Platform Overview

v1.2.6 Latest release

AA Customizer is a branding plugin for Alliance Auth that gives administrators a simple admin-panel UI to fully brand their installation — custom logos, backgrounds, layout, CSS, and more — all without touching code or static files.

Core Features

🏷️ Custom Site Name

Global override for SITE_NAME without editing local.py.

🎬 Video Backgrounds

Fullscreen .mp4/.webm/.ogv videos with configurable loop count (play once, N times, or forever).

📐 Multiple Layouts

Centered Card or Split-Screen (Background Left / Login Left) login layouts.

🖼️ Dynamic Logos

Upload or link logos for the Login page, Navbar, and Sidebar independently.

💉 Injected Content

Add custom HTML to the Login card or site-wide <head> (analytics, Discord links, etc.).

🎨 Custom CSS

Inject inline CSS or link external stylesheets, loaded after the active theme.

🖌️ Login Page Redesign

Inject CSS, HTML, and JS exclusively on the login page for a completely custom landing page design.

🌐 Login Page SPA Mode

Turn the login page into a full-viewport multi-page public site with a navigation bar — no server changes required.

📊 Dashboard Injection

Inject custom CSS, HTML, and scripts into the member dashboard and a separate admin status widget visible only to superusers.

🔐 Restricted Admin Access

Optionally limit AA Customizer admin access to a specific list of user IDs via AA_CUSTOMIZER_TRUSTED_USER_IDS in local.py.

System Requirements

  • Alliance Auth >= 4.0.0 (Bootstrap 5 template set)
  • django-solo
  • Pillow (required for image upload & processing)

Customization Areas

Breakdown of configuration categories.

Installation Guide

Every installation requires the Core Setup below. Then select the tab for your hosting environment to finish configuring media storage.

1. Core Setup — All Environments

Activate your Alliance Auth virtual environment and install:

pip install aa-customizer

Edit your local.py:

# 1. Place aa_customizer first so its templates take priority
INSTALLED_APPS.insert(0, 'aa_customizer')

# 2. Register the context processor
TEMPLATES[0]["OPTIONS"]["context_processors"].append(
    "aa_customizer.context_processors.aa_customizer"
)

# 3. Define media paths (adjust to your install path)
MEDIA_ROOT = "/var/www/myauth/media/"
MEDIA_URL  = "/media/"

Run migrations:

python manage.py migrate aa_customizer

Docker: Media Volume Setup

The easiest approach for Docker is to use URL fields (external CDN, Imgur, GitHub raw) so no volume is needed. If you want to self-host media, add a named volume in three places in docker-compose.yml:

  1. Add the volume to the base service definition, nginx, and top-level volumes:
    # In x-allianceauth-base
    x-allianceauth-base: &allianceauth-base
      volumes:
        - media-data:/var/www/myauth/media

    # In the nginx service
    services:
      nginx:
        volumes:
          - media-data:/var/www/myauth/media

    # Top-level volumes section
    volumes:
      media-data:
  2. Add the Nginx media location block inside server {}:
    client_max_body_size 20m;

    location /media {
        alias /var/www/myauth/media;
        autoindex off;
    }
  3. Fix permissions — the AA container runs as UID 61000:
    docker compose exec -u root allianceauth_gunicorn chown -R 61000:61000 /var/www/myauth/media
  4. Build and restart:
    docker compose build
    docker compose up -d

Bare Metal: Nginx & Static Files

  1. Create the media directory and set permissions:
    mkdir -p /var/www/myauth/media
    chown -R www-data:www-data /var/www/myauth/media
  2. Collect static files:
    python manage.py collectstatic
  3. Add the media block to your Nginx config inside server {}:
    # Raise this if uploads are rejected with 413
    client_max_body_size 20m;

    location /media {
        alias /var/www/myauth/media;
        autoindex off;
    }
  4. Restart services:
    sudo nginx -t && sudo systemctl reload nginx
    sudo systemctl restart gunicorn

Media Hosting Strategy

There are two ways to supply images and videos to the customizer. Choose based on your hosting environment and accessibility needs.

🔗 Option A: External URLs

Quickest setup — no storage config needed

Paste a URL from any public image/video host (Imgur, Cloudflare R2, GitHub raw, etc.) directly into the URL fields in the admin panel.

Pros Works instantly with zero extra server config. No volume mounts, nginx rules, or permission changes.
Cons Users in regions that block certain CDNs (e.g. Imgur is blocked in parts of the UK) will see broken images. Third-party dependency.

🗄️ Option B: Local Hosting

Best reliability — served from your own domain

Upload files directly via the Media Library tab in the admin panel. They're served from your own domain, so any user who can reach your Auth site will see them.

Pros Fully self-hosted. No third-party tracking. Guaranteed to load for all your users globally.
Cons Requires the Nginx media block and (for Docker) a bind mount — see the Installation Guide.

