Getting Started

Harbor is an open source container registry that stores, signs and serves container images and OCI artifacts, with projects and role-based access control. Available as an open web service in Eyevinn Open Source Cloud, it runs as a single instance with the web portal, the registry and the job service built in. This tutorial walks you through the steps to get started.

Storage: 50 GiB persistent volume per instance. Images are stored there by default. You can optionally use an S3-compatible bucket instead (see Configuration).

Prerequisites

  • If you have not already done so, sign up for an Eyevinn OSC account
  • Docker (or another OCI client) on your machine to push and pull images

Harbor needs two dependencies that must exist before you create the Harbor instance: a PostgreSQL database and a Valkey (Redis compatible) instance.

Step 1: Create a PostgreSQL database

Navigate to the PostgreSQL service (see Service: PostgreSQL) and create an instance with a database name, for example harbor. The database must already exist, Harbor does not create it.

Open the instance details and note the internal cluster hostname. Use that hostname and port 5432 to build the database URL:

postgres://<user>:<password>@<internal-hostname>:5432/harbor?sslmode=disable

Only the sslmode query parameter is used. If the password contains special characters, percent-encode them in the URL.

Step 2: Create a Valkey instance

Create a Valkey instance (see Service: Valkey) with a password. Use the internal hostname, port 6379 and the password to build the Redis URL:

redis://:<password>@<internal-hostname>:6379

Harbor uses database indexes 0, 1 and 2 itself, so a database index in the URL is ignored. Do not share one Valkey instance between two Harbor instances.

Step 3: Store sensitive values as secrets

Navigate to the Harbor service and go to the "Service Secrets" tab. Click "New Secret" and create:

  • harbordburl: the full PostgreSQL URL from Step 1
  • harborredisurl: the full Redis URL from Step 2
  • harboradminpw: the password for the Harbor admin user

A {{secrets.NAME}} reference only works when it is the entire field value, so each URL must be stored whole as one secret. Keep a copy of the admin password somewhere safe, it cannot be read back from the service later.

Step 4: Create the Harbor instance

Go to the "My harbor" tab and click "Create harbor". Fill in:

  • Name: a name for your instance (alphanumeric only)
  • DatabaseUrl: {{secrets.harbordburl}}
  • RedisUrl: {{secrets.harborredisurl}}
  • AdminPassword: {{secrets.harboradminpw}}

Leave the other options empty to store images on the persistent volume.

The instance shows as running after about 10 seconds, but Harbor runs database migrations on first start and only answers after about 30 to 40 seconds. Wait before you log in.

Step 5: Log in

Open the instance URL in your browser and sign in as user admin with the password you stored in harboradminpw.

Create a project (for example library) in the web UI before pushing images.

Harbor does its own authentication, so all paths on the instance URL are reachable and standard Docker clients work.

Usage Example

Push and pull an image with Docker. Replace the placeholders with your instance host name (without https://) and project name:

docker login <instance-host> -u admin
docker pull alpine:3.20
docker tag alpine:3.20 <instance-host>/<project>/alpine:t1
docker push <instance-host>/<project>/alpine:t1
docker pull <instance-host>/<project>/alpine:t1

The image then shows up in the project in the web UI. No HTTPS configuration is needed, OSC terminates TLS in front of the instance.

Configuration

Option Required Description
name Yes Instance name, alphanumeric only
DatabaseUrl Yes PostgreSQL URL postgres://user:password@host:5432/dbname?sslmode=disable. The database must already exist. Store as a secret.
RedisUrl Yes Valkey URL redis://:password@host:6379. Any database index in the URL is ignored. Store as a secret.
AdminPassword Yes Password for the admin user. Only applied when Harbor initialises a new database, changing it later has no effect. Store as a secret.
StorageBackend No filesystem (default, persistent volume) or s3
S3Endpoint With s3 URL of the S3-compatible endpoint
S3Bucket With s3 Name of the bucket
S3AccessKey With s3 Access key. Store as a secret.
S3SecretKey With s3 Secret key. Store as a secret.

Limitations

  • Single instance, no high availability.
  • Trivy vulnerability scanning, SBOM scanning and the metrics exporter are not included in this build.
  • The initial admin password cannot be read back from the service. Keep a copy of it.
  • Webhooks to private or internal addresses are rejected by default.
  • Not tested on OSC: replication, proxy cache, OIDC and LDAP authentication, retention policies, garbage collection and webhooks.
  • The S3 storage backend has not been tested on OSC, and not against MinIO.

Resources