Alliance Auth

4.13.1 · active · verified Thu Apr 16

Alliance Auth is a comprehensive web-based authentication system for EVE Online organizations. It streamlines the management of user access to various external services and in-game applications, automatically granting or revoking permissions based on a user's EVE Online affiliations and groups. The current stable version is 4.13.1, and the project maintains an active release cadence with regular updates and community support.

Common errors

```
Error 500 trying to connect to the website on a new install
```
cause A generic web server error indicating an underlying issue in the Django application. This could be due to misconfigurations, missing dependencies, or database problems.

fix Check the detailed error logs located in your Alliance Auth project's `log` directory (e.g., `/home/allianceserver/myauth/log/allianceauth.log`). Increase logging level to 'DEBUG' in `settings/local.py` for more verbose output.
```
Failed to configure log handler
```
cause The directory designated for logs does not have the correct write permissions for the user running the Alliance Auth application.

fix Ensure the log directory (e.g., `/home/allianceserver/myauth/log/`) is writable by the `allianceserver` user (or whichever user runs your Auth instance). Use `sudo chown -R allianceserver:allianceserver /path/to/myauth/log/` and restart supervisor processes.
```
Groups aren't syncing to services / Tasks are not running
```
cause The Celery worker or beat processes, which handle background tasks like group synchronization, are not running or are encountering errors.

fix Check the status of your background processes using `supervisorctl status myauth:`. If `myauth:worker` or `myauth:beat` are not `RUNNING`, inspect their respective log files for errors. You might need to restart them (`supervisorctl restart myauth:worker myauth:beat`).
```
Unable to execute 'gunicorn myauth.wsgi' or ImportError: No module named 'myauth.wsgi'
```
cause Gunicorn is not being executed from the correct directory, preventing it from finding the Django project's WSGI file.

fix Ensure you are in your Alliance Auth project's base directory (e.g., `/home/allianceserver/myauth/`) before running the Gunicorn command. The command should be `cd /home/allianceserver/myauth/ && gunicorn myauth.wsgi` (or similar for supervisor).
```
pip install -r requirements.txt is failing
```
cause This often points to either a permissions issue (the user cannot write to the virtual environment) or missing system-level dependencies required for compiling Python packages (e.g., development headers for `mysqlclient`).

fix Verify that your user has write permissions to the virtual environment directory. Check the error message for indications of missing system packages (e.g., `python3-dev`, `libmysqlclient-dev`). Install these using your system's package manager (e.g., `apt-get` or `yum`).

Warnings

breaking Upcoming v5.0.0 introduces significant breaking changes: drops Python 3.8/3.9 support, requires Django 5.2, uses Django-ESI v9 (dropping Swagger Client), removes legacy XMLAPI code and Bootstrap 3 templates. Community apps will need updates for compatibility.
Fix: Review the official v5.0.0 release notes and migration guides thoroughly. Update Python, Django, and all community applications to compatible versions before upgrading the core Alliance Auth instance.
gotcha Avoid using 'sudo' for pip installs or management commands within your virtual environment, as it can lead to permission issues and break the environment's integrity.
Fix: Always activate your virtual environment (e.g., `source /path/to/venv/bin/activate`) and run commands as the unprivileged user designated for Alliance Auth. Only use `sudo` for system-level package management or when explicitly instructed for specific server configurations.
gotcha Using MariaDB versions prior to 10.2.x can result in a 'Specified key was too long error' during database migrations, due to incompatibilities with Django's default index lengths.
Fix: Ensure your MariaDB installation is version 10.2.x or newer. Alternatively, use a different supported Django database (e.g., PostgreSQL, MySQL 5.7+).
gotcha When updating Alliance Auth, especially across major versions, ensure all installed community applications are compatible. Incompatible apps can break your Auth installation or cause unexpected behavior.
Fix: Always check the changelogs and update instructions for both Alliance Auth and all your installed community apps before performing an upgrade. Pin app versions in `requirements.txt` to prevent unsupervised breaking upgrades.

Install

pip install allianceauth gunicorn superlance Install core library and recommended tools

Imports

Django URL patterns for Alliance Auth
```
from django.urls import include, path

urlpatterns = [
    path('', include('allianceauth.urls')),
    # ... other app URLs
]
```
Alliance Auth is typically included as a full Django application. Its URLs are included in your project's main urls.py.

Adding Alliance Auth to INSTALLED_APPS

INSTALLED_APPS = [
    # ... other Django/community apps
    'allianceauth',
    'allianceauth.authentication',
    'allianceauth.eveonline',
    # ... other required Alliance Auth apps
]

The core 'allianceauth' and its sub-applications are added to Django's INSTALLED_APPS in settings/local.py to enable functionality.

Quickstart

This quickstart outlines the essential steps to initialize a new Alliance Auth project, install its dependencies, configure basic settings, perform database migrations, create an administrative user, and run the development server. For production, Gunicorn and Supervisor are recommended for managing the application and background tasks.

# Assuming Python 3.x and a virtual environment are active, and system dependencies (DB, Redis) are installed.

# 1. Install Alliance Auth and recommended WSGI server/monitoring tools
pip install allianceauth gunicorn superlance

# 2. Create your Alliance Auth project (replace 'myauth' with your desired project name)
allianceauth start myauth

# 3. Navigate into the new project directory
cd myauth

# 4. Configure your EVE SSO application and database settings
#    Edit myauth/settings/local.py to set EVE_CLIENT_ID, EVE_SECRET_KEY, EVE_CALLBACK_URL,
#    and configure your DATABASES and EMAIL_URL.

# 5. Run database migrations
python manage.py migrate

# 6. Create an admin superuser
python manage.py createsuperuser

# 7. Collect static files
python manage.py collectstatic --noinput

# 8. Start the development server (for testing only, use gunicorn/supervisor for production)
python manage.py runserver 0.0.0.0:8000

# Access your site at http://localhost:8000 and log in with your superuser account via /admin.

view raw JSON →