Alliance Auth

This document describes how to install Alliance Auth from scratch.

Note

There are additional installation steps for activating services and apps that come with Alliance Auth. Please see the page for the respective service or apps in chapter Features for details.

Dependencies

Operating Systems

Alliance Auth can be installed on any in-support *nix operating system.

Our install documentation targets the following operating systems.

  • Ubuntu 18.04

  • Ubuntu 20.04

  • Ubuntu 22.04

  • Centos 7

  • CentOS Stream 8

  • CentOS Stream 9

To install on your favorite flavour of Linux, identify and install equivalent packages to the ones listed here.

OS Maintenance

It is reccommended to ensure your OS is fully up to date before proceeding. We may also add Package Repositories here, used later in the documentation.

Ubuntu 1804, 2004, 2204:

sudo apt-get update
sudo apt-get upgrade
sudo do-dist-upgrade

CentOS 7

yum install epel-release
sudo yum upgrade

CentOS Stream 8

sudo dnf config-manager --set-enabled powertools
sudo dnf install epel-release epel-next-release
sudo yum upgrade

CentOS Stream 9

sudo dnf config-manager --set-enabled crb
dnf install epel-release epel-next-release
sudo yum upgrade

Python

Alliance Auth requires Python 3.8 or higher. Ensure it is installed on your server before proceeding.

Ubuntu 1804, 2004:

Note

Ubuntu 2204 ships with Python 3.10 already

sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt-get update
sudo apt-get install python3.10 python3.10-dev python3.10-venv

CentOS 7: We need to build Python from source

Centos Stream 8/9:

Note

A Python 3.9 Package is available for Stream 8 and 9. You _may_ use this instead of building your own package. But our documentation will assume Python3.10 and you may need to substitute as neccessary sudo dnf install python39 python39-devel

cd ~
sudo yum install gcc openssl-devel bzip2-devel libffi-devel wget
wget https://www.python.org/ftp/python/3.10.5/Python-3.10.5.tgz
tar xvf Python-3.10.5.tgz
cd Python-3.10.5/
./configure --enable-optimizations --enable-shared
sudo make altinstall

Database

It’s recommended to use a database service instead of SQLite. Many options are available, but this guide will use MariaDB.

Note

Many Ubuntu distributions come with an older version of Maria DB, which is not compatible with Alliance Auth. You need Maria DB 10.3 or higher!

Ubuntu 1804, 2004, 2204:

Warning

Please follow these steps to update MariaDB https://mariadb.org/download/?t=repo-config&d=20.04+%22focal%22&v=10.6&r_m=osuosl

Ubuntu 1804, 2004, 2204

apt-get install mariadb-server mariadb-client libmysqlclient-dev

CentOS 7

sudo yum install MariaDB-server MariaDB-client MariaDB-devel MariaDB-shared

CentOS Stream 8/9

Note

We reccomend using the built in AppStream, as they are maintained by CentOS. Currently an AppStream is not available for 10.6

sudo dnf module enable mariadb:10.5
sudo dnf install mariadb mariadb-server mariadb-devel
sudo systemctl enable mariadb
sudo systemctl start mariadb

Important

If you don’t plan on running the database on the same server as auth you still need to install the libmysqlclient-dev package on Ubuntu or mariadb-devel package on CentOS.

Redis and Other Tools

A few extra utilities are also required for installation of packages.

Ubuntu 1804, 2004, 2204:

sudo apt-get install unzip git redis-server curl libssl-dev libbz2-dev libffi-dev build-essential

CentOS 7:

sudo yum install gcc gcc-c++ unzip git redis curl bzip2-devel openssl-devel libffi-devel wget
sudo systemctl enable redis.service
sudo systemctl start redis.service

CentOS Stream 8, Stream 9:

sudo dnf install gcc gcc-c++ unzip git redis curl bzip2-devel openssl-devel libffi-devel wget
sudo systemctl enable redis.service
sudo systemctl start redis.service

Database Setup

Alliance Auth needs a MySQL user account and database. Open an SQL shell with

sudo mysql -u root

and create them as follows, replacing PASSWORD with an actual secure password:

CREATE USER 'allianceserver'@'localhost' IDENTIFIED BY 'PASSWORD';
CREATE DATABASE alliance_auth CHARACTER SET utf8mb4;
GRANT ALL PRIVILEGES ON alliance_auth . * TO 'allianceserver'@'localhost';

Once your database is set up, you can leave the SQL shell with exit.

Add timezone tables to your mysql installation:

mysql_tzinfo_to_sql /usr/share/zoneinfo | sudo mysql -u root mysql

Note

You may see errors when you add the timezone tables. To make sure that they were correctly added run the following commands and check for the time_zone tables:

mysql -u root -p
use mysql;
show tables;

Close the SQL shell and secure your database server with this command:

mysql_secure_installation

Auth Install

User Account

For security and permissions, it’s highly recommended you create a separate user to install auth under. Do not log in as this account.

Ubuntu 1804, 2004, 2204:

adduser --disabled-login allianceserver

CentOS 7, Stream 8, Stream 9:

sudo useradd -s /bin/bash allianceserver
sudo passwd -l allianceserver

Prepare Directories

sudo mkdir -p /var/www/myauth/static
sudo chown -R allianceserver:allianceserver /var/www/myauth/static/

Note

When installing and performing maintenance on Alliance Auth, using the allianceserver user will greatly simplify permission management:

sudo su allianceserver

Virtual Environment

Create a Python virtual environment and put it somewhere convenient (e.g. /home/allianceserver/venv/auth/)

Note

Your python3.x command/version may vary depending on your installed python version.

python3.10 -m venv /home/allianceserver/venv/auth/

Tip

