Configuration

vcpkg-harbor is configured through environment variables. All variables are prefixed with VCPKG_.

Configuration File

Create a .env file in your project directory:

# Copy the example configuration
cp .env.example .env

Server Settings

Variable	Default	Description
`VCPKG_SERVER_HOST`	`0.0.0.0`	Host to bind the server to
`VCPKG_SERVER_PORT`	`15151`	Port to bind the server to
`VCPKG_SERVER_WORKERS`	`1`	Number of worker processes
`VCPKG_SERVER_RELOAD`	`false`	Enable auto-reload (development)
`VCPKG_SERVER_READ_ONLY`	`false`	Run in read-only mode
`VCPKG_SERVER_WRITE_ONLY`	`false`	Run in write-only mode

Storage Settings

Variable	Default	Description
`VCPKG_STORAGE_TYPE`	`minio`	Storage backend: `minio`, `filesystem`, `s3`, `azure`, `gcs`
`VCPKG_STORAGE_PATH`	`./cache`	Path for filesystem storage

MinIO Settings

Variable	Default	Description
`VCPKG_MINIO_ENDPOINT`	`localhost:9000`	MinIO server endpoint
`VCPKG_MINIO_ACCESS_KEY`	`minioadmin`	Access key
`VCPKG_MINIO_SECRET_KEY`	`minioadmin`	Secret key
`VCPKG_MINIO_BUCKET`	`vcpkg-harbor`	Bucket name
`VCPKG_MINIO_SECURE`	`false`	Use HTTPS

AWS S3 Settings

Variable	Default	Description
`VCPKG_S3_BUCKET`	`vcpkg-harbor`	S3 bucket name
`VCPKG_S3_REGION`	`us-east-1`	AWS region
`VCPKG_S3_ACCESS_KEY_ID`	-	AWS access key ID
`VCPKG_S3_SECRET_ACCESS_KEY`	-	AWS secret access key
`VCPKG_S3_ENDPOINT_URL`	-	Custom S3 endpoint (for S3-compatible services)

Azure Blob Settings

Variable	Default	Description
`VCPKG_AZURE_CONNECTION_STRING`	-	Azure connection string
`VCPKG_AZURE_ACCOUNT_NAME`	-	Storage account name
`VCPKG_AZURE_ACCOUNT_KEY`	-	Storage account key
`VCPKG_AZURE_CONTAINER`	`vcpkg-harbor`	Container name

Google Cloud Storage Settings

Variable	Default	Description
`VCPKG_GCS_BUCKET`	`vcpkg-harbor`	GCS bucket name
`VCPKG_GCS_PROJECT`	-	GCP project ID
`VCPKG_GCS_CREDENTIALS_FILE`	-	Path to service account JSON

Build Tag Settings

Build tags let independent build streams share one server while keeping separate views of the cache. See Build Tags for the full picture.

Variable	Default	Description
`VCPKG_TAGS_ENABLED`	`true`	Accept an optional build tag as the first path segment. `false` restores the pre-tag behaviour exactly
`VCPKG_TAGS_ALLOWED`	-	Comma-separated allowlist of tag names. Empty means any name matching the pattern is accepted
`VCPKG_TAGS_PATTERN`	`^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$`	Regular expression every tag name must match
`VCPKG_TAGS_DEFAULT_NAMESPACE`	`_default`	Namespace name used for untagged (4 segment) requests
`VCPKG_TAGS_DEDUPE`	`true`	Store each package once and let tags reference it with reference counting. `false` gives every tag a private copy
`VCPKG_TAGS_MAX_PACKAGES_PER_TAG`	`0`	Maximum number of packages kept per tag (`0` = unlimited)
`VCPKG_TAGS_MAX_BYTES_PER_TAG`	`0`	Maximum total package size kept per tag in bytes (`0` = unlimited)

Logging Settings

Variable	Default	Description
`VCPKG_LOG_LEVEL`	`INFO`	Log level: DEBUG, INFO, WARNING, ERROR
`VCPKG_LOG_JSON`	`false`	Output logs in JSON format
`VCPKG_LOG_FILE`	`logs/vcpkg-harbor.log`	Log file path (null to disable)
`VCPKG_LOG_RETENTION_DAYS`	`30`	Log file retention period

