mirror of
https://gitlab.com/allianceauth/allianceauth.git
synced 2025-07-09 04:20:17 +02:00
Improve installation guide
This commit is contained in:
Erik Kalkoken
Ariel Rin
parent
82d7d7e3bf
commit
3eddeefe28
@ -26,9 +26,10 @@ To install on your favorite flavour of Linux, identify and install equivalent pa
|
||||
|
||||
### 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.
|
||||
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:
|
||||
|
||||
```bash
|
||||
sudo apt-get update
|
||||
```
|
||||
@ -41,7 +42,7 @@ sudo apt-get upgrade
|
||||
sudo do-dist-upgrade
|
||||
```
|
||||
|
||||
CentOS 7
|
||||
CentOS 7:
|
||||
|
||||
```bash
|
||||
yum install epel-release
|
||||
@ -51,7 +52,7 @@ yum install epel-release
|
||||
sudo yum upgrade
|
||||
```
|
||||
|
||||
CentOS Stream 8
|
||||
CentOS Stream 8:
|
||||
|
||||
```bash
|
||||
sudo dnf config-manager --set-enabled powertools
|
||||
@ -65,7 +66,7 @@ sudo dnf install epel-release epel-next-release
|
||||
sudo yum upgrade
|
||||
```
|
||||
|
||||
CentOS Stream 9
|
||||
CentOS Stream 9:
|
||||
|
||||
```bash
|
||||
sudo dnf config-manager --set-enabled crb
|
||||
@ -78,15 +79,12 @@ dnf install epel-release epel-next-release
|
||||
```bash
|
||||
sudo yum upgrade
|
||||
```
|
||||
|
||||
### Python
|
||||
|
||||
Alliance Auth requires Python 3.8 or higher. Ensure it is installed on your server before proceeding.
|
||||
Install Python 3.10 and related tools on your system.
|
||||
|
||||
Ubuntu 1804, 2004:
|
||||
```eval_rst
|
||||
.. note::
|
||||
Ubuntu 2204 ships with Python 3.10 already
|
||||
```
|
||||
|
||||
```bash
|
||||
sudo add-apt-repository ppa:deadsnakes/ppa
|
||||
@ -100,13 +98,25 @@ sudo apt-get update
|
||||
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:
|
||||
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
|
||||
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
|
||||
```
|
||||
|
||||
@ -137,6 +147,7 @@ cd Python-3.10.5/
|
||||
```bash
|
||||
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.
|
||||
@ -147,19 +158,21 @@ It's recommended to use a database service instead of SQLite. Many options are a
|
||||
```
|
||||
|
||||
Ubuntu 1804, 2004, 2204:
|
||||
|
||||
```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
|
||||
apt-get install mariadb-server mariadb-client libmysqlclient-dev
|
||||
```
|
||||
|
||||
CentOS 7
|
||||
CentOS 7:
|
||||
|
||||
```eval_rst
|
||||
.. warning::
|
||||
Please follow these steps to update MariaDB
|
||||
@ -170,11 +183,11 @@ CentOS 7
|
||||
sudo yum install MariaDB-server MariaDB-client MariaDB-devel MariaDB-shared
|
||||
```
|
||||
|
||||
CentOS Stream 8/9
|
||||
CentOS Stream 8/9:
|
||||
|
||||
```eval_rst
|
||||
.. note::
|
||||
We reccomend using the built in AppStream, as they are maintained by CentOS. Currently an AppStream is not available for 10.6
|
||||
We recommend using the built in AppStream, as they are maintained by CentOS. Currently an AppStream is not available for 10.6
|
||||
```
|
||||
|
||||
```bash
|
||||
@ -188,6 +201,7 @@ sudo dnf install mariadb mariadb-server mariadb-devel
|
||||
```bash
|
||||
sudo systemctl enable mariadb
|
||||
```
|
||||
|
||||
```bash
|
||||
sudo systemctl start mariadb
|
||||
```
|
||||
@ -202,11 +216,13 @@ sudo systemctl start mariadb
|
||||
A few extra utilities are also required for installation of packages.
|
||||
|
||||
Ubuntu 1804, 2004, 2204:
|
||||
|
||||
```bash
|
||||
sudo apt-get install unzip git redis-server curl libssl-dev libbz2-dev libffi-dev build-essential
|
||||
```
|
||||
|
||||
CentOS 7:
|
||||
|
||||
```bash
|
||||
sudo yum install gcc gcc-c++ unzip git redis curl bzip2-devel openssl-devel libffi-devel wget
|
||||
```
|
||||
@ -220,6 +236,7 @@ sudo systemctl start redis.service
|
||||
```
|
||||
|
||||
CentOS Stream 8, Stream 9:
|
||||
|
||||
```bash
|
||||
sudo dnf install gcc gcc-c++ unzip git redis curl bzip2-devel openssl-devel libffi-devel wget
|
||||
```
|
||||
@ -231,6 +248,7 @@ sudo systemctl enable redis.service
|
||||
```bash
|
||||
sudo systemctl start redis.service
|
||||
```
|
||||
|
||||
## Database Setup
|
||||
|
||||
Alliance Auth needs a MySQL user account and database. Open an SQL shell with
|
||||
@ -277,11 +295,13 @@ mysql_secure_installation
|
||||
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:
|
||||
|
||||
```bash
|
||||
adduser --disabled-login allianceserver
|
||||
sudo adduser --disabled-login allianceserver
|
||||
```
|
||||
|
||||
CentOS 7, Stream 8, Stream 9:
|
||||
|
||||
```bash
|
||||
sudo useradd -s /bin/bash allianceserver
|
||||
```
|
||||
@ -289,6 +309,7 @@ sudo useradd -s /bin/bash allianceserver
|
||||
```bash
|
||||
sudo passwd -l allianceserver
|
||||
```
|
||||
|
||||
### Prepare Directories
|
||||
|
||||
```bash
|
||||
@ -308,6 +329,23 @@ sudo chown -R allianceserver:allianceserver /var/www/myauth/static/
|
||||
|
||||
### Virtual Environment
|
||||
|
||||
Switch to the allianceserver user.
|
||||
|
||||
```bash
|
||||
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.
|
||||
```
|
||||
|
||||
Create a Python virtual environment and put it somewhere convenient (e.g. `/home/allianceserver/venv/auth/`)
|
||||
|
||||
```eval_rst
|
||||
@ -346,16 +384,17 @@ As **callback URL** you want to define the URL of your Alliance Auth site plus t
|
||||
|
||||
### Alliance Auth Project
|
||||
|
||||
Update Pip before installing python packages:
|
||||
|
||||
```bash
|
||||
pip install -U pip setuptools
|
||||
```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)`.
|
||||
```
|
||||
|
||||
Ensure wheel is available before continuing:
|
||||
#### Install Python packages
|
||||
|
||||
Update & install basic tools before installing further Python packages:
|
||||
|
||||
```bash
|
||||
pip install wheel
|
||||
pip install -U pip setuptools wheel
|
||||
```
|
||||
|
||||
You can install **Alliance Auth** with the following command. This will install AA and all its Python dependencies.
|
||||
@ -370,7 +409,9 @@ You should also install Gunicorn now unless you want to use another WSGI server
|
||||
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:
|
||||
#### Create Alliance Auth project
|
||||
|
||||
Now you need to create the Django project that will run **Alliance Auth**. Ensure you are in the allianceserver home directory by issuing:
|
||||
|
||||
```bash
|
||||
cd /home/allianceserver
|
||||
@ -382,16 +423,25 @@ The following command bootstraps a Django project which will run your **Alliance
|
||||
allianceauth start myauth
|
||||
```
|
||||
|
||||
The settings file needs configuring, edit the template at `myauth/myauth/settings/local.py`.
|
||||
#### Update settings
|
||||
|
||||
Your settings file needs configuring:
|
||||
|
||||
```bash
|
||||
nano myauth/myauth/settings/local.py
|
||||
```
|
||||
|
||||
**Be sure to configure:**
|
||||
* Your site URL as `SITE_URL`
|
||||
* The Database account setup earlier in **Database Setup**
|
||||
* `ESI_SSO_CLIENT_ID`, `ESI_SSO_CLIENT_SECRET` from the EVE Online Developers Portal earlier in **Eve Online Settings**
|
||||
* `ESI_USER_CONTACT_EMAIL` to an email address to ensure that CCP has reliable contact information for you
|
||||
* Valid Email server settings.
|
||||
|
||||
Django needs to install models to the database before it can start.
|
||||
- Your site URL as `SITE_URL`
|
||||
- The database user account setup from earlier in [Database Setup](#database-setup)
|
||||
- `ESI_SSO_CLIENT_ID`, `ESI_SSO_CLIENT_SECRET` from the EVE Online Developers Portal from earlier in [Eve Online SSO](#eve-online-sso)
|
||||
- `ESI_USER_CONTACT_EMAIL` to an email address to ensure that CCP has reliable contact information for you
|
||||
- Valid email server settings
|
||||
|
||||
#### Install database & static files
|
||||
|
||||
Django needs to setup the database before it can start.
|
||||
|
||||
```bash
|
||||
python /home/allianceserver/myauth/manage.py migrate
|
||||
@ -400,7 +450,7 @@ 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
|
||||
python /home/allianceserver/myauth/manage.py collectstatic
|
||||
python /home/allianceserver/myauth/manage.py collectstatic --noinput
|
||||
```
|
||||
|
||||
Check to ensure your settings are valid.
|
||||
@ -409,7 +459,6 @@ Check to ensure your settings are valid.
|
||||
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::
|
||||
@ -417,17 +466,7 @@ python /home/allianceserver/myauth/manage.py check
|
||||
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](https://www.fullstackpython.com/wsgi-servers.html) is required. For this [Gunicorn](http://gunicorn.org/) 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](gunicorn.md) doc.
|
||||
|
||||
## Superuser
|
||||
#### 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.
|
||||
|
||||
@ -439,6 +478,16 @@ Once your install is complete, the superuser account is accessed by logging in v
|
||||
|
||||
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.
|
||||
|
||||
## 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](https://www.fullstackpython.com/wsgi-servers.html) is required. For this [Gunicorn](http://gunicorn.org/) 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](gunicorn.md) doc.
|
||||
|
||||
### Supervisor
|
||||
|
||||
[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.
|
||||
@ -461,9 +510,11 @@ CentOS 7:
|
||||
```bash
|
||||
sudo dnf install supervisor
|
||||
```
|
||||
|
||||
```bash
|
||||
sudo systemctl enable supervisord.service
|
||||
```
|
||||
|
||||
```bash
|
||||
sudo systemctl start supervisord.service
|
||||
```
|
||||
@ -473,9 +524,11 @@ CentOS Stream 8, Stream 9:
|
||||
```bash
|
||||
sudo dnf install supervisor
|
||||
```
|
||||
|
||||
```bash
|
||||
sudo systemctl enable supervisord.service
|
||||
```
|
||||
|
||||
```bash
|
||||
sudo systemctl start supervisord.service
|
||||
```
|
||||
@ -491,21 +544,21 @@ ln -s /home/allianceserver/myauth/supervisor.conf /etc/supervisor/conf.d/myauth.
|
||||
CentOS:
|
||||
|
||||
```bash
|
||||
ln -s /home/allianceserver/myauth/supervisor.conf /etc/supervisord.d/myauth.ini
|
||||
sudo ln -s /home/allianceserver/myauth/supervisor.conf /etc/supervisord.d/myauth.ini
|
||||
```
|
||||
|
||||
Activate it with `supervisorctl reload`.
|
||||
Activate it with `sudo 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.
|
||||
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. ::
|
||||
|
||||
supervisorctl restart myauth:
|
||||
sudo supervisorctl restart myauth:
|
||||
```
|
||||
|
||||
## Webserver
|
||||
## Web server
|
||||
|
||||
Once installed, decide on whether you're going to use [NGINX](nginx.md) or [Apache](apache.md) and follow the respective guide.
|
||||
|
||||
@ -530,7 +583,7 @@ source /home/allianceserver/venv/auth/bin/activate
|
||||
and update with:
|
||||
|
||||
```bash
|
||||
pip install --upgrade allianceauth
|
||||
pip install -U allianceauth
|
||||
```
|
||||
|
||||
Some releases come with changes to the base settings. Update your project's settings with:
|
||||
@ -548,7 +601,7 @@ 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
|
||||
python /home/allianceserver/myauth/manage.py collectstatic
|
||||
python /home/allianceserver/myauth/manage.py collectstatic --noinput
|
||||
```
|
||||
|
||||
Always restart AA, Celery and Gunicorn after updating:
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user