aa-customizer

AA Customizer

📖 Interactive Documentation — Installation guide, field reference, media strategy

A branding & customization plugin for Alliance Auth.

Gives administrators a simple admin-panel UI to customize their Alliance Auth installation without touching code or replacing static files.

Screenshots

Split Screen layout

Centered Card layout (default)

Side Bar Icon

Custom Login CSS/HTML (Design how you want!)

Features

Requirements

• Alliance Auth ≥ 4.0.0 (Bootstrap 5 template set)
• django-solo
• Pillow

---

To prevent confusion on how to get this installed, I figured I would break it down a little more.

After the initial install, migrate, 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.)

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:

---

Installation

Bare Metal install

1 — Install the package

# Activate your Alliance Auth virtualenv first, then:
pip install aa-customizer

2 — Add to INSTALLED_APPS

Open your local.py and add above INSTALLED_APPS =:

INSTALLED_APPS.insert(0, 'aa_customizer')

Django searches each app's templates/ folder in INSTALLED_APPS order and uses the first match. Placing aa_customizer first ensures its template overrides are picked up before the Alliance Auth originals.

Note: allianceauth.admin_status (the dashboard version/celery widget) is automatically registered by aa_customizer at startup — you do not need to add it to INSTALLED_APPS manually.

3 — Add the context processor

In local.py, add to the settings section to append the existing TEMPLATES list:

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

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

4 — Run migrations

python manage.py migrate aa_customizer

5 — Collect static files

python manage.py collectstatic

6 — Configure your web server

Make sure your web server (nginx, Apache, etc.) is configured to serve files from MEDIA_ROOT at MEDIA_URL.

In your nginx.conf, add inside the server {} block:

# 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;
}

Adjust client_max_body_size to suit your largest file. A 1920×1080 JPEG is typically 1–5 MB; a short MP4 video background can be 10–20 MB. Set it slightly above your expected maximum.

7 — (Optional) Populate the Media Library

Once media is configured, go to AA Customizer → Media Library in the admin panel to upload images. Give each one a descriptive name (e.g. "Corp logo v2", "Winter background"). You can then pick from your library in Custom Branding without re-uploading — just change the dropdown selection to switch images instantly.

Docker install

The recommended approach for Docker is to use URL fields for all images (point at an external CDN, Imgur, GitHub raw assets, etc.) so you don't need to mount a media volume just to serve a few files.

1 — Install the package inside the container

# Activate your Alliance Auth virtualenv first, then:
pip install aa-customizer

2 — Add to INSTALLED_APPS

Open your local.py and add above INSTALLED_APPS =:

INSTALLED_APPS.insert(0, 'aa_customizer')

Django searches each app's templates/ folder in INSTALLED_APPS order and uses the first match. Placing aa_customizer first ensures its template overrides are picked up before the Alliance Auth originals.

Note: allianceauth.admin_status (the dashboard version/celery widget) is automatically registered by aa_customizer at startup — you do not need to add it to INSTALLED_APPS manually.

3 — Add the context processor

In local.py, add to the settings section to append the existing TEMPLATES list:

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

4 — Run migrations

python manage.py migrate aa_customizer

5 — (Optional) Configure media storage

Skip this section if you plan to use URL fields for all images.

a) Add media settings to local.py

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

b) Add the named volume to docker-compose.yml

The standard AA Docker setup uses a named Docker volume for media. Add it in three places:

1. In x-allianceauth-base volumes (so gunicorn, beat, and workers all share it):

x-allianceauth-base: &allianceauth-base
  volumes:
    # ... your existing volume mounts ...
    - media-data:/var/www/myauth/media

2. In the nginx service volumes:

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

3. In the top-level volumes: section:

volumes:
  media-data:

c) Configure nginx

In your nginx.conf, add the following inside the server {} block:

# 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;
}

Adjust client_max_body_size to suit your largest file. A 1920×1080 JPEG is typically 1–5 MB; a short MP4 video background can be 10–20 MB. Set it slightly above your expected maximum.

6 — Build and restart

docker compose build
docker compose down
docker compose up -d

7 — Fix volume permissions (if media was configured)

