Skip to main content

Quickstart: Your First Container Registry

Get Angos running and push your first container image in under 5 minutes.

What You'll Learn​

By the end of this tutorial, you will:

  • Run a Angos server
  • Push a container image to your registry
  • Pull the image back

Prerequisites​

  • Docker installed and running
  • A terminal

Step 1: Download Angos​

Download the latest release for your platform from the releases page:

# Example for Linux x86_64
curl -LO https://github.com/project-angos/angos/releases/latest/download/angos-linux-amd64
chmod +x angos-linux-amd64
mv angos-linux-amd64 angos

Or build from source:

git clone https://github.com/project-angos/angos.git
cd angos
cargo build --release
cp target/release/angos .

Step 2: Create a Minimal Configuration​

Create a file named config.toml:

[server]
bind_address = "0.0.0.0"
port = 5000

[blob_store.fs]
root_dir = "./registry-data"

[global.access_policy]
default_allow = true

[repository."test"]

This configures the registry to:

  • Listen on all interfaces on port 5000
  • Store images in the ./registry-data directory
  • Allow unauthenticated access (for testing only)
  • Create a repository named test for pushing images

Step 3: Start the Registry​

./angos -c config.toml server

You should see output indicating the server is running:

Listening on 0.0.0.0:5000 (non-TLS)

Step 4: Configure Docker for Insecure Registry​

Since this quickstart uses HTTP (no TLS), you need to configure Docker to allow insecure connections.

Edit or create /etc/docker/daemon.json:

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

Then restart Docker:

# Linux
sudo systemctl restart docker

# macOS (Docker Desktop)
# Restart Docker Desktop from the menu bar

Tip: For production deployments, always use TLS. See Deploy with Docker Compose for a secure setup.

Step 5: Tag and Push an Image​

In a new terminal, tag an existing image for your registry:

docker pull alpine:latest
docker tag alpine:latest localhost:5000/test/alpine:latest

Push the image to your registry:

docker push localhost:5000/test/alpine:latest

Step 6: Pull the Image Back​

Verify the image is stored by pulling it:

docker rmi localhost:5000/test/alpine:latest
docker pull localhost:5000/test/alpine:latest

You've successfully pushed and pulled an image from your own container registry.

What's Next?​

Now that you have a basic registry running, you can:

Configuration Reference​

For all available configuration options, see the Configuration Reference.