A virtual environment provides support for creating a lightweight “copy” of Python with their own site directories. Each virtual environment has its own Python binary (allowing creation of environments with various Python versions) and can have its own independent set of installed Python packages in its site directories. You can read more about virtual environments on the Python docs.

Activate the virtual environment with (Note the /bin/activate on the end of the path):

source /home/allianceserver/venv/auth/bin/activate

Hint

Each time you come to do maintenance on your Alliance Auth installation, you should activate your virtual environment first. When finished, deactivate it with the deactivate command.

Eve Online SSO

You need to have a dedicated Eve SSO app for Alliance auth. Please go to EVE Developer to create one.

For scopes your SSO app needs to have at least publicData. Additional scopes depends on which Alliance Auth apps you will be using. For convenience, we recommend adding all available ESO scopes to your SSO app. Note that Alliance Auth will always ask the users to approve specific scopes before they are used.

As callback URL you want to define the URL of your Alliance Auth site plus the route: /sso/callback. Example for a valid callback URL: https://auth.example.com/sso/callback

In local.py you will need to set ESI_USER_CONTACT_EMAIL to an email address to ensure that CCP has reliable contact information for you.

Alliance Auth Project

Update Pip before installing python packages:

pip install -U pip setuptools

Ensure wheel is available before continuing:

pip install wheel

You can install Alliance Auth with the following command. This will install AA and all its Python dependencies.

pip install allianceauth

You should also install Gunicorn now unless you want to use another WSGI server (see Gunicorn for details):

pip install gunicorn

Now you need to create the application that will run the Alliance Auth install. Ensure you are in the allianceserver home directory by issuing:

cd /home/allianceserver

The following command bootstraps a Django project which will run your Alliance Auth instance. You can rename it from myauth to anything you’d like. Note that this name is shown by default as the site name but that can be changed later.

allianceauth start myauth

The settings file needs configuring. Edit the template at myauth/myauth/settings/local.py. Be sure to configure the EVE SSO as defined earlier in Eve Online Settings and valid Email settings.

Django needs to install models to the database before it can start.

python /home/allianceserver/myauth/manage.py migrate

Now we need to round up all the static files required to render templates. Make a directory to serve them from and populate it.

python /home/allianceserver/myauth/manage.py collectstatic

Check to ensure your settings are valid.

python /home/allianceserver/myauth/manage.py check

Hint

If you are using root, ensure the allianceserver user has read/write permissions to this directory before proceeding:

chown -R allianceserver:allianceserver /home/allianceserver/myauth

Services

Alliance Auth needs some additional services to run, which we will set up and configure next.

Gunicorn

To run the Alliance Auth website a WSGI Server is required. For this Gunicorn is highly recommended for its ease of configuring. It can be manually run from within your myauth base directory with gunicorn --bind 0.0.0.0 myauth.wsgi or automatically run using Supervisor.

The default configuration is good enough for most installations. Additional information is available in the gunicorn doc.

Superuser

Before using your auth site, it is essential to create a superuser account. This account will have all permissions in Alliance Auth. It’s OK to use this as your personal auth account.

python /home/allianceserver/myauth/manage.py createsuperuser

Once your install is complete, the superuser account is accessed by logging in via the admin site at https://example.com/admin.

If you intend to use this account as your personal auth account you need to add a main character. Navigate to the normal user dashboard (at https://example.com) after logging in via the admin site and select Change Main. Once a main character has been added, it is possible to use SSO to login to this account.

Supervisor

Supervisor is a process watchdog service: it makes sure other processes are started automatically and kept running. It can be used to automatically start the WSGI server and Celery workers for background tasks.

Note

You will need to exit the allianceserver user back to a user with sudo capabilities to install supervisor:

exit

Ubuntu 1804, 2004, 2204:

sudo apt-get install supervisor

CentOS 7:

sudo dnf install supervisor
sudo systemctl enable supervisord.service
sudo systemctl start supervisord.service

CentOS Stream 8, Stream 9:

sudo dnf install supervisor
sudo systemctl enable supervisord.service
sudo systemctl start supervisord.service

Once installed, it needs a configuration file to know which processes to watch. Your Alliance Auth project comes with a ready-to-use template which will ensure the Celery workers, Celery task scheduler and Gunicorn are all running.

Ubuntu 1804, 2004:

ln -s /home/allianceserver/myauth/supervisor.conf /etc/supervisor/conf.d/myauth.conf

CentOS:

ln -s /home/allianceserver/myauth/supervisor.conf /etc/supervisord.d/myauth.ini

Activate it with supervisorctl reload.

You can check the status of the processes with supervisorctl status. Logs from these processes are available in /home/allianceserver/myauth/log named by process.

Note

Any time the code or your settings change you’ll need to restart Gunicorn and Celery.

supervisorctl restart myauth:

Webserver

Once installed, decide on whether you’re going to use NGINX or Apache and follow the respective guide.

Note that Alliance Auth is designed to run with web servers on HTTPS. While running on HTTP is technically possible, it is not recommended for production use, and some functions (e.g. Email confirmation links) will not work properly.

Updating

Periodically new releases are issued with bug fixes and new features. Be sure to read the release notes which will highlight changes.

To update your install, swap to your allianceserver user

sudo su allianceserver

Activate your virtual environment

source /home/allianceserver/venv/auth/bin/activate

and update with:

pip install --upgrade allianceauth

Some releases come with changes to the base settings. Update your project’s settings with:

allianceauth update /home/allianceserver/myauth

Some releases come with new or changed models. Update your database to reflect this with:

python /home/allianceserver/myauth/manage.py migrate

Finally, some releases come with new or changed static files. Run the following command to update your static files folder:

python /home/allianceserver/myauth/manage.py collectstatic

Always restart AA, Celery and Gunicorn after updating:

supervisorctl restart myauth: