> ## 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.

# Docker

> Integrate Root Image Catalog with Docker - authentication, Dockerfile changes, Compose, and registry mirroring.

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](/getting-started/authentication))

## Authentication

```bash theme={null}
docker login cr.root.io \
  --username rootio \
  --password YOUR_ROOT_TOKEN
```

Or pipe the token to avoid it appearing in shell history:

```bash theme={null}
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

```bash theme={null}
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:**

```bash theme={null}
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`:

```dockerfile theme={null}
# 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:**

```dockerfile theme={null}
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:**

```dockerfile theme={null}
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:

```yaml theme={null}
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`:

```json theme={null}
{
  "registry-mirrors": ["https://cr.root.io"]
}
```

Restart Docker after making changes:

```bash theme={null}
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:**

```yaml theme={null}
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:**

```yaml theme={null}
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:**

```yaml theme={null}
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 .
```