Input Priority Logic

For fields that support all three input methods (URL, Library, Upload), the plugin uses a strict priority chain. Only the highest-priority non-empty value is rendered.

Priority 1 URL Field
→
Priority 2 Library Pick
→
Priority 3 Direct Upload

If a URL is set, the Library and Upload fields are ignored.

Field & Layout Reference

All configuration fields available in the AA Customizer admin panel. Use the search box to jump to a specific field.

Admin Panel Fields

Section Field Description
Site Site Name Global override for SITE_NAME from local.py, displayed across the whole site.
Background Login Background — URL URL of a background image or video (takes priority over all other background fields). Video files (.mp4, .webm, .ogv) play fullscreen, muted, and auto-pause when the tab is hidden.
Background Login Background — Library Select an image uploaded to the Media Library. Takes priority over a direct upload.
Background Login Background — Upload Upload a background image or video directly into this field. Supported formats: JPEG, PNG, GIF, WebP, BMP, TIFF, SVG, MP4, WebM, OGV.
Background Login Background Color CSS color shown when no image is set, or behind a video while it loads. Example: #1a1a2e.
Background Background Video — Loop Count 0 = loop forever (default). 1 = play once then freeze on the last frame. N = play N times then freeze. Only applies to video backgrounds.
Layout Login Page Layout Centered Card — login card centered over the full background (default). Split Screen — Background Left — background on the left, dark login panel on the right. Split Screen — Login Left — mirrors it.
Layout Split Panel — Show Overlay Text Tick to show text on the background panel of a split-screen layout; untick to hide it.
Layout Split Panel — Overlay Text Text shown on the background panel. Leave blank to auto-display the site name.
Layout Split Panel — Text Position Vertical position of the overlay text: Top, Center, or Bottom.
Login Branding Login Logo — URL URL of a logo image shown at the top of the login card (highest priority).
Login Branding Login Logo — Library Select a logo from the Media Library.
Login Branding Login Logo — Upload Upload a logo image directly.
Login Branding Login Logo Max Width (px) CSS max-width applied to the login logo image.
Login Branding Login Page Title Custom heading shown above the SSO button on the login card.
Login Branding Login Page Subtitle Optional description text shown below the title.
Login Branding Login Page Extra HTML Raw HTML injected below the EVE SSO button on the login card. Useful for Discord links, notices, etc.
Favicon Favicon — URL URL of a favicon image (highest priority). Replaces all Alliance Auth browser-tab icons.
Favicon Favicon — Library Select a favicon from the Media Library.
Favicon Favicon — Upload Upload a favicon image directly.
Navbar Logo Navbar Logo — URL URL of a logo shown alongside the site name in the top navigation bar (highest priority).
Navbar Logo Navbar Logo — Library Select a navbar logo from the Media Library.
Navbar Logo Navbar Logo — Upload Upload a navbar logo directly.
Navbar Logo Navbar Logo Height (px) CSS height applied to the navbar logo.
Sidebar Logo Sidebar Logo — URL URL of an image to replace the Alliance Auth logo in the sidebar (highest priority).
Sidebar Logo Sidebar Logo — Library Select a sidebar logo from the Media Library.
Sidebar Logo Sidebar Logo — Upload Upload a sidebar logo directly.
Sidebar Logo Sidebar Logo Width (px) CSS max-width applied to the sidebar logo.
Custom CSS Custom CSS — URL External stylesheet URL linked in every page <head>, loaded after the active theme.
Custom CSS Custom CSS (Inline) Raw CSS text injected via <style> on every page, loaded after the active theme. Takes precedence over the built-in Custom CSS admin.
Extra HTML Extra <head> HTML Raw HTML injected at the end of <head> on every page. Useful for analytics scripts, font imports, or custom meta tags.
Login Page Login Page — CSS URL External stylesheet URL linked only on the login page <head>, loaded after global CSS. Useful for a completely custom login page design.
Login Page Login Page — CSS (Inline) Raw CSS text injected via <style> only on the login page, loaded after global CSS. Use to restyle or completely override the login page appearance.
Login Page Login Page — Extra <head> HTML Raw HTML injected at the end of <head> only on the login page. Useful for login-specific scripts or meta tags.
Login Page Login Page — Extra Body HTML Raw HTML injected just before </body> only on the login page. Useful for custom overlays, JS bundles, or analytics specific to the login experience.
Login Page — SPA Login Page — Enable SPA mode When enabled, a full-viewport overlay SPA is shown on the login page with a nav bar and multiple page sections. Visitors browse a public site; clicking Sign In reveals the standard EVE SSO card. Add page content via Login Page — Extra Body HTML using <section data-route="slug" data-label="Nav Label"> elements wrapped in <div id="aac-spa-content" style="display:none">.
Login Page — SPA Login Page — SPA nav brand Text shown in the top-left of the SPA navigation bar. Defaults to the site name if left blank.
Dashboard Dashboard — CSS URL External stylesheet URL loaded only on the main (member) dashboard, after the global CSS URL. Use for widget-specific design frameworks without affecting other pages.
Dashboard Dashboard — CSS Inline CSS applied only on the main dashboard, after all other stylesheets. Highest CSS priority — full design control over the dashboard layout and widgets.
Dashboard Dashboard — Extra <head> HTML Raw HTML injected at the end of <head> on the main dashboard only. Useful for chart libraries or custom fonts specific to the member dashboard.
Dashboard Dashboard — Extra Body HTML Raw HTML injected before </body> on the main dashboard only. Useful for overlays, widget scripts, or custom markup visible to all logged-in members.
Admin Dashboard Admin Dashboard — CSS URL External stylesheet URL loaded only in the admin status widget (superusers only). Non-superusers never receive this stylesheet.
Admin Dashboard Admin Dashboard — CSS Inline CSS applied only inside the admin status widget (superusers only). Non-superusers never receive these styles.
Admin Dashboard Admin Dashboard — Extra <head> HTML Raw HTML injected at the end of <head> when the admin status widget is shown — superusers only. Useful for chart libraries or extra scripts for the admin panel.
Admin Dashboard Admin Dashboard — Extra Body HTML Raw HTML injected inside the admin status widget, after all panel cards — superusers only. Useful for overlays or extra markup visible only to administrators.

