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

# Ubuntu

> Configure pkg.root.io in your Dockerfile to install Root-patched OS packages on Ubuntu.

## Supported Releases

| Codename | Ubuntu Version |
| -------- | -------------- |
| oracular | 24.10          |
| noble    | 24.04 LTS      |
| mantic   | 23.10          |
| jammy    | 22.04 LTS      |
| focal    | 20.04 LTS      |

***

## Dockerfile

```dockerfile theme={null}
# syntax=docker/dockerfile:1.6
FROM ubuntu:noble

RUN --mount=type=secret,id=rootio_api_key \
    DEBIAN_FRONTEND=noninteractive apt-get update && \
    # Install dependencies for adding repositories
    apt-get install -y --no-install-recommends gnupg ca-certificates && \
    \
    # Initialize keyring and add Root.io GPG key
    mkdir -p /etc/apt/keyrings && \
    echo "LS0tLS1CRUdJTiBQR1AgUFVCTElDIEtFWSBCTE9DSy0tLS0tCgptRE1FYVlIQ1dSWUpLd1lCQkFIYVJ3OEJBUWRBcDdXVHNLMTVrWTNmQ0pxOUNRVnlxODluRzFoNEw4OHZvVndqCnB0NGNXSjYwSkZKdmIzUXVhVzhnUVZCVUlGSmxjRzl6YVhSdmNua2dQR0Z3ZEVCeWIyOTBMbWx2UG9pVEJCTVcKQ2dBN0ZpRUUzSVVhWTlLRDFsTUhKYTdNZ09RM004RHd3c2tGQW1tQndsa0NHd01GQ3drSUJ3SUNJZ0lHRlFvSgpDQXNDQkJZQ0F3RUNIZ2NDRjRBQUNna1FnT1EzTThEd3dzbGY2d0QrSWxqSGRkVmFKM2xKYjBsSE0rZVFubWNvCnlmTTlpWis5cXI0SjBNYnZsNG9CQUtOL0pYZkJvR2JGYzgzM0ZmN1I5R3M5UXU2bm1EUVZlSDI4eHEwdDRwWU4KPWs3ZHMKLS0tLS1FTkQgUEdQIFBVQkxJQyBLRVkgQkxPQ0stLS0tLQo=" \
    | base64 -d | gpg --dearmor -o /etc/apt/keyrings/rootio.gpg && \
    \
    # Write API key to auth.conf.d (never embedded in the source URL)
    mkdir -p /etc/apt/auth.conf.d && \
    printf "machine pkg.root.io\nlogin root\npassword %s\n" \
    "$(cat /run/secrets/rootio_api_key)" > /etc/apt/auth.conf.d/rootio.conf && \
    chmod 600 /etc/apt/auth.conf.d/rootio.conf && \
    \
    # Add Root.io APT repository
    echo "deb [signed-by=/etc/apt/keyrings/rootio.gpg] https://pkg.root.io/ubuntu/noble noble main" \
    > /etc/apt/sources.list.d/rootio.list && \
    \
    DEBIAN_FRONTEND=noninteractive apt-get update && \
    \
    # Install packages, preferring Root.io patched versions when available
    for pkg in curl git openssl wget bash tini; do \
    if apt-cache show "rootio-$pkg" >/dev/null 2>&1; then \
    apt-get install -y --no-install-recommends "rootio-$pkg"; \
    else \
    apt-get install -y --no-install-recommends "$pkg"; \
    fi; \
    done && \
    \
    # Remove credentials and clean up
    rm -f /etc/apt/auth.conf.d/rootio.conf && \
    rm -rf /var/lib/apt/lists/*

CMD ["/bin/bash"]
```

Replace both occurrences of `noble` with your target release codename.

***

## Build

```bash theme={null}
export ROOTIO_API_KEY="your-api-token"

DOCKER_BUILDKIT=1 docker build \
  --secret id=rootio_api_key,env=ROOTIO_API_KEY \
  -t my-app:latest .
```

***

## How It Works

1. `gnupg` and `ca-certificates` are installed from the upstream Ubuntu registry first.
2. Root.io's GPG key is imported to `/etc/apt/keyrings/rootio.gpg` for package signature verification.
3. The API key is written to `/etc/apt/auth.conf.d/rootio.conf` - APT reads it automatically and it never appears in the source URL.
4. For each package, `apt-cache show rootio-<pkg>` checks if a Root-patched version exists. If yes, the patched version is installed; if not, the standard upstream package is used.
5. The auth file is removed in the same `RUN` layer, so credentials are never persisted in the image.

***

## CI/CD Integration

<Tabs>
  <Tab title="GitHub Actions">
    ```yaml theme={null}
    - name: Build container image
      env:
        ROOTIO_API_KEY: ${{ secrets.ROOTIO_API_KEY }}
      run: |
        DOCKER_BUILDKIT=1 docker build \
          --secret id=rootio_api_key,env=ROOTIO_API_KEY \
          -t my-app:latest .
    ```
  </Tab>

  <Tab title="GitLab CI">
    ```yaml theme={null}
    build:
      variables:
        DOCKER_BUILDKIT: "1"
        ROOTIO_API_KEY: $ROOTIO_API_KEY
      script:
        - docker build
            --secret id=rootio_api_key,env=ROOTIO_API_KEY
            -t my-app:latest .
    ```
  </Tab>
</Tabs>

***

## Troubleshooting

| Issue                                  | Solution                                                                          |
| -------------------------------------- | --------------------------------------------------------------------------------- |
| `401 Unauthorized` on `apt-get update` | Verify `ROOTIO_API_KEY` is set and passed via `--secret`                          |
| `rootio-<package>` not found           | Root hasn't patched this package yet - the fallback installs the upstream version |
| GPG key import fails                   | Ensure `gnupg` and `ca-certificates` are installed before the key import step     |
| `--secret` flag not recognized         | Prepend `DOCKER_BUILDKIT=1` to your build command                                 |