local-registry

cbgbt's avatarfrom cbgbt

Start and manage a local OCI registry for Bottlerocket kit development

⭐3stars🔀4forks📁View on GitHub🕐Updated Dec 19, 2025⬇️7downloads

When & Why to Use This Skill

This Claude skill enables developers to seamlessly start and manage a local OCI (Open Container Initiative) registry specifically designed for Bottlerocket kit development. By facilitating local builds and publishing, it eliminates the need for external registry access, streamlines the testing of kit changes, and supports fully offline or isolated development workflows.

Use Cases

  • Local Kit Iteration: Build and publish Bottlerocket kits to a local registry to verify changes before pushing to production environments.
  • Offline Development: Continue containerized infrastructure development in air-gapped environments or locations with limited internet connectivity.
  • Automated Testing: Integrate local registry management into development scripts to verify kit compatibility and variant integration automatically.
  • Environment Cleanup: Easily reset development environments by stopping registries and cleaning persistent data volumes with simple commands.
namelocal-registry
descriptionStart and manage a local OCI registry for Bottlerocket kit development

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
  • build-kit-locally - Uses local registry to publish built kits
  • build-variant-from-local-kits - Configures variant builds to use local registry

See Also

Configuration commands for local registry usage:

For publishing kits:

  • brdev twoliter use-local-publish - Create Infra.toml for publishing to local registry
  • brdev twoliter use-upstream-publish - Remove Infra.toml

For fetching kits:

  • brdev twoliter use-local-deps - Create Twoliter.override for fetching from local registry
  • brdev twoliter use-upstream-deps - Remove Twoliter.override

Both (convenience):

  • brdev twoliter use-local - Create both files
  • brdev twoliter use-upstream - Remove both files

When fetching, also set vendor = "local" in Twoliter.toml for specific kits you want from the local registry.