{"id":7925,"library":"allianceauth","title":"Alliance Auth","description":"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.","status":"active","version":"4.13.1","language":"en","source_language":"en","source_url":"https://gitlab.com/allianceauth/allianceauth","tags":["eve-online","authentication","django","sso","community-management","game-integration"],"install":[{"cmd":"pip install allianceauth gunicorn superlance","lang":"bash","label":"Install core library and recommended tools"}],"dependencies":[{"reason":"Requires Python 3.8 to <3.13 for version 4.x. Upcoming v5.x will drop 3.8/3.9 and target 3.12/3.13.","package":"Python","optional":false},{"reason":"Alliance Auth is a Django application framework. v4.x supports Django up to 4.2.x; v5.x will require Django 5.2.","package":"Django","optional":false},{"reason":"A robust database is required for production. SQLite is available for development but not recommended for production.","package":"MariaDB/MySQL or PostgreSQL","optional":false},{"reason":"Used for caching and Celery task queue management.","package":"Redis","optional":false}],"imports":[{"note":"Alliance Auth is typically included as a full Django application. Its URLs are included in your project's main urls.py.","symbol":"Django URL patterns for Alliance Auth","correct":"from django.urls import include, path\n\nurlpatterns = [\n    path('', include('allianceauth.urls')),\n    # ... other app URLs\n]"},{"note":"The core 'allianceauth' and its sub-applications are added to Django's INSTALLED_APPS in settings/local.py to enable functionality.","symbol":"Adding Alliance Auth to INSTALLED_APPS","correct":"INSTALLED_APPS = [\n    # ... other Django/community apps\n    'allianceauth',\n    'allianceauth.authentication',\n    'allianceauth.eveonline',\n    # ... other required Alliance Auth apps\n]"}],"quickstart":{"code":"# Assuming Python 3.x and a virtual environment are active, and system dependencies (DB, Redis) are installed.\n\n# 1. Install Alliance Auth and recommended WSGI server/monitoring tools\npip install allianceauth gunicorn superlance\n\n# 2. Create your Alliance Auth project (replace 'myauth' with your desired project name)\nallianceauth start myauth\n\n# 3. Navigate into the new project directory\ncd myauth\n\n# 4. Configure your EVE SSO application and database settings\n#    Edit myauth/settings/local.py to set EVE_CLIENT_ID, EVE_SECRET_KEY, EVE_CALLBACK_URL,\n#    and configure your DATABASES and EMAIL_URL.\n\n# 5. Run database migrations\npython manage.py migrate\n\n# 6. Create an admin superuser\npython manage.py createsuperuser\n\n# 7. Collect static files\npython manage.py collectstatic --noinput\n\n# 8. Start the development server (for testing only, use gunicorn/supervisor for production)\npython manage.py runserver 0.0.0.0:8000\n\n# Access your site at http://localhost:8000 and log in with your superuser account via /admin.","lang":"bash","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=5.0.0 (beta versions already released)"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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+).","message":"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.","severity":"gotcha","affected_versions":"<4.x when using MariaDB <10.2"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions, particularly major upgrades (e.g., 3.x to 4.x, 4.x to 5.x)"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","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.","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.","error":"Error 500 trying to connect to the website on a new install"},{"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.","cause":"The directory designated for logs does not have the correct write permissions for the user running the Alliance Auth application.","error":"Failed to configure log handler"},{"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`).","cause":"The Celery worker or beat processes, which handle background tasks like group synchronization, are not running or are encountering errors.","error":"Groups aren't syncing to services / Tasks are not running"},{"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).","cause":"Gunicorn is not being executed from the correct directory, preventing it from finding the Django project's WSGI file.","error":"Unable to execute 'gunicorn myauth.wsgi' or ImportError: No module named 'myauth.wsgi'"},{"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`).","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`).","error":"pip install -r requirements.txt is failing"}]}