Image & Video Recommendations

Background Image
1920 × 1080 px

JPEG, PNG, or GIF. JPEG recommended for photos.

Background Video
1920 × 1080 px

MP4 (H.264) or WebM (VP9). Keep under ~15 MB for fast loads.

Login Logo
≥ 256 × 256 px

Transparent PNG. Displayed at the top of the login card.

Navbar & Sidebar Logos
Transparent PNG

Navbar height ≤ 64 px. Sidebar width ≤ 256 px.

Favicon
≥ 192 × 192 px

PNG or ICO format for best browser-tab display.

Security & Licensing

Important considerations for administrators regarding raw input fields and the open-source license.

⚠️ Security Notes

  • Raw HTML fields: Login Page Extra HTML, Extra <head> HTML, Login Page — Extra <head> HTML, Login Page — Extra Body HTML, Dashboard — Extra <head> HTML, Dashboard — Extra Body HTML, Admin Dashboard — Extra <head> HTML, and Admin Dashboard — Extra Body HTML are injected without sanitization. Only Django staff/superusers can access the AA Customizer admin panel, but you should still restrict access to highly trusted administrators to prevent XSS vulnerabilities.
  • Restricted Admin Access: Add AA_CUSTOMIZER_TRUSTED_USER_IDS = [1, 7] to local.py to limit AA Customizer admin access to only those user IDs, even if other staff/superusers exist. Leave the setting unset (or as an empty list) to fall back to the default Django staff/superuser check. Find your user ID in the Alliance Auth admin panel under Authentication → Users.
  • CSS Precedence: The customizer's CSS loads after Alliance Auth's default custom CSS. This is intentional — it lets you override theme styles — but double-check your selectors to avoid unintended layout breaks.
  • Custom CSS URL: Validated as a URL by Django's field validator; only http and https schemes are accepted.

📄 License

This project is licensed under the MIT License.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

Login Page Showcase

Using only the four Login Page Custom Code fields, you can replace the default Alliance Auth login card with a fully custom marketing page — without touching a single server file. This live demo shows a complete EVE Online corporation landing page built entirely in the admin panel. For an even richer experience, enable SPA mode to get a built-in navigation bar and multi-page routing powered automatically by the plugin's own JavaScript and CSS.

Field 1
Login Page — Extra <head> HTML

Imports the Space Grotesk Google Font used throughout the landing page.

Field 2
Login Page — CSS (Inline)

Repositions the existing login card as a hidden overlay modal and styles the entire showcase page — 250+ lines of CSS.

Field 3
Login Page — Extra Body HTML

Injects the full marketing page (nav, hero, stats, feature cards, CTA, footer) and all the JavaScript — 230+ lines.

Result
Zero server changes

The Alliance Auth EVE SSO login button still works normally — only its visual presentation is controlled by your CSS.

↗ Open Full Demo Scroll the iframe · click Member Login · press Esc to close the modal.

💡 How the modal overlay works

The CSS field sets .aac-login-root { position: fixed; opacity: 0; pointer-events: none; }, effectively hiding the existing login card without removing it from the DOM. The JavaScript in the Body HTML field adds the .aac-open class when a visitor clicks Member Login, transitioning the card to full opacity. The EVE SSO button inside the card still points to Alliance Auth's real login URL — no server-side changes required.