local-registry

Start and manage a local OCI registry for Bottlerocket kit development

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026

When & Why to Use This Skill

This Claude skill enables developers to efficiently start and manage a local OCI registry specifically for Bottlerocket kit development. It streamlines the local development lifecycle by allowing users to build, publish, and test kits in an isolated environment, eliminating the dependency on external registries and improving iteration speed.

Use Cases

  • Local Kit Development: Building and publishing Bottlerocket kits locally to accelerate the development and debugging cycle.
  • Offline Testing: Testing kit changes and variant compatibility in isolated or air-gapped environments without internet access.
  • Pre-production Validation: Verifying the integrity of kit builds and configurations before pushing them to production OCI registries.
  • Environment Consistency: Ensuring a standardized local registry setup across a development team using predefined Docker configurations.
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

Procedure

Start the registry

(cd $FOREST_ROOT && 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

(cd $FOREST_ROOT && brdev registry status)

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

View registry logs

(cd $FOREST_ROOT && brdev registry logs)

To follow logs in real-time:

(cd $FOREST_ROOT && brdev registry logs --follow)

Stop the registry

(cd $FOREST_ROOT && brdev registry stop)

Note: This preserves the registry data volume.

Clean registry data

(cd $FOREST_ROOT && brdev registry clean)

This removes both the container and the data volume.

Configuration

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

# Custom port (default: 5000, minimum: 1024)
FORESTER_REGISTRY_PORT=5001

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

Note: Container and volume names are automatically derived from the port as forester-registry-{port} and forester-registry-data-{port}.

Validation

After starting the registry:

curl http://localhost:5000/v2/_catalog

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