Quickstart Guide
Relevant source files
The following files were used as context for generating this wiki page:
Harbor Satellite is a registry fleet management and artifact distribution solution that extends the Harbor container registry to edge computing environments. It consists of two primary components: the Satellite, a lightweight registry running at edge locations, and Ground Control, a cloud-side management service for device onboarding and state orchestration.
The goal of this guide is to provide a standardized path for deploying these components and establishing a secure connection between them. The project supports two main authentication paradigms: Token-based Zero-Touch Registration (ZTR) for development and SPIFFE/SPIRE-based cryptographic identity for production-grade zero-trust environments.
Sources: CLAUDE.md:8-12, QUICKSTART.md:3-5
Authentication Paradigms
Harbor Satellite allows administrators to choose the authentication method that best fits their deployment scale and security requirements.
| Method | Description | Infrastructure Req. | Security Model |
|---|---|---|---|
| Token-based ZTR | Simple one-time token authentication. | Ground Control + Database | Shared Secret (Token) |
| SPIFFE/SPIRE | Cryptographic identity via X.509 SVIDs. | GC + SPIRE Server + Agents | Zero-Trust (mTLS) |
Sources: QUICKSTART.md:14-41, deploy/quickstart/README.md:16-24
Token-based ZTR (Development/Testing)
This method is recommended for local development, CI/CD, and quick testing. It utilizes a single-use token with a configurable TTL to bootstrap the satellite.
1. Ground Control Setup
Ground Control requires a PostgreSQL database and environment configuration for Harbor connectivity.
- Create a
.envfile in theground-controldirectory. - Define
HARBOR_URL,HARBOR_USERNAME, andHARBOR_PASSWORD. - Start the service using Docker Compose:
docker compose up.
Sources: deploy/no-spiffe/quickstart.md:21-65, CLAUDE.md:65-68
2. Group and Config Management
Before a satellite can be registered, you must define what it will host and how it will behave.
- Groups: Collections of container images (repository, tag, digest) for replication.
- Configs: JSON artifacts defining Ground Control URLs, replication intervals, and local registry (Zot) settings.
Sources: deploy/no-spiffe/quickstart.md:80-143, CLAUDE.md:88-92
3. Satellite Registration
Register the satellite via the Ground Control API to obtain an authentication token.
curl --location 'http://localhost:8080/satellites' \
--header 'Content-Type: application/json' \
--data '{
"name": "satellite_1",
"groups": ["group1"],
"config_name": "config1"
}'
Sources: deploy/no-spiffe/quickstart.md:145-160
SPIFFE/SPIRE (Production/Fleet)
For production, Harbor Satellite uses the SPIFFE framework to provide zero-trust identity. SPIRE handles the issuance and automatic rotation of X.509 certificates used for mutual TLS (mTLS) between Satellites and Ground Control.
SPIFFE Architecture
The following diagram illustrates the relationship between SPIRE components and the Satellite ecosystem:
Note: SPIRE Server acts as the central identity authority, while agents on each node attest the workloads (GC and Satellite).
Sources: QUICKSTART.md:27-39, deploy/quickstart/spiffe/README.md:41-55
Attestation Methods
SPIFFE requires "attestation" to prove the identity of a node. Supported methods include:
- Join Token: One-time tokens from SPIRE server (simplest for SPIFFE setup).
- X.509 PoP: Uses pre-provisioned X.509 certificates.
- SSH PoP: Uses SSH host certificates.
Sources: deploy/quickstart/spiffe/README.md:7-13, deploy/quickstart/README.md:11-15
Core Service Endpoints
When deploying the quickstart environment, the following default ports are utilized for component communication:
| Component | Default Port | Description |
|---|---|---|
| Ground Control | 8080 / 9080 | Fleet management API (HTTP/HTTPS) |
| SPIRE Server | 8081 | Central identity authority |
| PostgreSQL | 5432 | Ground Control metadata database |
| Local Registry (Zot) | 8585 | The OCI-compliant registry on the Satellite |
| Mock Harbor | 5000 | Simulated upstream registry for quickstart |
Sources: deploy/quickstart/README.md:28-34, deploy/quickstart/common/docker-compose.base.yml:26-33, deploy/no-spiffe/quickstart.md:112-120
Operational Workflow
The standard operational flow for a new Satellite deployment follows these steps:
- Onboarding: The Satellite registers with Ground Control (via token or SPIFFE ID).
- State Sync: The Satellite fetches the "Desired State" (a list of artifacts and configurations) from Ground Control.
- Replication: The Satellite replicates images from the central Harbor registry to its local Zot registry.
- Runtime Integration: The Satellite configures local container runtimes (Docker, containerd, etc.) to use the local registry as a mirror.
Summary
This quickstart infrastructure allows users to evaluate Harbor Satellite's ability to manage edge registries. By choosing between simple token-based ZTR or secure SPIFFE/SPIRE mTLS, users can transition from local development to production fleet management. Successful setup results in a Satellite that synchronizes with a central Harbor instance and serves artifacts locally to edge workloads, even in intermittent connectivity scenarios.
Sources: README.md:14-25, QUICKSTART.md:3-8