Docker creates named volumes owned by root. The AA container runs as uid/gid 61000. Run this once after first bringing the stack up:

Confirm the uid/gid:

docker compose exec allianceauth_gunicorn ls -la /var/www/myauth/media
# fix ownership
docker compose exec -u root allianceauth_gunicorn chown -R 61000:61000 /var/www/myauth/media

After this, uploads made through /admin/aa_customizer/aacustomizersettings/ will be stored under /var/www/myauth/media/aa_customizer/ and served immediately by nginx.

Usage

1. Log in to the Alliance Auth admin panel (/admin/).
2. (Optional) Build your image library — find AA Customizer → Media Library and upload your images there, giving each a name. You can upload as many as you like and switch between them without re-uploading.
3. Find AA Customizer → Custom Branding in the left-hand sidebar.
4. For each image slot, choose how to set it:
   • Library — pick from an image you uploaded to the Media Library (recommended when self-hosting media)
   • URL — paste an external link (CDN, Imgur, etc.) — always takes priority
   • Upload — upload a file directly into the field
5. Fill in any other fields you want and click Save.

Changes take effect immediately on the next page load — no server restart needed.

Field reference

Site

Login Page — Background

Login Page — Layout

Login Page — Branding

Favicon

Navigation Bar Logo

Sidebar Logo

Site-Wide CSS & HTML

Login Page — SPA Mode

SPA mode turns your login page into a mini website with a navigation bar. Visitors can browse multiple pages (About, Requirements, etc.) before clicking Sign In to get the normal EVE SSO login card.

How to build your SPA pages

With SPA mode on, go to Login Page — Extra Body HTML and paste your pages using this structure:

<div id="aac-spa-content">

  <section data-route="home" data-label="Home">
    <div class="aac-spa-page">
      <p class="aac-spa-corp-tag">YOUR CORP TAG</p>
      <h1 class="aac-spa-hero-title">My Corporation</h1>
      <p class="aac-spa-hero-sub">Short tagline here</p>
      <div class="aac-spa-hero-actions">
        <a href="#about" class="aac-spa-btn aac-spa-btn-outline">About Us</a>
        <a href="#signin" class="aac-spa-btn aac-spa-btn-primary">Sign In →</a>
      </div>
    </div>
  </section>

  <section data-route="about" data-label="About Us">
    <div class="aac-spa-page">
      <h2 class="aac-spa-page-title">About Us</h2>
      <p class="aac-spa-body-text">Tell visitors about your corp here.</p>
    </div>
  </section>

</div>

• Each <section> becomes one page. The data-route is its internal name; data-label is the nav link text.
• Nav links are built automatically — no extra setup needed.
• Linking to href="#signin" closes the SPA and shows the login card.
• A full ready-to-use scaffold is available in login-spa.html in this repository — copy and paste it into the Extra Body HTML field and edit the text.

Member Dashboard — Custom Code

Inject custom CSS or HTML into the dashboard all logged-in members see.

Superuser Dashboard — Custom Code

Inject custom CSS or HTML into the admin status overview page (/admin/). Only superusers and staff see this.

Image recommendations

Restricting admin access

By default, any superuser can edit Custom Branding and the Media Library in admin.

If you want to lock those pages down to specific people only — even if other superusers exist — add this to local.py:

AA_CUSTOMIZER_TRUSTED_USER_IDS = [1, 42]

Replace 1 and 42 with the real user IDs of the people who should have access. Anyone not on the list will be turned away even if they are a superuser.

How to find a user's ID: Go to Admin → Authentication → Users, click the user's name, and look at the number in the URL. For example, /admin/auth/user/5/change/ means their ID is 5.

If you leave this setting out of local.py entirely, all superusers retain access as normal.

Security notes

• Raw HTML fields (Login Page Extra HTML, Extra <head> HTML) are rendered without sanitization and are only editable by Django admin users (staff/superusers).
• Custom CSS URL is validated as a URL by Django's field validator; only http/https schemes are accepted.
• AA Customizer works alongside Alliance Auth's built-in Custom CSS admin (/admin/custom_css/customcss/). The customizer's CSS loads after the built-in one, so it takes precedence.

License

MIT