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

# Alpine Linux

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

## Supported Versions

Alpine 3.22, 3.21, 3.20, 3.19, 3.18

***

## Dockerfile

```dockerfile theme={null}
# syntax=docker/dockerfile:1.6
ARG ALPINE_VERSION=3.20
FROM alpine:${ALPINE_VERSION}

ARG ALPINE_VERSION
RUN --mount=type=secret,id=rootio_api_key \
    # Install Root.io Alpine signing key
    echo "LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0KTUlJQklqQU5CZ2txaGtpRzl3MEJBUUVGQUFPQ0FROEFNSUlCQ2dLQ0FRRUFvcG1yUjR1em95WEFiTHFiRUE3cwpBNWQrVytnUzE0TzEwMlJHUjhxa0h0cDhSUEs2b3FvZkhJZzNYSWpnSVlzalQwYTk1VXNzbGFlL2FDWU1UeFBVCmhnSmxkTVU1SnlzZmYxT1BEQld4R2ZCOFJCL081cjA1cU9JLzJ3QlgwQjl5NjhhU0xQZi9UWEA3akY5STRKL3EKdjArWVF2c3owRWdqUEFjeVN2MlgvOHE2R2RoOHRkWG4rbTVBYjJoUU5YUE1TdTM3aXMwUVR3Uk9DSFV4ZXZLeAo0OUZ5UGkvQUR5UDB6bVFYaUtCQW52alN6YVNQNmZPQm1yYlNNY05wYnVPV2lwUUJoajRnVE5KOVNzaDZSQmdmCmJVUlFhdmlwWlAyL0RiNTNiLzJ5UTJJU21QMEo1cmdjWnkrdXoyZndTWmtHb3pUa0ErZDE1dHludlJRVFQwbGkKWXdJREFRQUIKLS0tLS1FTkQgUFVCTElDIEtFWS0tLS0tCg==" | \
    base64 -d > /etc/apk/keys/root@alpinelinux.org-67b85bd5.rsa.pub && \
    \
    # Add pkg.root.io repository with credentials from secret
    echo "https://root:$(cat /run/secrets/rootio_api_key)@pkg.root.io/alpine/${ALPINE_VERSION}" \
    >> /etc/apk/repositories && \
    \
    apk update && \
    \
    # Install packages, preferring Root.io patched versions when available
    for pkg in curl git openssl wget tini; do \
    if apk search -e "rootio-$pkg" | grep -q "rootio-$pkg"; then \
    apk add --no-cache "rootio-$pkg"; \
    else \
    apk add --no-cache "$pkg"; \
    fi; \
    done && \
    \
    # Remove repository credentials
    sed -i '/pkg\.root\.io/d' /etc/apk/repositories

CMD ["/bin/sh"]
```

To target a different Alpine version, pass it as a build argument:

```bash theme={null}
DOCKER_BUILDKIT=1 docker build \
  --build-arg ALPINE_VERSION=3.21 \
  --secret id=rootio_api_key,env=ROOTIO_API_KEY \
  -t my-app:latest .
```

***

## 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. Root.io's RSA public key is written to `/etc/apk/keys/` for package signature verification.
2. The `pkg.root.io` repository URL (with credentials inline) is appended to `/etc/apk/repositories`.
3. For each package, `apk search -e rootio-<pkg>` checks if a Root-patched version exists. If yes, the patched version is installed; if not, the standard upstream package is used.
4. The `pkg.root.io` line is removed from `/etc/apk/repositories` 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 `apk 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 |
| `--secret` flag not recognized     | Prepend `DOCKER_BUILDKIT=1` to your build command                                 |
| Key verification error             | Ensure the base64-encoded key is copied in full without line breaks               |