Feature Installer

A command-line tool for installing devcontainer features from OCI registries or local directories.

Features

• 🚀 Install features from GitHub Container Registry (ghcr.io)
• 📁 Install features from local directories
• 🔗 Automatic dependency resolution with topological sorting
• ⚙️ Flexible option configuration and merging
• 🧪 Comprehensive test coverage

Installation

From Release

Download the latest binary from the releases page.

From Source

go install github.com/devcontainer-community/feature-installer@latest

Development Build

git clone https://github.com/devcontainer-community/feature-installer.git
cd feature-installer
make build

Usage

Install Feature from OCI Registry

# Install a feature from GitHub Container Registry
feature-installer feature install ghcr.io/bascodes/devcontainer-features/debug-dump-env:1

# Install with custom options
feature-installer feature install ghcr.io/example/feature:latest --option key=value

Install Local Feature

# Install from local directory
feature-installer feature install ./my-feature

# Install with options
feature-installer feature install ./my-feature --option enableFeature=true --option version=1.2.3

Multiple Features with Dependencies

The tool automatically resolves dependencies and installs features in the correct order:

feature-installer feature install feature-a feature-b feature-c

Development

Prerequisites

• Go 1.23+
• Make (optional, for convenience commands)

Quick Start

# Clone and setup
git clone https://github.com/devcontainer-community/feature-installer.git
cd feature-installer
make deps

# Run tests
make test

# Run all checks (format, vet, test)
make check

# Build
make build

Available Make Targets

make help          # Show all available targets
make build         # Build the binary
make test          # Run tests
make test-coverage # Run tests with coverage report
make lint          # Run linting (requires golangci-lint)
make fmt           # Format code
make vet           # Run go vet
make check         # Run format, vet, and tests
make ci-local      # Run CI checks locally
make clean         # Clean build artifacts

Architecture

The feature installer follows this flow:

1. Command Parsing: CLI arguments and options are parsed using Cobra
2. Feature Detection: Determines if features are OCI references or local directories
3. Dependency Resolution: Uses graph-based topological sorting to determine installation order
4. OCI Download: Downloads and extracts features from container registries using ORAS
5. Installation: Executes install.sh scripts with environment variables from user options

Key Components

• cmd/: CLI command definitions and argument parsing
• internal/featureinstaller/: Core installation logic and dependency resolution
• internal/featureinstaller/oci/: OCI registry operations and artifact handling
• internal/featureinstaller/directory/: Local directory feature installation
• internal/devcontainer/schemas/: JSON schema parsing for devcontainer features

Testing

The project has comprehensive test coverage including:

• Unit Tests: Test individual components in isolation
• Integration Tests: End-to-end testing with real feature installations
• Test Fixtures: Reusable test features for various scenarios

# Run all tests
go test ./...

# Run with coverage
make test-coverage

# Run specific test package
go test ./internal/featureinstaller/...

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run tests (make check)
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

Code Quality

This project uses automated CI checks:

• Go formatting with gofmt
• Static analysis with go vet
• Testing with race detection
• Build verification across multiple platforms
• Security scanning with Trivy

All checks must pass before PRs can be merged.

License

This project is licensed under the MIT License.

Related Projects

• Dev Container Features
• Dev Container CLI
• ORAS Go Library