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

find and replace fixes, will introduce errors

Browse Source
This commit is contained in:
Ariel Rin
2023-10-27 16:37:53 +10:00
parent b9d128259e
commit ffb526ab0c
52 changed files with 615 additions and 589 deletions
Download Patch File Download Diff File Expand all files Collapse all files

474
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
@@ -28,234 +27,243 @@ 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}
```bash
:::{group-tab} Ubuntu 2004, 2204
```shell
sudo apt-get update
```
```bash
```shell
sudo apt-get upgrade
```
```bash
```shell
sudo do-dist-upgrade
```
CentOS 7:
:::
:::{group-tab} CentOS 7
```bash
```shell
yum install epel-release
```
```bash
```shell
sudo yum upgrade
```
CentOS Stream 8:
:::
:::{group-tab} CentOS Stream 8
```bash
```shell
sudo dnf config-manager --set-enabled powertools
```
```bash
```shell
sudo dnf install epel-release epel-next-release
```
```bash
```shell
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
```shell
sudo dnf install epel-release epel-next-release
```
```bash
```shell
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
```shell
sudo apt-get update
```
```bash
sudo apt-get install python3.10 python3.10-dev python3.10-venv
```shell
sudo apt-get install python3.11 python3.11-dev python3.11-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, Stream 8, Stream 9
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
```shell
cd ~
```
```bash
```shell
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
```shell
wget https://www.python.org/ftp/python/3.11.5/Python-3.11.5.tgz
```
```bash
tar xvf Python-3.10.5.tgz
```shell
tar xvf Python-3.11.5.tgz
```
```bash
cd Python-3.10.5/
```shell
cd Python-3.11.5/
```
```bash
```shell
./configure --enable-optimizations --enable-shared
```
```bash
```shell
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
```shell
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
```shell
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
```
```shell
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 +279,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;
```bash
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 +305,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 +406,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 +428,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 +442,7 @@ allianceauth start myauth
Your settings file needs configuring:
```bash
```shell
nano myauth/myauth/settings/local.py
```
@@ -439,34 +458,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
```
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 +509,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::
```bash
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 +632,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:
```