mirror of
https://github.com/nickyeoman/docker-compose-cookbooks.git
synced 2026-09-03 18:36:22 +00:00
118 lines
4.4 KiB
Markdown
118 lines
4.4 KiB
Markdown
# Harbor
|
|
|
|
Harbor is a self-hosted OCI container image registry with vulnerability scanning, image signing, replication, and RBAC — basically a private Docker Hub. Its compose file is generated by Harbor's own installer from `harbor.yml`, so a static `compose.yaml` in this repo would drift immediately (~10 tightly-coupled services: core, registry, database, redis, jobservice, portal, trivy, nginx, etc). Use the official installer instead of hand-rolling compose. See `container-requests.md` for the "will not be in the repo" rationale.
|
|
|
|
- Project Repository: https://github.com/goharbor/harbor
|
|
- Documentation: https://goharbor.io/docs/
|
|
- Releases (installer download): https://github.com/goharbor/harbor/releases
|
|
|
|
## Tutorial: Installing Harbor
|
|
|
|
### 1. Prerequisites
|
|
|
|
- Docker Engine 20.10.10+ and Docker Compose 2.0.0+ on the host
|
|
- A domain name (or IP) that will be Harbor's registry hostname
|
|
- A TLS certificate, or be prepared to run without HTTPS on a trusted internal network only (Docker refuses to talk to an insecure registry over plain HTTP unless explicitly configured)
|
|
|
|
### 2. Download the offline installer
|
|
|
|
```bash
|
|
cd /opt
|
|
wget https://github.com/goharbor/harbor/releases/download/v2.11.1/harbor-offline-installer-v2.11.1.tgz
|
|
tar xzvf harbor-offline-installer-v2.11.1.tgz
|
|
cd harbor
|
|
```
|
|
|
|
Check the [releases page](https://github.com/goharbor/harbor/releases) for the current version.
|
|
|
|
### 3. Configure `harbor.yml`
|
|
|
|
```bash
|
|
cp harbor.yml.tmpl harbor.yml
|
|
nano harbor.yml
|
|
```
|
|
|
|
Key fields to set:
|
|
|
|
```yaml
|
|
hostname: registry.example.com # the domain or IP clients will use
|
|
|
|
http:
|
|
port: 80
|
|
|
|
https:
|
|
port: 443
|
|
certificate: /your/certificate/path
|
|
private_key: /your/private/key/path
|
|
|
|
harbor_admin_password: ChangeThisPassword
|
|
|
|
data_volume: /data/harbor
|
|
|
|
database:
|
|
password: ChangeThisPassword
|
|
```
|
|
|
|
If you don't have a certificate yet, comment out the entire `https:` block and drop `https` from downstream instructions — but note Docker clients will then need `insecure-registries` configured to push/pull (see step 6).
|
|
|
|
### 4. Run the installer
|
|
|
|
```bash
|
|
sudo ./install.sh
|
|
```
|
|
|
|
This generates `docker-compose.yml` from `harbor.yml` and brings the stack up. Optional flags:
|
|
|
|
```bash
|
|
sudo ./install.sh --with-trivy # image vulnerability scanning
|
|
sudo ./install.sh --with-chartmuseum # Helm chart repository (deprecated upstream, skip for new installs)
|
|
```
|
|
|
|
### 5. Log in to the UI
|
|
|
|
Open `https://registry.example.com` and log in as `admin` with the password set in `harbor_admin_password`. Immediately:
|
|
|
|
1. Create a new project (e.g. `homelab`) — set it Private or Public
|
|
2. Create additional users under Administration → Users, or configure LDAP/OIDC
|
|
|
|
### 6. Push and pull images
|
|
|
|
```bash
|
|
docker login registry.example.com
|
|
docker tag myapp:latest registry.example.com/homelab/myapp:latest
|
|
docker push registry.example.com/homelab/myapp:latest
|
|
|
|
# on another machine:
|
|
docker pull registry.example.com/homelab/myapp:latest
|
|
```
|
|
|
|
If running without TLS, add the registry to `/etc/docker/daemon.json` on every client first:
|
|
|
|
```json
|
|
{
|
|
"insecure-registries": ["registry.example.com:80"]
|
|
}
|
|
```
|
|
|
|
then `sudo systemctl restart docker`.
|
|
|
|
### 7. Use it as a pull-through cache / replication target (optional)
|
|
|
|
Administration → Registries lets you add Docker Hub (or another registry) as an endpoint, then Administration → Replications to mirror images in on a schedule — useful for caching frequently-pulled base images locally.
|
|
|
|
### 8. Day-2 operations
|
|
|
|
```bash
|
|
cd /opt/harbor
|
|
sudo docker compose down
|
|
sudo ./install.sh # re-run after editing harbor.yml to regenerate and restart
|
|
```
|
|
|
|
Back up `data_volume` (default `/data/harbor`) and the Postgres data inside it before any upgrade. Upgrades are major-version-specific — always read the [upgrade guide](https://goharbor.io/docs/edge/administration/upgrade/) for your version jump, don't just re-run the new installer over old data blindly.
|
|
|
|
## Gotchas
|
|
|
|
- Trivy's vulnerability database downloads on first scan and needs outbound internet access; air-gapped installs need `--with-trivy` plus manually seeding the DB.
|
|
- The installer's generated `docker-compose.yml` is meant to be managed by `install.sh`, not edited by hand — re-running the installer after config changes is the supported workflow.
|
|
- Harbor's own `database` and `redis` containers store state locally by default; point `harbor.yml` at external Postgres/Redis instead if you already run those services elsewhere.
|