Skip to content

Docker Integration Guide

Overview

OrbitRepos provides a high-performance Docker Registry V2 compliant interface. You can use it to host private images, proxy public registries like Docker Hub, and group multiple repositories under a single endpoint.

Prerequisites

  • Docker CLI installed on your machine.
  • An active OrbitRepos instance. See the Quick Start for setup instructions using Docker Compose.
  • Network access to http://localhost:8080.

Create a Repository

You can create a Docker repository via the Web UI or the Management API.

  1. Log in to OrbitRepos (default: admin/admin).
  2. Navigate to Repositories > Create Repository.
  3. Select Docker as the format.
  4. Choose a type: hosted, proxy, or group.
  5. Name it my-docker-hosted (for this guide).
curl -u admin:admin -X POST http://localhost:8080/api/v1/repositories \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-docker-hosted",
    "format": "docker",
    "type": "hosted"
  }'

Push / Publish Artifacts

Before pushing, you must authenticate the Docker CLI with your OrbitRepos instance.

docker login localhost:8080 -u admin -p admin

To push an image, tag it with the repository path and use docker push:

# Tag an existing image
docker tag nginx:latest localhost:8080/my-docker-hosted/nginx:latest

# Push to OrbitRepos
docker push localhost:8080/my-docker-hosted/nginx:latest

Pull / Install Artifacts

Pulling images follows the standard Docker flow. If the repository is private, ensure you are logged in.

docker pull localhost:8080/my-docker-hosted/nginx:latest

Proxy Setup

A proxy repository caches artifacts from a remote registry (e.g., Docker Hub).

  1. Create a repository with type proxy.
  2. Set the Remote URL to https://registry-1.docker.io.
  3. Pull images through OrbitRepos: 
    docker pull localhost:8080/my-docker-proxy/library/nginx:latest

Tip

Use a group repository to combine your hosted and proxy repositories. This allows you to pull both internal and external images from a single URL.

Troubleshooting

Issue Cause Resolution
Permission Denied Missing or expired credentials. Run docker login localhost:8080 again.
Repository not found The repository name is misspelled. Verify the name in the OrbitRepos UI.
Manifest unknown The image or tag does not exist. Check the artifact list in the UI.
HTTP 405 Using a non-v2 compatible client. Ensure your Docker CLI is up to date.

Warning

Docker expects HTTPS by default. If using localhost:8080 without TLS, Docker treats it as an insecure registry. For other domains, you may need to add them to insecure-registries in daemon.json.