Mathis/allianceauth
1
0
Fork 0
mirror of https://gitlab.com/allianceauth/allianceauth.git synced 2025-12-18 06:45:04 +01:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'master' of gitlab.com:allianceauth/allianceauth into v4.x

Browse Source
This commit is contained in:
Ariel Rin
2023-12-08 14:49:56 +10:00
parent dba3c651dc 23a3dd1ab9
commit 20067c1133
94 changed files with 2865 additions and 1642 deletions
Download Patch File Download Diff File Expand all files Collapse all files

507
docs/installation/allianceauth.md
View File

@@ -2,10 +2,9 @@
This document describes how to install **Alliance Auth** from scratch.
```eval_rst
.. 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 :doc:`/features/index` for details.
```
:::{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 :doc:`/features/index` for details.
:::
## Dependencies
@@ -15,7 +14,6 @@ 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
@@ -28,234 +26,213 @@ To install on your favorite flavour of Linux, identify and install equivalent pa
It is recommended 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:
::::{tabs}
:::{group-tab} Ubuntu 2004, 2204
```bash
```shell
sudo apt-get update
```
```bash
sudo apt-get upgrade
```
```bash
sudo do-dist-upgrade
```
CentOS 7:
:::
:::{group-tab} CentOS 7
```bash
```shell
yum install epel-release
```
```bash
sudo yum upgrade
```
CentOS Stream 8:
:::
:::{group-tab} CentOS Stream 8
```bash
```shell
sudo dnf config-manager --set-enabled powertools
```
```bash
sudo dnf install epel-release epel-next-release
```
```bash
sudo yum upgrade
```
CentOS Stream 9:
:::
:::{group-tab} CentOS Stream 9
```bash
```shell
sudo dnf config-manager --set-enabled crb
```
```bash
dnf install epel-release epel-next-release
```
```bash
sudo dnf install epel-release epel-next-release
sudo yum upgrade
```
:::
::::
### Python
Install Python 3.10 and related tools on your system.
Install Python 3.11 and related tools on your system.
Ubuntu 1804, 2004:
::::{tabs}
```bash
:::{group-tab} Ubuntu 2004, 2204
```shell
sudo add-apt-repository ppa:deadsnakes/ppa
```
```bash
sudo apt-get update
sudo apt-get install python3.11 python3.11-dev python3.11-venv
```
```bash
sudo apt-get install python3.10 python3.10-dev python3.10-venv
```
Ubuntu 2204:
```eval_rst
.. note::
Ubuntu 2204 ships with Python 3.10 already, but some important tools are missing in the default installation.
```
```bash
sudo apt-get install python3.10-dev python3.10-venv
```
CentOS 7:
:::
:::{group-tab} CentOS 7
We need to build Python from source
Centos Stream 8/9:
```eval_rst
.. 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 necessary
sudo dnf install python39 python39-devel
```
```bash
cd ~
```
```bash
sudo yum install gcc openssl-devel bzip2-devel libffi-devel wget
```
```bash
wget https://www.python.org/ftp/python/3.10.5/Python-3.10.5.tgz
```
```bash
tar xvf Python-3.10.5.tgz
```
```bash
cd Python-3.10.5/
```
```bash
wget https://www.python.org/ftp/python/3.11.5/Python-3.11.5.tgz
tar xvf Python-3.11.5.tgz
cd Python-3.11.5/
./configure --enable-optimizations --enable-shared
sudo make altinstall
```
:::
:::{group-tab} CentOS Stream 8
We need to build Python from source
```bash
cd ~
sudo yum install gcc openssl-devel bzip2-devel libffi-devel wget
wget https://www.python.org/ftp/python/3.11.5/Python-3.11.5.tgz
tar xvf Python-3.11.5.tgz
cd Python-3.11.5/
./configure --enable-optimizations --enable-shared
sudo make altinstall
```
:::
:::{group-tab} CentOS Stream 9
We need to build Python from source
```bash
cd ~
sudo yum install gcc openssl-devel bzip2-devel libffi-devel wget
wget https://www.python.org/ftp/python/3.11.5/Python-3.11.5.tgz
tar xvf Python-3.11.5.tgz
cd Python-3.11.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.
It's recommended to use a database service instead of SQLite. Many options are available, but this guide will use MariaDB 10.11
```eval_rst
.. note::
Ubuntu distributions prior to 20.04 come with an older version of Maria DB, which is not compatible with **Alliance Auth**. You need Maria DB 10.3 or higher!
For 20.04 we still recommend to install Maria DB from the link below in order to get the newest stable version.
For 22.04 we recommend installing from the default Ubuntu distro, since it comes with the newest stable version.
```
::::{tabs}
Ubuntu 1804, 2004:
:::{group-tab} Ubuntu 2004, 2204
Follow the instructions at <https://mariadb.org/download/?t=repo-config&d=20.04+%22focal%22&v=10.11&r_m=osuosl> to add the MariaDB repository to your host.
```eval_rst
.. 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
```bash
```shell
sudo apt-get install mariadb-server mariadb-client libmysqlclient-dev
```
CentOS 7:
:::
:::{group-tab} CentOS 7
Follow the instructions at <https://mariadb.org/download/?t=repo-config&d=CentOS+7&v=10.11&r_m=osuosl> to add the MariaDB repository to your host.
```eval_rst
.. warning::
Please follow these steps to update MariaDB
https://mariadb.org/download/?t=repo-config&d=CentOS+7+%28x86_64%29&v=10.6&r_m=osuosl
```
```bash
```shell
sudo yum install MariaDB-server MariaDB-client MariaDB-devel MariaDB-shared
```
CentOS Stream 8/9:
:::
:::{group-tab} CentOS Stream 8
Follow the instructions at <https://mariadb.org/download/?t=repo-config&d=CentOS+Stream&v=10.11&r_m=osuosl> to add the MariaDB repository to your host.
```eval_rst
.. note::
We recommend using the built in AppStream, as they are maintained by CentOS. Currently an AppStream is not available for 10.6
```
```bash
sudo dnf module enable mariadb:10.5
```
```bash
```shell
sudo dnf install mariadb mariadb-server mariadb-devel
```
```bash
sudo systemctl enable mariadb
:::
:::{group-tab} CentOS Stream 9
Follow the instructions at <https://mariadb.org/download/?t=repo-config&d=CentOS+Stream&v=10.11&r_m=osuosl> to add the MariaDB repository to your host.
```shell
sudo dnf install mariadb mariadb-server mariadb-devel
```
```bash
sudo systemctl start mariadb
```
:::
::::
```eval_rst
.. 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.
```
:::::{important}
::::{tabs}
:::{group-tab} Ubuntu 2004, 2204
If you don't plan on running the database on the same server as auth you still need to install the `libmysqlclient-dev` package
:::
:::{group-tab} CentOS 7
If you don't plan on running the database on the same server as auth you still need to install the `mariadb-devel` package
:::
:::{group-tab} CentOS Stream 8
If you don't plan on running the database on the same server as auth you still need to install the `mariadb-devel` package
:::
:::{group-tab} CentOS Stream 9
If you don't plan on running the database on the same server as auth you still need to install the `mariadb-devel` package
:::
::::
:::::
### Redis and Other Tools
A few extra utilities are also required for installation of packages.
Ubuntu 1804, 2004, 2204:
::::{tabs}
```bash
:::{group-tab} Ubuntu 2004, 2204
```shell
sudo apt-get install unzip git redis-server curl libssl-dev libbz2-dev libffi-dev build-essential pkg-config
```
CentOS 7:
:::
:::{group-tab} CentOS 7
```bash
```shell
sudo yum install gcc gcc-c++ unzip git redis curl bzip2-devel openssl-devel libffi-devel wget pkg-config
```
```bash
```shell
sudo systemctl enable redis.service
```
```bash
sudo systemctl start redis.service
```
CentOS Stream 8, Stream 9:
:::
:::{group-tab} CentOS Stream 8
```bash
```shell
sudo dnf install gcc gcc-c++ unzip git redis curl bzip2-devel openssl-devel libffi-devel wget
```
```bash
```shell
sudo systemctl enable redis.service
```
```bash
sudo systemctl start redis.service
```
:::
:::{group-tab} CentOS Stream 9
```shell
sudo dnf install gcc gcc-c++ unzip git redis curl bzip2-devel openssl-devel libffi-devel wget
```
```shell
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
```bash
```shell
sudo mysql -u root
```
@@ -271,22 +248,24 @@ Once your database is set up, you can leave the SQL shell with `exit`.
Add timezone tables to your mysql installation:
```bash
```shell
mysql_tzinfo_to_sql /usr/share/zoneinfo | sudo mysql -u root mysql
```
```eval_rst
.. 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::
:::{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;
```shell
mysql -u root -p
use mysql;
show tables;
```
:::
Close the SQL shell and secure your database server with this command:
```bash
```shell
mysql_secure_installation
```
@@ -295,86 +274,96 @@ mysql_secure_installation
### 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.
::::{tabs}
Ubuntu 1804, 2004, 2204:
:::{group-tab} Ubuntu 2004, 2204
```bash
sudo adduser --disabled-login allianceserver
```
CentOS 7, Stream 8, Stream 9:
```bash
```shell
sudo useradd -s /bin/bash allianceserver
```
```bash
:::
:::{group-tab} CentOS 7
```shell
sudo passwd -l allianceserver
```
:::
:::{group-tab} CentOS Stream 8
```shell
sudo passwd -l allianceserver
```
:::
:::{group-tab} CentOS Stream 9
```shell
sudo passwd -l allianceserver
```
:::
::::
### Prepare Directories
```bash
```shell
sudo mkdir -p /var/www/myauth/static
```
```bash
```shell
sudo chown -R allianceserver:allianceserver /var/www/myauth/static/
```
```eval_rst
.. note::
When installing and performing maintenance on Alliance Auth, using the allianceserver user will greatly simplify permission management::
:::{warning}
When installing and performing maintenance on Alliance Auth, virtual environments and python packages, _sudo_ means _superuser_ _do_, this will not use your venv or your allianceserver user and will routinely break your permission structure.
sudo su allianceserver
Only use sudo for _system_ management or if you are unsure, when explicitly instructed to do so.
```shell
sudo su allianceserver
```
:::
### Virtual Environment
Switch to the allianceserver user.
```bash
```shell
sudo su allianceserver
```
And switch to it's home directory:
```bash
cd
```
```eval_rst
.. note::
In general using the allianceserver user will greatly simplify permission management, when installing and performing maintenance on Alliance Auth.
```shell
cd ~
```
Create a Python virtual environment and put it somewhere convenient (e.g. `/home/allianceserver/venv/auth/`)
```eval_rst
.. note::
Your python3.x command/version may vary depending on your installed python version.
:::{note}
Your python3.x command/version may vary depending on your installed python version.
:::
```shell
python3.11 -m venv /home/allianceserver/venv/auth/
```
```bash
python3.10 -m venv /home/allianceserver/venv/auth/
```
```eval_rst
.. 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.
.. _Python: https://docs.python.org/3/library/venv.html
```
:::{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. <https://docs.python.org/3/library/venv.html>
:::
Activate the virtual environment with (Note the `/bin/activate` on the end of the path):
```bash
```shell
source /home/allianceserver/venv/auth/bin/activate
```
```eval_rst
.. 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.
```
:::{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
@@ -386,22 +375,21 @@ As **callback URL** you want to define the URL of your Alliance Auth site plus t
### Alliance Auth Project
```eval_rst
.. warning::
Before installing any Python packages please double-check that you have activated in the virtual environment. This is usually indicated by your command line in the terminal starting with: `(auth)`.
```
:::{warning}
Before installing any Python packages please double-check that you have activated in the virtual environment. This is usually indicated by your command line in the terminal starting with: `(auth)`.
:::
#### Install Python packages
Update & install basic tools before installing further Python packages:
```bash
```shell
pip install -U pip setuptools wheel
```
You can install **Alliance Auth** with the following command. This will install AA, AA's Python dependencies, superlance for memory monitoring and gunicorn as a wsgi server
```bash
```shell
pip install allianceauth superlance gunicorn
```
@@ -409,13 +397,13 @@ pip install allianceauth superlance gunicorn
Now you need to create the Django project that will run **Alliance Auth**. Ensure you are in the allianceserver home directory by issuing:
```bash
```shell
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.
```bash
```shell
allianceauth start myauth
```
@@ -423,7 +411,7 @@ allianceauth start myauth
Your settings file needs configuring:
```bash
```shell
nano myauth/myauth/settings/local.py
```
@@ -439,34 +427,36 @@ nano myauth/myauth/settings/local.py
Django needs to setup the database before it can start.
```bash
```shell
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.
```bash
```shell
python /home/allianceserver/myauth/manage.py collectstatic --noinput
```
Check to ensure your settings are valid.
```bash
```shell
python /home/allianceserver/myauth/manage.py check
```
```eval_rst
.. hint::
If you are using root, ensure the allianceserver user has read/write permissions to this directory before proceeding::
:::{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
```shell
chown -R allianceserver:allianceserver /home/allianceserver/myauth
```
:::
#### Setup 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.
```bash
```shell
python /home/allianceserver/myauth/manage.py createsuperuser
```
@@ -488,72 +478,117 @@ The default configuration is good enough for most installations. Additional info
[Supervisor](http://supervisord.org/) 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.
```eval_rst
.. note::
:::{note}
You will need to exit the allianceserver user back to a user with sudo capabilities to install supervisor::
exit
```shell
exit
```
Ubuntu 1804, 2004, 2204:
:::
```bash
::::{tabs}
:::{group-tab} Ubuntu 2004, 2204
```shell
sudo apt-get install supervisor
```
CentOS 7:
:::
:::{group-tab} CentOS 7
```bash
```shell
sudo dnf install supervisor
```
```bash
```shell
sudo systemctl enable supervisord.service
```
```bash
```shell
sudo systemctl start supervisord.service
```
CentOS Stream 8, Stream 9:
:::
:::{group-tab} CentOS Stream 8
```bash
```shell
sudo dnf install supervisor
```
```bash
```shell
sudo systemctl enable supervisord.service
```
```bash
```shell
sudo systemctl start supervisord.service
```
:::
:::{group-tab} CentOS Stream 9
```shell
sudo dnf install supervisor
```
```shell
sudo systemctl enable supervisord.service
```
```shell
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.
::::{tabs}
Ubuntu 1804, 2004:
:::{group-tab} Ubuntu 2004, 2204
```bash
```shell
ln -s /home/allianceserver/myauth/supervisor.conf /etc/supervisor/conf.d/myauth.conf
```
CentOS:
:::
:::{group-tab} CentOS 7
```bash
```shell
sudo ln -s /home/allianceserver/myauth/supervisor.conf /etc/supervisord.d/myauth.ini
```
:::
:::{group-tab} CentOS Stream 8
```shell
sudo ln -s /home/allianceserver/myauth/supervisor.conf /etc/supervisord.d/myauth.ini
```
:::
:::{group-tab} CentOS Stream 9
```shell
sudo ln -s /home/allianceserver/myauth/supervisor.conf /etc/supervisord.d/myauth.ini
```
:::
::::
Activate it with `sudo supervisorctl reload`.
You can check the status of the processes with `sudo supervisorctl status`. Logs from these processes are available in `/home/allianceserver/myauth/log` named by process.
```eval_rst
.. note::
Any time the code or your settings change you'll need to restart Gunicorn and Celery. ::
:::{note}
Any time the code or your settings change you'll need to restart Gunicorn and Celery. ::
sudo supervisorctl restart myauth:
```shell
sudo supervisorctl restart myauth:
```
:::
## Web server
Once installed, decide on whether you're going to use [NGINX](nginx.md) or [Apache](apache.md) and follow the respective guide.
@@ -566,42 +601,42 @@ Periodically [new releases](https://gitlab.com/allianceauth/allianceauth/tags) a
To update your install, swap to your allianceserver user
```bash
```shell
sudo su allianceserver
```
Activate your virtual environment
```bash
```shell
source /home/allianceserver/venv/auth/bin/activate
```
and update with:
```bash
```shell
pip install -U allianceauth
```
Some releases come with changes to the base settings. Update your project's settings with:
```bash
```shell
allianceauth update /home/allianceserver/myauth
```
Some releases come with new or changed models. Update your database to reflect this with:
```bash
```shell
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:
```bash
```shell
python /home/allianceserver/myauth/manage.py collectstatic --noinput
```
Always restart AA, Celery and Gunicorn after updating:
```bash
```shell
supervisorctl restart myauth:
```

103
docs/installation/apache.md
View File

@@ -8,68 +8,115 @@ If you're using a small VPS to host services with very limited memory, consider
## Installation
Ubuntu 1804, 2004:
```bash
::::{tabs}
:::{group-tab} Ubuntu 2004, 2204
```shell
apt-get install apache2
```
CentOS 7:
```bash
:::
:::{group-tab} CentOS 7
```shell
yum install httpd
```
Centos Stream 8, Stream 9
```bash
:::
:::{group-tab} CentOS Stream 8
```shell
dnf install httpd
```
CentOS 7, Stream 8, Stream 9
```bash
:::
:::{group-tab} CentOS Stream 9
```shell
systemctl enable httpd
```
```bash
systemctl start httpd
```
:::
::::
CentOS 7, Stream 8, Stream 9
## Configuration
### Permissions
Apache needs to be able to read the folder containing your auth project's static files.
Ubuntu 1804, 2004:
```
::::{tabs}
:::{group-tab} Ubuntu 2004, 2204
```shell
chown -R www-data:www-data /var/www/myauth/static
```
CentOS 7, Stream 8, Stream 9
```
:::
:::{group-tab} CentOS 7
```shell
chown -R apache:apache /var/www/myauth/static
```
:::
:::{group-tab} CentOS Stream 8
```shell
chown -R apache:apache /var/www/myauth/static
```
:::
:::{group-tab} CentOS Stream 9
```shell
chown -R apache:apache /var/www/myauth/static
```
:::
::::
### Further Configuration
Apache serves sites through defined virtual hosts. These are located in `/etc/apache2/sites-available/` on Ubuntu and `/etc/httpd/conf.d/httpd.conf` on CentOS.
A virtual host for auth need only proxy requests to your WSGI server (Gunicorn if you followed the install guide) and serve static files. Examples can be found below. Create your config in its own file e.g. `myauth.conf`
### Ubuntu
::::{tabs}
:::{group-tab} Ubuntu 2004, 2204
To proxy and modify headers a few mods need to be enabled.
```bash
```shell
a2enmod proxy
a2enmod proxy_http
a2enmod headers
```
Create a new config file for auth e.g. `/etc/apache2/sites-available/myauth.conf` and fill out the virtual host configuration. To enable your config use `a2ensite myauth.conf` and then reload apache with `service apache2 reload`.
:::
:::{group-tab} CentOS 7
Place your virtual host configuration in the appropriate section within `/etc/httpd/conf.d/httpd.conf` and restart the httpd service with `systemctl restart httpd`.
:::
:::{group-tab} CentOS Stream 8
Place your virtual host configuration in the appropriate section within `/etc/httpd/conf.d/httpd.conf` and restart the httpd service with `systemctl restart httpd`.
:::
:::{group-tab} CentOS Stream 9
Place your virtual host configuration in the appropriate section within `/etc/httpd/conf.d/httpd.conf` and restart the httpd service with `systemctl restart httpd`.
:::
::::
```eval_rst
.. warning::
In some scenarios, the Apache default page is still enabled. To disable it use::
a2dissite 000-default.conf
:::{warning}
In some scenarios, the Apache default page is still enabled. To disable it use
```shell
a2dissite 000-default.conf
```
:::
### CentOS
Place your virtual host configuration in the appropriate section within `/etc/httpd/conf.d/httpd.conf` and restart the httpd service with `systemctl restart httpd`.
## Sample Config File
```
```ini
<VirtualHost *:80>
ServerName auth.example.com
@@ -107,7 +154,7 @@ It's 2018 - there's no reason to run a site without SSL. The EFF provides free,
After acquiring SSL the config file needs to be adjusted. Add the following lines inside the `<VirtualHost>` block:
```
```ini
RequestHeader set X-FORWARDED-PROTOCOL https
RequestHeader set X-FORWARDED-SSL On
```

26
docs/installation/gunicorn.md
View File

@@ -6,23 +6,21 @@ If you find Apache's `mod_wsgi` to be a headache or want to use NGINX (or some o
Check out the full [Gunicorn docs](http://docs.gunicorn.org/en/latest/index.html).
```eval_rst
.. note::
The page contains additional steps on how to setup and configure Gunicorn that are not required for users who decide to stick with the default Gunicorn configuration as described in the main installation guide for AA.
```
:::{note}
The page contains additional steps on how to setup and configure Gunicorn that are not required for users who decide to stick with the default Gunicorn configuration as described in the main installation guide for AA.
:::
## Setting up Gunicorn
```eval_rst
.. note::
If you're using a virtual environment, activate it now::
sudo su allianceserver
source /home/allianceserver/venv/auth/bin/activate
```
:::{note}
If you're using a virtual environment, activate it now::
sudo su allianceserver
source /home/allianceserver/venv/auth/bin/activate
:::
Install Gunicorn using pip
```bash
```shell
pip install gunicorn
```
@@ -38,7 +36,7 @@ If you are following this guide, we already use [Supervisor](allianceauth.md#sup
You'll want to edit `/etc/supervisor/conf.d/myauth.conf` (or whatever you want to call the config file)
```text
```ini
[program:gunicorn]
user = allianceserver
directory=/home/allianceserver/myauth/
@@ -49,6 +47,7 @@ autostart=true
autorestart=true
stopsignal=INT
```
- `[program:gunicorn]` - Change `gunicorn` to whatever you wish to call your process in Supervisor.
- `user = allianceserver` - Change to whatever user you wish Gunicorn to run as. You could even set this as allianceserver if you wished. I'll leave the question security of that up to you.
- `directory=/home/allianceserver/myauth/` - Needs to be the path to your Alliance Auth project.
@@ -81,6 +80,7 @@ Following this guide, you are running with a virtual environment. Therefore you'
e.g. `command=/path/to/venv/bin/gunicorn myauth.wsgi`
The example config is using the myauth venv from the main installation guide:
```ini
command=/home/allianceserver/venv/auth/bin/gunicorn myauth.wsgi
```
@@ -97,6 +97,6 @@ Any web server capable of proxy passing should be able to sit in front of Gunico
In the past when you made changes you restarted the entire Apache server. This is no longer required. When you update or make configuration changes that ask you to restart Apache, instead you can just restart Gunicorn:
```bash
```shell
supervisorctl restart myauth:gunicorn
```

19
docs/installation/index.md
View File

@@ -4,14 +4,13 @@ This chapter contains the main installation guides for **Alliance Auth**.
In addition to main guide for installation Alliance Auth you also find guides for configuring web servers (Apache, NGINX) and the recommended WSGI server (Gunicorn).
```eval_rst
.. toctree::
:maxdepth: 1
:::{toctree}
:maxdepth: 1
allianceauth
nginx
apache
gunicorn
upgrade_python
switch_to_non_root
```
allianceauth
nginx
apache
gunicorn
upgrade_python
switch_to_non_root
:::

51
docs/installation/nginx.md
View File

@@ -14,7 +14,7 @@ If you're converting from Apache, here are some things to consider.
Nginx is lightweight for a reason. It doesn't try to do everything internally and instead concentrates on just being a good HTTP server. This means that, unlike Apache, it won't automatically run PHP scripts via mod_php and doesn't have an internal WSGI server like mod_wsgi. That doesn't mean that it can't, just that it relies on external processes to run these instead. This might be good or bad depending on your outlook. It's good because it allows you to segment your applications, restarting Alliance Auth wont impact your PHP applications. On the other hand it means more config and more management of services. For some people it will be worth it, for others losing the centralised nature of Apache may not be worth it.
```eval_rst
```{eval-rst}
+-----------+----------------------------------------+
| Apache | Nginx Replacement |
+===========+========================================+
@@ -22,7 +22,6 @@ Nginx is lightweight for a reason. It doesn't try to do everything internally an
+-----------+----------------------------------------+
| mod_wsgi | Gunicorn or other external WSGI server |
+-----------+----------------------------------------+
```
Your .htaccess files won't work. Nginx has a separate way of managing access to folders via the server config. Everything you can do with htaccess files you can do with Nginx config. [Read more on the Nginx wiki](https://www.nginx.com/resources/wiki/start/topics/examples/likeapache-htaccess/)
@@ -33,36 +32,51 @@ Install Nginx via your preferred package manager or other method. If you need he
Nginx needs to be able to read the folder containing your auth project's static files. `chown -R nginx:nginx /var/www/myauth/static`.
```eval_rst
.. tip::
Some specific distros may use ``www-data:www-data`` instead of ``nginx:nginx``, causing static files (images, stylesheets etc) not to appear. You can confirm what user Nginx will run under by checking either its base config file ``/etc/nginx/nginx.conf`` for the "user" setting, or once Nginx has started ``ps aux | grep nginx``.
Adjust your chown commands to the correct user if needed.
..
```
:::{tip}
Some specific distros may use ``www-data:www-data`` instead of ``nginx:nginx``, causing static files (images, stylesheets etc) not to appear. You can confirm what user Nginx will run under by checking either its base config file ``/etc/nginx/nginx.conf`` for the "user" setting, or once Nginx has started ``ps aux | grep nginx``.
Adjust your chown commands to the correct user if needed.
:::
You will need to have [Gunicorn](gunicorn.md) or some other WSGI server setup for hosting Alliance Auth.
## Install
Ubuntu 1804, 2004, 2204:
```bash
::::{tabs}
:::{group-tab} Ubuntu 2004, 2204
```shell
sudo apt-get install nginx
```
CentOS 7
```bash
:::
:::{group-tab} CentOS 7
```shell
sudo yum install nginx
```
CentOS Stream 8, Stream 9:
```bash
:::
:::{group-tab} CentOS Stream 8
```shell
sudo dnf install nginx
```
:::
:::{group-tab} CentOS Stream 9
```shell
sudo dnf install nginx
```
:::
::::
Create a config file in `/etc/nginx/sites-available` (`/etc/nginx/conf.d` on CentOS) and call it `alliance-auth.conf` or whatever your preferred name is.
Create a symbolic link to enable the site (not needed on CentOS):
```bash
```shell
ln -s /etc/nginx/sites-available/alliance-auth.conf /etc/nginx/sites-enabled/
```
@@ -70,8 +84,7 @@ ln -s /etc/nginx/sites-available/alliance-auth.conf /etc/nginx/sites-enabled/
Copy this basic config into your config file. Make whatever changes you feel are necessary.
```
```ini
server {
listen 80;
listen [::]:80;
@@ -107,7 +120,7 @@ With [Let's Encrypt](https://letsencrypt.org/) offering free SSL certificates, t
Your config will need a few additions once you've got your certificate.
```
```ini
listen 443 ssl http2; # Replace listen 80; with this
listen [::]:443 ssl http2; # Replace listen [::]:80; with this
@@ -123,7 +136,7 @@ Your config will need a few additions once you've got your certificate.
If you want to redirect all your non-SSL visitors to your secure site, below your main configs `server` block, add the following:
```
```ini
server {
listen 80;
listen [::]:80;

186
docs/installation/upgrade_python.md
View File

@@ -4,10 +4,9 @@ This guide describes how to upgrade an existing Alliance Auth (AA) installation
This guide shares many similarities with the Alliance Auth install guide, but it is targeted towards existing installs needing to update.
```eval_rst
.. note::
This guide will upgrade the software components only but not change any data or configuration.
```
:::{note}
This guide will upgrade the software components only but not change any data or configuration.
:::
## Install a new Python version
@@ -15,77 +14,84 @@ To run AA with a newer Python 3 version than your system's default you need to i
To install other Python versions than those included with your distribution, you need to add a new installation repository. Then you can install the specific Python 3 to your system.
Ubuntu 1804, 2004:
```eval_rst
.. note::
:::{note}
Ubuntu 2204 ships with Python 3.10 already
```
```bash
sudo add-apt-repository ppa:deadsnakes/ppa
```
```bash
sudo apt-get update
```
```bash
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:
```eval_rst
.. 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
:::{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.11 and you may need to substitute as neccessary
sudo dnf install python39 python39-devel
:::
::::{tabs}
:::{group-tab} Ubuntu 2004, 2204
```shell
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt-get update
sudo apt-get install python3.11 python3.11-dev python3.11-venv
```
:::
:::{group-tab} CentOS 7
```bash
cd ~
```
```bash
sudo yum install gcc openssl-devel bzip2-devel libffi-devel wget
```
```bash
wget https://www.python.org/ftp/python/3.10.5/Python-3.10.5.tgz
```
```bash
tar xvf Python-3.10.5.tgz
```
```bash
cd Python-3.10.5/
```
```bash
wget https://www.python.org/ftp/python/3.11.5/Python-3.11.5.tgz
tar xvf Python-3.11.5.tgz
cd Python-3.11.5/
./configure --enable-optimizations --enable-shared
```
```bash
sudo make altinstall
```
:::
:::{group-tab} CentOS Stream 8
```bash
cd ~
sudo yum install gcc openssl-devel bzip2-devel libffi-devel wget
wget https://www.python.org/ftp/python/3.11.5/Python-3.11.5.tgz
tar xvf Python-3.11.5.tgz
cd Python-3.11.5/
./configure --enable-optimizations --enable-shared
sudo make altinstall
```
:::
:::{group-tab} CentOS Stream 9
```bash
cd ~
sudo yum install gcc openssl-devel bzip2-devel libffi-devel wget
wget https://www.python.org/ftp/python/3.11.5/Python-3.11.5.tgz
tar xvf Python-3.11.5.tgz
cd Python-3.11.5/
./configure --enable-optimizations --enable-shared
sudo make altinstall
```
:::
::::
## Preparing your venv
Before updating your venv it is important to make sure that your current installation is stable. Otherwise your new venv might not be consistent with your data, which might create problems.
Start by navigating to your main project folder (the one that has `manage.py` in it). If you followed the default installation the path is: `/home/allianceserver/myauth`
```eval_rst
.. note::
If you installed Alliance Auth under the allianceserver user, as reccommended. Remember to switch users for easier permission management::
:::{note}
If you installed Alliance Auth under the allianceserver user, as reccommended. Remember to switch users for easier permission management::
:::
sudo su allianceserver
```bash
sudo su allianceserver
```
Activate your venv:
```bash
```shell
source /home/allianceserver/venv/auth/bin/activate
```
@@ -93,23 +99,23 @@ source /home/allianceserver/venv/auth/bin/activate
Make sure to upgrade AA to the newest version:
```bash
```shell
pip install -U allianceauth
```
Run migrations and collectstatic.
```bash
```shell
python manage.py migrate
```
```bash
```shell
python manage.py collectstatic
```
Restart your AA supervisor:
```bash
```shell
supervisorctl restart myauth:
```
@@ -119,38 +125,39 @@ You also need to upgrade all additional apps to their newest version that you ha
If you unsure which apps you have installed from repos check `INSTALLED_APPS` in your settings. Alternatively run this command to get a list all apps in your venv.
```bash
```shell
pip list
```
Repeat as needed for your apps
```bash
```shell
pip install -U APP_NAME
```
Make sure to run migrations and collect static files for all upgraded apps.
```bash
```shell
python manage.py migrate
```
```bash
```shell
python manage.py collectstatic
```
### Restart and final check
Do a final restart of your AA supervisors and make sure your installation is still running normally.
For a final check that they are no issues - e.g. any outstanding migrations - run this command:
```bash
```shell
python manage.py check
```
If you get the following result you are good to go. Otherwise make sure to fix any issues first before proceeding.
```bash
```shell
System check identified no issues (0 silenced).
```
@@ -160,7 +167,7 @@ Make sure you are in your venv!
First we create a list of all installed packages in your venv. You can use this list later as reference to see what packages should be installed.
```bash
```shell
pip freeze > requirements.txt
```
@@ -169,41 +176,38 @@ At this point we recommend creating a list of the additional packages that you n
- Community AA apps (e.g. aa-structures)
- Additional tools you are using (e.g. flower, django-extensions)
```eval_rst
.. hint::
While `requirements.txt` will contain a complete list of your packages, it will also contain many packages that are automatically installed as dependencies and don't need be manually reinstalled.
```
```eval_rst
.. note::
Some guide on the Internet will suggest to use use the requirements.txt file to recreate a venv. This is indeed possible, but only works if all packages can be installed from PyPI. Since most community apps are installed directly from repos this guide will not follow that approach.
```
:::{hint}
While `requirements.txt` will contain a complete list of your packages, it will also contain many packages that are automatically installed as dependencies and don't need be manually reinstalled.
:::
:::{note}
Some guide on the Internet will suggest to use use the requirements.txt file to recreate a venv. This is indeed possible, but only works if all packages can be installed from PyPI. Since most community apps are installed directly from repos this guide will not follow that approach.
:::
Leave the venv and shutdown all AA services:
```bash
```shell
deactivate
```
```bash
```shell
supervisorctl stop myauth:
```
Rename and keep your old venv so we have a fallback in case of some unforeseeable issues:
```bash
```shell
mv /home/allianceserver/venv/auth /home/allianceserver/venv/auth_old
```
## Create your new venv
Now let's create our new venv with Python 3.10 and activate it:
Now let's create our new venv with Python 3.11 and activate it:
```bash
python3.10 -m venv /home/allianceserver/venv/auth
```shell
python3.11 -m venv /home/allianceserver/venv/auth
```
```bash
```shell
source /home/allianceserver/venv/auth/bin/activate
```
@@ -213,17 +217,17 @@ Now we need to reinstall all packages into your new venv.
### Install basic packages
```bash
```shell
pip install -U pip setuptools wheel
```
### Installing AA & Gunicorn
```bash
```shell
pip install allianceauth
```
```bash
```shell
pip install gunicorn
```
@@ -235,13 +239,13 @@ Use the list of packages you created earlier as a checklist. Alternatively you u
To check whether you are missing any apps you can also run the check command:
```bash
```shell
python manage.py check
```
Note: In case you forget to install an app you will get this error
```bash
```shell
ModuleNotFoundError: No module named 'xyz'
```
@@ -251,7 +255,7 @@ Note that you should not need to run any migrations unless you forgot to upgrade
After you have completed installing all packages just start your AA supervisor again.
```bash
```shell
supervisorctl start myauth:
```
@@ -263,7 +267,7 @@ In case you run into any major issue you can always switch back to your initial
Before you start double-check that you still have your old venv for auth:
```bash
```shell
ls /home/allianceserver/venv/auth /home/allianceserver/venv
```
@@ -274,18 +278,18 @@ If the output shows these two folders you should be safe to proceed:
Run these commands to remove your current venv and switch back to the old venv for auth:
```bash
```shell
supervisorctl stop myauth:
```
```bash
```shell
rm -rf /home/allianceserver/venv/auth
```
```bash
```shell
mv /home/allianceserver/venv/auth_old /home/allianceserver/venv/auth
```
```bash
```shell
supervisorctl start myauth:
```