Authentication Settings

Variable	Default	Description
`VCPKG_AUTH_ENABLED`	`false`	Enable authentication
`VCPKG_AUTH_TYPE`	`none`	Auth type: `none`, `token`, `basic`
`VCPKG_AUTH_TOKEN`	-	API token (for token auth)
`VCPKG_AUTH_BASIC_USERS`	-	User credentials (for basic auth)

Feature Flags

Variable	Default	Description
`VCPKG_METRICS_ENABLED`	`true`	Enable Prometheus metrics
`VCPKG_METRICS_PATH`	`/metrics`	Metrics endpoint path
`VCPKG_DASHBOARD_ENABLED`	`true`	Enable web dashboard
`VCPKG_DASHBOARD_PATH`	`/`	Dashboard base path
`VCPKG_DASHBOARD_ASSETS`	`local`	Where the dashboard loads Tailwind CSS and HTMX from: `local` (vendored under `/static`) or `cdn`

Reverse Proxy Settings

Needed when vcpkg-harbor is not served from the root of a domain, or when the dashboard is embedded in another page.

Variable	Default	Description
`VCPKG_PROXY_ROOT_PATH`	-	Path prefix the application is served under, e.g. `/harbor`. Equivalent to uvicorn’s `--root-path`
`VCPKG_PROXY_FORWARDED_ALLOW_IPS`	-	Client IPs trusted to send `X-Forwarded-` headers, or `` for any
`VCPKG_PROXY_FRAME_ANCESTORS`	-	`Content-Security-Policy: frame-ancestors` value, e.g. `'self' https://intranet.example.com`. Unset means no header, so any page may embed the dashboard
`VCPKG_PROXY_FRAME_OPTIONS`	-	`X-Frame-Options` value: `DENY` or `SAMEORIGIN`. Unset means no header

Serving under a sub-path

With VCPKG_PROXY_ROOT_PATH set, every link, asset and dashboard background request is generated with the prefix, so the dashboard also works inside an <iframe> on another page. Both common proxy layouts are supported - one that forwards the prefix and one that strips it:

# Forwards /harbor/... unchanged (recommended)
location /harbor/ {
    proxy_pass http://127.0.0.1:15151;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
}

# Strips the prefix before forwarding; note the trailing slash
location /harbor/ {
    proxy_pass http://127.0.0.1:15151/;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
}

Prefer the first form. A stripping proxy cannot be told apart from a genuine request when a cached package happens to be named after the prefix, so /harbor/1.0/<sha>/x64-linux would be read as the prefix plus a three-segment path and answered with 404.

Embedding without internet access

VCPKG_DASHBOARD_ASSETS=local, the default, serves Tailwind CSS and HTMX from /static, so the dashboard renders on an air-gapped host and inside a page served with a strict Content-Security-Policy (no inline scripts or styles and no third-party origins are needed). Set it to cdn to load both from jsDelivr instead, which compiles the stylesheet in the browser and therefore needs style-src 'unsafe-inline'.

Example Configurations

Production with S3

VCPKG_STORAGE_TYPE=s3
VCPKG_S3_BUCKET=my-vcpkg-cache
VCPKG_S3_REGION=us-west-2
VCPKG_AUTH_ENABLED=true
VCPKG_AUTH_TYPE=token
VCPKG_AUTH_TOKEN=your-secret-token
VCPKG_LOG_JSON=true

Development with Local Storage

VCPKG_STORAGE_TYPE=filesystem
VCPKG_STORAGE_PATH=./cache
VCPKG_LOG_LEVEL=DEBUG
VCPKG_SERVER_RELOAD=true

Shared Server with Build Streams

VCPKG_TAGS_ENABLED=true
VCPKG_TAGS_ALLOWED=nightly,release,ci
VCPKG_TAGS_MAX_PACKAGES_PER_TAG=500

Behind a Reverse Proxy, Dashboard Embedded in an Intranet Portal

VCPKG_PROXY_ROOT_PATH=/harbor
VCPKG_PROXY_FORWARDED_ALLOW_IPS=10.0.0.1
VCPKG_PROXY_FRAME_ANCESTORS="'self' https://portal.example.com"
VCPKG_DASHBOARD_ASSETS=local