Skill: Local OCI Registry Skill

Skill: Local OCI Registry

Purpose

Start and manage a local OCI registry for development. This allows building and publishing kits locally without requiring external registry access.

When to Use

Developing changes to kits that need to be consumed by variants
Testing kit changes before publishing to production registries
Working offline or in isolated environments

Prerequisites

Docker installed and running
Working from within a grove directory

Procedure

Start the registry

brdev registry start

This will:

Start a local Docker registry on localhost:5000
Configure persistence (registry data survives restarts)
Wait for the registry to be healthy before returning
Output the registry URL for use in builds

Verify registry is running

brdev registry status

Returns exit code 0 if running, non-zero otherwise.

Get registry URL

brdev registry url

Outputs localhost:{port} for the current grove. Use this in scripts instead of hardcoding ports.

View registry logs

brdev registry logs

To follow logs in real-time:

brdev registry logs --follow

Stop the registry

brdev registry stop

Note: This preserves the registry data volume.

Clean registry data

brdev registry clean

This removes both the container and the data volume.

Configuration

brdev uses environment variables for configuration. Create a .env file in the forest root or set environment variables:

# Custom image (default: registry:2)
BRDEV_REGISTRY_IMAGE=registry:2.8

Note: Container and volume names are automatically derived from the grove name as brdev-registry-{grove} and brdev-registry-data-{grove}. The port is auto-derived from a hash of the grove name (range 5001-5999).

Validation

After starting the registry:

brdev registry list

Should return: {"repositories":[]}

Common Issues

Docker not installed:

Error: Docker is not installed or not in PATH. Install Docker and ensure it's in your PATH

Solution: Install Docker and ensure it's in your PATH.

Docker daemon not running:

Error: Docker daemon is not running. Start Docker with: sudo systemctl start docker

Solution: Start the Docker daemon.

Port already in use:

Error: Failed to start container. The port may already be in use

Solution:

Check for existing registry: docker ps | grep registry
Stop conflicting container: docker stop <container-id>
Or use a custom port via FORESTER_REGISTRY_PORT

Permission denied:

Ensure user is in docker group: groups | grep docker
Add user to docker group: sudo usermod -aG docker $USER
May need to restart shell after adding to group

Related Skills

build-kit-locally - Uses local registry to publish built kits
build-variant-from-local-kits - Configures variant builds to use local registry

Agent Skills: Skill: Local OCI Registry

Skill Files