Docker/OCI Registry Guide

Artifact Keeper provides a fully compliant OCI Distribution Specification registry for Docker and other container images.

Endpoint

All Docker/OCI operations use the /v2 endpoint, which implements the OCI Distribution Specification.

http://localhost:8080/v2

Configuration

Authenticate with your Artifact Keeper instance:

docker login localhost:8080

Enter your Artifact Keeper username and password when prompted.

Alternative: Token Authentication

You can also authenticate using a token:

echo $ARTIFACT_KEEPER_TOKEN | docker login localhost:8080 -u username --password-stdin

Pushing Images

Tag Your Image

First, tag your image with the Artifact Keeper registry URL:

docker tag myapp:latest localhost:8080/myapp:latest
docker tag myapp:latest localhost:8080/myapp:1.0.0

Push to Registry

Push your tagged images:

docker push localhost:8080/myapp:latest
docker push localhost:8080/myapp:1.0.0

Pulling Images

Pull images from your Artifact Keeper registry:

docker pull localhost:8080/myapp:latest
docker pull localhost:8080/myapp:1.0.0

Multi-Architecture Images

Artifact Keeper supports multi-architecture manifests for cross-platform container images.

Create Multi-Arch Manifest

# Build for multiple architectures
docker buildx build --platform linux/amd64,linux/arm64 \
  -t localhost:8080/myapp:1.0.0 \
  --push .

Inspect Manifests

docker manifest inspect localhost:8080/myapp:1.0.0

Tag Management

Use the OCI API to list all tags for an image:

curl http://localhost:8080/v2/myapp/tags/list

Response:

{
  "name": "myapp",
  "tags": ["latest", "1.0.0", "1.0.1"]
}

Delete Tags

Delete a specific tag:

# Get the digest
DIGEST=$(docker inspect --format='{{index .RepoDigests 0}}' localhost:8080/myapp:1.0.0 | cut -d@ -f2)

# Delete by digest
curl -X DELETE http://localhost:8080/v2/myapp/manifests/$DIGEST

Repository Namespacing

Organize images using repository paths:

# Push to namespaced repository
docker tag myapp:latest localhost:8080/team/project/myapp:latest
docker push localhost:8080/team/project/myapp:latest

# Pull from namespaced repository
docker pull localhost:8080/team/project/myapp:latest

Best Practices

Use Semantic Versioning

Tag images with semantic versions for better tracking:

docker tag myapp:latest localhost:8080/myapp:1.2.3
docker push localhost:8080/myapp:1.2.3

Immutable Tags

Avoid overwriting existing tags. Use unique version tags for each build:

# Good: unique version
docker push localhost:8080/myapp:1.2.3-build.42

# Avoid: reusing same tag
docker push localhost:8080/myapp:latest  # overwrites previous latest

Layer Caching

Artifact Keeper deduplicates image layers across repositories, saving storage space automatically.

Integration with CI/CD

GitHub Actions Example

name: Build and Push
on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Login to Artifact Keeper
        uses: docker/login-action@v3
        with:
          registry: registry.example.com
          username: ${{ secrets.REGISTRY_USERNAME }}
          password: ${{ secrets.REGISTRY_PASSWORD }}

      - name: Build and push
        uses: docker/build-push-action@v5
        with:
          push: true
          tags: |
            registry.example.com/myapp:latest
            registry.example.com/myapp:${{ github.sha }}

GitLab CI Example

build:
  stage: build
  image: docker:latest
  services:
    - docker:dind
  before_script:
    - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD registry.example.com
  script:
    - docker build -t registry.example.com/myapp:$CI_COMMIT_SHA .
    - docker push registry.example.com/myapp:$CI_COMMIT_SHA

Troubleshooting

TLS Certificate Errors

If using self-signed certificates, configure Docker to trust them:

# Add certificate to Docker
sudo mkdir -p /etc/docker/certs.d/localhost:8080
sudo cp ca.crt /etc/docker/certs.d/localhost:8080/ca.crt
sudo systemctl restart docker

Or use insecure registry (development only):

{
  "insecure-registries": ["localhost:8080"]
}

Authentication Failures

Verify credentials and token expiration:

# Check authentication
curl -u username:password http://localhost:8080/v2/

Expected response: {}

Storage Issues

Monitor available storage space and configure retention policies in Artifact Keeper to automatically clean up old images.

Advanced Features

Content Addressability

All images are stored by their SHA256 digest, ensuring integrity:

# Pull by digest for reproducible builds
docker pull localhost:8080/myapp@sha256:abc123...

Garbage Collection

Artifact Keeper automatically removes unreferenced layers. Configure cleanup policies in the admin UI.

Rate Limiting

Configure rate limits per user or repository to prevent abuse:

# Check rate limit headers
curl -I http://localhost:8080/v2/myapp/manifests/latest