Developer Environment Setup
Relevant source files
The following files were used as context for generating this wiki page:
The Harbor Satellite developer environment is designed to facilitate the development and testing of two primary components: the Satellite (edge-side registry) and Ground Control (cloud-side management). This setup supports multiple authentication workflows, including token-based Zero-Touch Registration (ZTR) and SPIFFE/SPIRE identity management, allowing developers to simulate edge-to-cloud artifact orchestration locally.
Sources: CLAUDE.md:1-12, QUICKSTART.md:1-15
Prerequisites and Tooling
To establish a functional development environment, several core tools and languages are required. The project utilizes Task as its primary build and orchestration tool.
| Tool | Version | Purpose |
|---|---|---|
| Go | 1.24.11+ | Primary programming language for both components |
| Task | 3.x | Task runner for builds, tests, and deployment |
| Docker | Latest | Containerization for components and E2E stacks |
| Dagger | Latest | CI/CD automation and local build execution |
| golangci-lint | v2.0.2 | Code linting and quality enforcement |
| PostgreSQL | 13+ | Database for Ground Control state management |
Sources: Taskfile.yml:4-10, taskfile-readme.md:5-13, QUICKSTART.md:6-12
Component Architecture Overview
The repository is structured as a Go workspace containing two distinct modules. Developers must be aware of the module boundaries when managing dependencies or running tests.
The architecture separates edge synchronization (Satellite) from fleet management (Ground Control).
Sources: CLAUDE.md:62-95, README.md:104-125
Local Development Workflow
Building Components
Developers can build binaries directly using Go or via the provided Task and Dagger commands.
# Build both components for the current platform
task build
# Build specific components (Satellite or Ground Control)
task _build:satellite
task _build:ground-control
# Build using Dagger (consistent with CI)
dagger call build --source=. --component=satellite export --path=./bin
Sources: Taskfile.yml:25-30, taskfiles/build.yml:10-38, CLAUDE.md:18-24
Configuration
Ground Control Environment
Ground Control requires a .env file for local execution, primarily for database and Harbor connectivity.
HARBOR_URL=http://localhost:8080
HARBOR_USERNAME=admin
HARBOR_PASSWORD=Harbor12345
DB_HOST=127.0.0.1
DB_PORT=5432
DB_DATABASE=groundcontrol
Sources: deploy/no-spiffe/quickstart.md:30-45, scripts/local-test.sh:65-79
Satellite Configuration
The Satellite uses a config.json file for its runtime settings, which can be hot-reloaded. Key sections include app_config for Ground Control connectivity and zot_config for the embedded OCI registry.
Sources: CLAUDE.md:106-115, pkg/config/validate.go:10-30
Testing and Quality Assurance
Linting and Security
The project enforces strict linting rules, including limits on function length (100 lines) and cyclomatic complexity.
# Run standard linting
task lint
# Run vulnerability checks
task vuln
Sources: Taskfile.yml:37-50, CLAUDE.md:41-45
End-to-End (E2E) Testing
The E2E suite automates the creation of a full stack including Harbor, Ground Control, and Satellite.
Authentication Setups
Developers can choose between two primary authentication environments:
1. Token-Based ZTR
The simplest setup for local development. It uses one-time tokens generated by the Ground Control API.
- Workflow: Register satellite via API -> Receive Token -> Start Satellite with
--tokenflag.
Sources: deploy/no-spiffe/quickstart.md:110-125, QUICKSTART.md:20-30
2. SPIFFE/SPIRE Setup
Recommended for simulating production-like zero-trust environments.
- Requires running a SPIRE server and agents.
- Task commands available for generating local CA certificates and bootstrapping the SPIRE stack:
task e2e-spiffe.
Sources: QUICKSTART.md:32-45, taskfiles/e2e.yml:50-100
Summary
The Harbor Satellite development environment provides a comprehensive toolkit for managing edge registry lifecycles. By leveraging Go, Task, and Docker, developers can transition from simple token-based testing to complex SPIFFE-authenticated fleet simulations within a single local environment.
Sources: README.md:10-25, CLAUDE.md:13-17