Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.root.io/llms.txt

Use this file to discover all available pages before exploring further.

Root Image Catalog works with Docker out of the box. Images are pulled from cr.root.io using standard Docker commands and credentials.

​
Prerequisites

  • Docker 20.10 or later
  • Root registry credentials (username and token - see Authentication)

​
Authentication

docker login cr.root.io \
  --username rootio \
  --password YOUR_ROOT_TOKEN
Or pipe the token to avoid it appearing in shell history: 
echo "$ROOT_TOKEN" | docker login cr.root.io --username rootio --password-stdin
Docker stores credentials in ~/.docker/config.json. All subsequent pulls from cr.root.io use these credentials automatically. Credential helpers (optional): You can use any Docker-compatible credential helper (docker-credential-pass, macOS Keychain, etc.) for more secure credential storage. Configure them in ~/.docker/config.json as you would for any other registry.

​
Pulling Images

docker pull cr.root.io/python:3.12-slim
docker pull cr.root.io/node:20-slim
docker pull cr.root.io/nginx:1.25
Tags mirror Docker Hub exactly. cr.root.io/python:3.12-slim is the same image as docker.io/python:3.12-slim - same behavior, same entrypoints, with CVEs remediated. Multi-architecture pulls: 
docker pull --platform linux/amd64 cr.root.io/python:3.12-slim
docker pull --platform linux/arm64 cr.root.io/python:3.12-slim

​
Updating Your Dockerfile

Change the FROM directive to use cr.root.io: 
# Before
FROM python:3.12-slim

# After
FROM cr.root.io/python:3.12-slim
No other changes are needed. The image behaves identically. Using a build argument for flexibility: 
ARG BASE_REGISTRY=cr.root.io
FROM ${BASE_REGISTRY}/python:3.12-slim

# Build with Root Image Catalog (default):
# docker build .

# Build with Docker Hub (override):
# docker build --build-arg BASE_REGISTRY=docker.io .
Multi-stage builds: 
ARG BASE_REGISTRY=cr.root.io

FROM ${BASE_REGISTRY}/golang:1.22-alpine AS builder
WORKDIR /app
COPY . .
RUN go build -o /app/server ./cmd/server

FROM ${BASE_REGISTRY}/alpine:3.20
COPY --from=builder /app/server /usr/local/bin/server
CMD ["/usr/local/bin/server"]

​
Docker Compose

Use cr.root.io images in docker-compose.yml the same way: 
services:
  app:
    image: cr.root.io/python:3.12-slim
    environment:
      - DATABASE_URL=postgresql://db:5432/myapp

  db:
    image: cr.root.io/postgres:16-alpine
    environment:
      - POSTGRES_PASSWORD=secret

  cache:
    image: cr.root.io/redis:7-alpine
Docker Compose inherits credentials from ~/.docker/config.json, so no extra configuration is needed after running docker login.

​
Registry Mirror Configuration

To use cr.root.io as a registry mirror (so all pulls transparently go through Root), configure Docker’s daemon.json: 
{
  "registry-mirrors": ["https://cr.root.io"]
}
Restart Docker after making changes: 
sudo systemctl restart docker
With mirror mode, docker pull python:3.12-slim automatically resolves to the Root-patched version without changing any Dockerfiles.

​
CI/CD with Docker

GitHub Actions: 
name: Build and push
on: [push]

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

      - name: Log in to Root Image Catalog
        uses: docker/login-action@v3
        with:
          registry: cr.root.io
          username: rootio
          password: ${{ secrets.ROOT_TOKEN }}

      - name: Build image
        uses: docker/build-push-action@v5
        with:
          push: true
          tags: your-registry/your-app:latest
GitLab CI: 
build:
  stage: build
  before_script:
    - echo "$ROOT_TOKEN" | docker login cr.root.io --username rootio --password-stdin
  script:
    - docker build -t your-registry/your-app:latest .
    - docker push your-registry/your-app:latest
CircleCI: 
jobs:
  build:
    docker:
      - image: cimg/base:stable
    steps:
      - checkout
      - setup_remote_docker
      - run:
          name: Authenticate to Root registry
          command: echo "$ROOT_TOKEN" | docker login cr.root.io --username rootio --password-stdin
      - run:
          name: Build image
          command: docker build -t your-registry/your-app:latest .