Configuration
bocal.toml lives at the project root and is optional — bocal works with defaults and CLI flags. A global ~/.config/bocal/config.toml can hold cross-project registry definitions; project config overrides global by name.
store = ".bocal" # local fixture store (default)
env_out = ".bocal.env" # file restore writes [env] to (default)
# undo_keep = 3 # how many `restore --backup` undo sets to keep per
# # fixture (default 3; 0 disables pruning)
# divergence_warn_secs = 3600 # warn if a tag's services were captured more than
# # this far apart (default 3600 = 1h)
# template_env: shell env vars allowed inside {{ }} placeholders in [env].
# Resolved service ports/hosts and BOCAL_* are always available; this adds
# named shell vars. Arbitrary shell env is never read.
# template_env = ["APP_ENV", "API_BASE_URL"]
# Named registries. "default" is used when --registry is omitted.
[registries.default]
bucket = "s3://my-team-bocal"
region = "us-east-1"
# prefix = "myproject/" # optional key prefix inside the bucket
# endpoint = "..." # S3-compatible endpoint (R2, MinIO, …)
# path_style = false # addressing (see below)
# profile = "..." # AWS profile for this registry's creds (see below)
# Self-hosted MinIO with its own credentials via an AWS profile
[registries.staging]
bucket = "s3://my-team-bocal-staging"
endpoint = "https://my-minio.internal:9000"
region = "us-east-1" # MinIO ignores it, but the S3 client requires one
path_style = true
profile = "minio-staging"
Credentials
Credentials follow the standard AWS chain: env vars (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY), ~/.aws/credentials, instance role. No credentials are ever stored in a bocal file — which is why bocal.toml is safe to commit.
Per-registry credentials (profile)
The bare AWS chain resolves one identity per process, which isn't enough when different registries need different credentials (AWS for default, MinIO keys for staging, an R2 token elsewhere). A registry block may name an AWS profile:
[registries.staging]
bucket = "s3://team-staging"
endpoint = "https://minio.internal:9000"
profile = "minio-staging" # selects this identity from ~/.aws/credentials
with the identity in the standard AWS file:
# ~/.aws/credentials
[minio-staging]
aws_access_key_id = minioadmin
aws_secret_access_key = ...
Resolution per operation: the registry's profile → AWS_PROFILE → the default chain. The profile only selects which credentials the chain reads — bocal stores no secret, so the block stays committable.
Addressing (path_style)
The S3 client can address a bucket two ways:
- Virtual-hosted (
https://<bucket>.host/<key>) — AWS S3 and Cloudflare R2 default. - Path-style (
https://host/<bucket>/<key>) — required by MinIO and most self-hosted gateways.
Resolution: explicit path_style in the block wins; otherwise it's auto-enabled when endpoint is set (the MinIO/self-hosted signal) and off for AWS/R2. A bucket name containing dots also forces path-style (TLS-cert mismatch on virtual-hosted).
Region
Required by the S3 client even for providers that ignore it (MinIO). When an endpoint is set and region is omitted, bocal defaults to us-east-1. For AWS, region (or AWS_REGION) must match the bucket's real region.
Validation
bocal validates a registry on first use with a cheap HeadBucket — surfacing endpoint/credential/addressing/profile misconfiguration as a single actionable error rather than a cryptic mid-upload failure. bocal registry add runs the same check at add time.
Environment variables
| Variable | Purpose |
|---|---|
BOCAL_STORE | Override the default store path. |
BOCAL_REGISTRY | Default registry name. |
BOCAL_WORKTREE | Worktree root for [[files]] (overridden by --worktree; default cwd). |
BOCAL_USER | Identity for created_by/pushed_by (else git config user.email, else $USER). |
AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION, AWS_PROFILE | S3 credentials / region / profile. |
(each service's port_env) | Port for that service. |
(each service's host_env) | Host for that service (non-loopback needs --allow-remote). |
PGUSER, PGPASSWORD, PGDATABASE | Postgres connection. |
MYSQL_USER, MYSQL_PWD | MySQL/Dolt connection. |