Skip to main content
Image Creator is usually the optimal way to add packages to Minimus images, but when you need the extra freedom to test out options and decide which packages you will need, direct package access is available. Package access allows you to add Minimus packages directly in your Dockerfile or install them in a running container so you can experiment within the Minimus ecosystem.

​
Creator vs. package access

Image Creator is the standard choice when working with Minimus because it allows Minimus to handle all of the following for you: When using package access to install packages ad-hoc, you (or someone on your team) will need to manually handle the above tasks. That said, package access is a common choice and is fully supported by Minimus.

​
Requesting package access

Package access is not enabled by default, so you’ll need to request access to have it enabled for your tenant. Visit the Tokens page in your Minimus console and select the option to Request package access.
Request Package Access
Fill out the contact form and our team will follow up with you shortly thereafter.
Request Package Access Contact Form

​
Authenticate to packages.mini.dev

Learn how to authenticate to the Minimus Package Repository both at runtime and during the Docker build process.

​
Prerequisites

When installing packages, make sure to use Minimus containers that meet both conditions:
  1. Can run apk commands - Minimus dev images fit the bill
  2. Run as root - usually this is not the default in Minimus images so you’ll need to switch to a root user
Keep in mind that Minimus production images are usually not a good fit because they are distroless. This means they don’t include the necessary packages. You can always check the image’s SBOM to be sure.

​
During runtime (inside a container)

  1. Create a token with package access scope. See tokens
    Package Access Token
  2. Run a Minimus docker container as root and make sure the container includes apk. For example, you can run the Bash image with the latest-dev tag: 
    docker run -it -u root reg.mini.dev/bash:latest-dev
  3. In the container, authenticate to the Minimus package registry:
    package access command
    export HTTP_AUTH="basic:packages.mini.dev:minimus:mini_dkj***"
apk update
    Once authenticated, the session will remain active until the token expires.
  4. Add packages as usual. For example, you can add git: 
    apk add --no-cache --repository=https://packages.mini.dev/os git

​
In a Dockerfile

You can install packages directly within your Dockerfile by authenticating during the image build. As is standard practice in CI pipelines, this approach uses a build variable like ${REPO_PASS} to securely handle credentials. Below is an example of the code to be added to your Dockerfile:
Dockerfile HTTP_AUTH code
...
ARG REPO_PASS
ENV HTTP_AUTH="basic:packages.mini.dev:minimus:${REPO_PASS}"

USER root

# Update APK and install packages
RUN apk update && \
    apk add --no-cache \
        <pkg1> \
        <pkg2>
...
Build with a Minimus token that has package access: 
docker build --build-arg REPO_PASS={token} -t my-minimus-image:local .

​
Python tutorial example (multi-stage build)

The following example builds on the multi-stage pattern from the Minimus Python guide. We will follow the steps in the original guide, replacing only the Dockerfile and build command. The Dockerfile uses a latest-dev builder for package installation and Python dependencies and switches to the minimal Python image at runtime.
Dockerfile with apk add steps
# === Build Stage ===
FROM reg.mini.dev/python:latest-dev AS builder

ARG REPO_PASS
ENV HTTP_AUTH="basic:packages.mini.dev:minimus:${REPO_PASS}"

WORKDIR /app

# Install system packages from the Minimus package repository
USER root
RUN apk update && \
    apk add --no-cache \
        build-base \
        libffi-dev

RUN python -m venv /app/venv
ENV PATH="/app/venv/bin:$PATH"

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# === Runtime Stage ===
FROM reg.mini.dev/python:latest

WORKDIR /app

COPY main.py .
COPY --from=builder /app/venv /app/venv
ENV PATH="/app/venv/bin:$PATH"

ENTRYPOINT ["python", "main.py"]
Note that all apk commands stay in the latest-dev build stage and are executed as USER root to avoid Unable to lock database: Permission denied. The runtime image reg.mini.dev/python:latest is distroless and does not include /bin/sh, so RUN apk ... is not supported there. Add your Minimus token to the build command: 
docker compose build --build-arg REPO_PASS={token}

​
Runtime Troubleshooting

​
Auth error

If the remote server returns an error, most likely authentication failed because your token doesn’t include package access. For example: WARNING: updating and opening https://packages.mini.dev/os: remote server returned error (try 'apk update') To fix the issue, edit your token or create a new one with package access scope. See tokens

​
Permission denied

If you get an error that permission was denied, most likely you are running as a non-root user and can’t modify system files. For example: ERROR: Unable to lock database: Permission denied ERROR: Failed to open apk database: Permission denied To fix the issue, run the container with -u root to override the default user at runtime.

​
APK not found

If you try to run HTTP_AUTH="basic:packages.mini.dev:token" and get an error bash: apk: command not found, this means you are using a Minimus image that is not able to run apk commands. To fix the issue, run a Minimus dev image so it includes dev tools.

​
Dockerfile Troubleshooting

​
Auth error

If you get an error that ends with exit code: 2, most likely authentication failed because your token doesn’t include package access. For example: failed to solve: process "/bin/sh -c apk update && apk add --no-cache <pkg1> <pkg2>" did not complete successfully: exit code: 2 To fix the issue, edit your token or create a new one with package access scope. See tokens

​
Permission denied

If you get an error that ends with exit code: 99, most likely you are running as a non-root user and can’t modify system files. For example: failed to solve: process "/bin/sh -c apk update && apk add --no-cache <pkg1> <pkg2>" did not complete successfully: exit code: 99 To fix the issue, edit your Dockerfile to switch to the root user before running the apk commands.
Last modified on May 4, 2026