local-registry
Start and manage a local OCI registry for Bottlerocket kit development
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.
| name | local-registry |
|---|---|
| description | Start 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
Related Skills
build-and-publish-kit- Uses local registry to publish built kitsbuild-variant- Configures variant builds to use local registry