Skip to content

HOW‐TO

Jump to bottom
Thrain edited this page Mar 22, 2026 · 5 revisions

To prevent confusion on how to get this installed, the readme is a good start, but I figured I would break it down a little more.

After the initial install, mirgate, etc. the app will function without having to do any of the extra folder creations by using image URLs.

The upside is, it will work, the downside is, for any user that is located in a country that is blocking certain websites, like Imgur, the images will not appear. (A UK user in our Corp pointed this out to me.)

alt

So, the work around is either:

  • A: Use a service that can provide global hosting for images. For this, I used Cloudflare's R2 Object storage, linked to the custom domain (your Auth URL), which then created a DNS record for the storage. This in turn will expose anything put into the bucket, so it's recommended to only store what is needed, I.E.: pictures. (Tested this by using Proton VPN)

  • B: Do the setup to allow the images to be hosted directly in Auth:

Docker Setup

Modify the docker-compose.yml file to include the following

alt

  volumes:
    # ... your existing volume mounts ...
    - media-data:/var/www/myauth/media

alt

services:
  nginx:
    volumes:
      # ... your existing volume mounts ...
      - media-data:/var/www/myauth/media

alt

volumes:
  media-data:

Edit the nginx.conf file:

alt

# Allow uploads up to 20 MB (nginx default is 1 MB — raise this if you
# get "413 Request Entity Too Large" when uploading background images).
client_max_body_size 20m;
# add after location /static
location /media {
    alias /var/www/myauth/media;
    autoindex off;
}

And then add this to the local.py file under custom settings:

alt

TEMPLATES[0]["OPTIONS"]["context_processors"].append(
    "aa_customizer.context_processors.aa_customizer"
)

MEDIA_ROOT = "/path/to/your/media/"
MEDIA_URL  = "/media/"

Baremetal Setup

The steps are the same as Docker, but there is no docker-compose.yml to edit — everything is done via local.py and your nginx site config.

1 — Edit local.py:

TEMPLATES[0]["OPTIONS"]["context_processors"].append(
    "aa_customizer.context_processors.aa_customizer"
)

MEDIA_ROOT = "/home/allianceauth/myauth/media/"
MEDIA_URL  = "/media/"

Adjust the path in MEDIA_ROOT to match your install. The gunicorn process user must be able to write to this directory.

2 — Create the media directory and set permissions:

mkdir -p /home/allianceauth/myauth/media
chown allianceauth:allianceauth /home/allianceauth/myauth/media

3 — Edit your nginx site config (typically /etc/nginx/conf.d/myauth.conf or /etc/nginx/sites-available/myauth):

# Raise upload limit (nginx default is 1 MB — raises this if you
# get "413 Request Entity Too Large" when uploading background images).
client_max_body_size 20m;

# Add this block alongside your existing location /static block
location /media {
    alias /home/allianceauth/myauth/media;
    autoindex off;
}

4 — Restart services:

sudo systemctl restart gunicorn
sudo systemctl reload nginx

Important: Changes to local.py do not take effect until gunicorn is restarted. If images still don't show after configuring everything, this is the most common missed step.

Clone this wiki locally