Extend the Docker image

The stock Docker image can be extended in a variety of ways.

General information

The default image is based on the slim variant of the official Python image. This means it is based on the current Debian stable version and the latest Python version.

django-ca runs in a virtual environment created with uv, but uv is not installed in the image to keep the image size to a minimum.

Install additional packages

To install additional packages (like other third-party Django apps), you first need to install uv in Docker. Note that the virtual environment is already active:

Dockerfile for django-ca with additional Python packages

FROM mathiasertl/django-ca

# Install uv (see https://docs.astral.sh/uv/guides/integration/docker/#installing-uv)
COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
ENV UV_LINK_MODE=copy

# Install additional packages in the django-ca virtual environment:
RUN --mount=type=cache,target=/root/.cache/uv \
    uv pip install ...

This of course also works if you want to install your local package with uv pip install -e ., you just need to add your source code first.

To verify that you install packages correctly, build your image and try importing the Python modules you installed:

$ docker build -t example .
$ docker run --rm -it example python -c 'import ...'

Add configuration

To load additional settings for either Django, django-ca or your own django apps, simply place YAML files in /usr/src/django-ca/ca/conf/. Files placed here will be loaded into the Django settings system when the application starts. The Compose setup also loads files from /usr/src/django-ca/ca/conf/compose/. If you place files here, settings will only be loaded if started via Compose.

The locations that settings are loaded from is controlled by DJANGO_CA_SETTINGS.

If for example you want to override a django-ca setting and also want to configure an Email host:

10-app-settings.yaml

CA_ENABLE_REST_API: true
EMAIL_HOST: smtp.example.com

This file can then be added to your image with:

FROM mathiasertl/django-ca
ADD 10-app-settings.yaml /usr/src/django-ca/ca/conf/

To verify that your settings are included correctly, build the image and print out settings:

$ docker build -t example .
$ docker run --rm -it -e DJANGO_CA_SECRET_KEY=dummy example manage shell
>>> from django.conf import settings
>>> print(settings.SETTINGS_FILES)
(PosixPath('/usr/src/django-ca/ca/conf/00-docker.yaml'),)
>>> print(settings.CA_ENABLE_REST_API)
True

Extend `INSTALLED_APPS` and URL patterns

You can extend INSTALLED_APPS as well as the URL patterns using EXTEND_INSTALLED_APPS and EXTEND_URL_PATTERNS.

Add NGINX configuration

If your setup (potentially) uses Compose and adds additional URL endpoints, you will have to add to the NGINX site configuration provided by the django-ca Docker image. To increase security, the NGINX configuration only routes known URL endpoints to the application server (Gunicorn).

The NGINX setup usually consists of HTTP and HTTPS configuration. To automatically route HTTP requests to the application server for HTTP only, add them to /usr/src/django-ca/nginx/include.d/http/. For HTTPS, add them to /usr/src/django-ca/nginx/include.d/https/. In either case, the files need to have the .conf file suffix:

/usr/src/django-ca/nginx/include.d/https/app.conf

location /cmc/ {
    try_files "" @django_ca;
}

You can include any configuration valid in a server context.

Use custom image in Compose

To use a custom image in the standard Compose setup included in django-ca, set DJANGO_CA_IMAGE and DJANGO_CA_VERSION in your .env. file, which gives you full control over the image that will be loaded:

.env

DJANGO_CA_IMAGE=example
DJANGO_CA_VERSION=latest

The image will be loaded in the exact same context (Redis, PostgreSQL, …) as the default image.