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 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.
| 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
- 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 kitsbuild-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- CreateInfra.tomlfor publishing to local registrybrdev twoliter use-upstream-publish- RemoveInfra.toml
For fetching kits:
brdev twoliter use-local-deps- CreateTwoliter.overridefor fetching from local registrybrdev twoliter use-upstream-deps- RemoveTwoliter.override
Both (convenience):
brdev twoliter use-local- Create both filesbrdev twoliter use-upstream- Remove both files
When fetching, also set vendor = "local" in Twoliter.toml for specific kits you want from the local registry.