Migrating your Docker Compose stack from AA V3.x to AA v4.x

Our Docker Compose stack has both changed significantly, and simplified itself drastically depending on your level of familiarity with Docker.

We have Removed our need to run Supervisor inside the container to run the various tasks needed, and split the stack into multiple containers responsible for each task, as well as modernized many elements.


We are bundling a few often customized files along side our AA install for easier modification by users, you will need to download these into aa-docker/conf

wget https://gitlab.com/allianceauth/allianceauth/-/raw/v4.x/docker/conf/celery.py
wget https://gitlab.com/allianceauth/allianceauth/-/raw/v4.x/docker/conf/urls.py
wget https://gitlab.com/allianceauth/allianceauth/-/raw/v4.x/docker/conf/memory_check.sh
wget https://gitlab.com/allianceauth/allianceauth/-/raw/v4.x/docker/conf/redis_healthcheck.sh

Docker Compose

At this point you should take a copy of your docker-compose and take note of any additional volumes or configurations you have, and why.

Take a complete backup of your local.py, docker-compose and SQL database.

docker compose down

Replace your conf/nginx.conf with the contents of https://gitlab.com/allianceauth/allianceauth/-/raw/v4.x/docker/conf/nginx.conf

Replace your docker-compose.yml with the contents of https://gitlab.com/allianceauth/allianceauth/-/raw/v4.x/docker/docker-compose.yml

V3.x installs likely used a dedicated database for Nginx Proxy Manager, you can either setup NPM again without a database, or uncomment the sections noted to maintain this configuration

    # Uncomment this section to use a dedicated database for Nginx Proxy Manager
      DB_MYSQL_HOST: "proxy-db"
      DB_MYSQL_PORT: 3306
      DB_MYSQL_USER: "npm"
      DB_MYSQL_NAME: "npm"
  # Uncomment this section to use a dedicated database for Nginx Proxy Manager
    image: 'jc21/mariadb-aria:latest'
    restart: always
      MYSQL_DATABASE: 'npm'
      MYSQL_USER: 'npm'
      - 3306
      - proxy-db:/var/lib/mysql
      driver: "json-file"
        max-size: "1Mb"
        max-file: "5"


You will need to add some entries to your .env file



The password field is intentionally not filled so that you create one. You can either use the grafana credentials you have been using, or create a suitably secure password now.

You will also need to update the AA_DOCKER_TAG to the version of V4.x you want to install. Either follow the pattern or check https://gitlab.com/allianceauth/allianceauth/-/releases

(Optional) Build Custom Container

If you are using a docker container with a requirements.txt, You will need to reinstate some customizations.

Modify docker-compose.yml, as follows.

  • Comment out the image line under allianceauth

  • Uncomment the build section

  • e.g.

      x-allianceauth-base: &allianceauth-base
      # image: ${AA_DOCKER_TAG?err}
        context: .
        dockerfile: custom.dockerfile
          AA_DOCKER_TAG: ${AA_DOCKER_TAG?err}
      restart: always

Now build your custom image

docker compose pull
docker compose build

Bring docker back up, migrate, collect static

docker compose --env-file=.env up -d --remove-orphans

docker compose exec allianceauth_gunicorn bash

allianceauth update myauth
auth migrate
auth collectstatic --clear