Refactor Docs with OS Versions and non-root

This commit is contained in:
Ariel Rin
2022-07-30 07:26:42 +00:00
parent f40ebbfba4
commit f5d70a2c48
11 changed files with 424 additions and 181 deletions

View File

@@ -2,11 +2,6 @@
This document describes how to install **Alliance Auth** from scratch.
```eval_rst
.. tip::
If you are uncomfortable with Linux permissions follow the steps below as the root user.
```
```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.
@@ -14,34 +9,106 @@ This document describes how to install **Alliance Auth** from scratch.
## Dependencies
### Operating System
### Operating Systems
Alliance Auth can be installed on any Unix like operating system. Dependencies are provided below for two of the most popular Linux platforms: Ubuntu and CentOS. To install on your favorite flavour of Linux, identify and install equivalent packages to the ones listed here.
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:
```bash
sudo apt-get update
```
```bash
sudo apt-get upgrade
```
```bash
sudo do-dist-upgrade
```
CentOS 7
```bash
yum install epel-release
```
```bash
sudo yum upgrade
```
CentOS Stream 8
```bash
sudo dnf config-manager --set-enabled powertools
```
```bash
sudo dnf install epel-release epel-next-release
```
```bash
sudo yum upgrade
```
CentOS Stream 9
```bash
sudo dnf config-manager --set-enabled crb
```
```bash
dnf install epel-release epel-next-release
```
```bash
sudo yum upgrade
```
### Python
Alliance Auth requires Python 3.7 or higher. Ensure it is installed on your server before proceeding.
Ubuntu 1604 1804:
Alliance Auth requires Python 3.8 or higher. Ensure it is installed on your server before proceeding.
Ubuntu 1804, 2004:
```eval_rst
.. note::
Ubuntu 2004 ships with Python 3.8, No updates required.
Ubuntu 2204 ships with Python 3.10 already
```
```bash
add-apt-repository ppa:deadsnakes/ppa
sudo add-apt-repository ppa:deadsnakes/ppa
```
```bash
apt-get update
sudo apt-get update
```
```bash
apt-get install python3.7 python3.7-dev python3.7-venv
sudo apt-get install python3.10 python3.10-dev python3.10-venv
```
CentOS 7/8:
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
```
```bash
cd ~
@@ -52,15 +119,15 @@ sudo yum install gcc openssl-devel bzip2-devel libffi-devel wget
```
```bash
wget https://www.python.org/ftp/python/3.7.11/Python-3.7.11.tgz
wget https://www.python.org/ftp/python/3.10.5/Python-3.10.5.tgz
```
```bash
tar xvf Python-3.7.11.tgz
tar xvf Python-3.10.5.tgz
```
```bash
cd Python-3.7.11/
cd Python-3.10.5/
```
```bash
@@ -68,64 +135,111 @@ cd Python-3.7.11/
```
```bash
make altinstall
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.
```eval_rst
.. warning::
.. 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!
For instructions on how To install a newer version of Maria DB on Ubuntu visit this page: `MariaDB Repositories <https://downloads.mariadb.org/mariadb/repositories/#distro=Ubuntu&mirror=osuosl>`_.
```
Ubuntu:
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:
CentOS 7
```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
yum install mariadb-server mariadb-devel mariadb-shared mariadb
sudo yum install MariaDB-server MariaDB-client MariaDB-devel MariaDB-shared
```
CentOS Stream 8/9
```eval_rst
.. note::
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.
We reccomend 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
sudo dnf install mariadb mariadb-server mariadb-devel
```
```bash
sudo systemctl enable mariadb
```
```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.
```
### Redis and Other Tools
A few extra utilities are also required for installation of packages.
Ubuntu:
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
```
```bash
apt-get install unzip git redis-server curl libssl-dev libbz2-dev libffi-dev
sudo systemctl enable redis.service
```
CentOS:
```bash
yum install gcc gcc-c++ unzip git redis curl bzip2-devel
sudo systemctl start redis.service
```
```eval_rst
.. important::
CentOS: Make sure Redis is running before continuing. ::
systemctl enable redis.service
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
```
```bash
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 `mysql -u root -p` and create them as follows, replacing `PASSWORD` with an actual secure password:
Alliance Auth needs a MySQL user account and database. Open an SQL shell with
```bash
sudo mysql -u root
```
and create them as follows, replacing `PASSWORD` with an actual secure password:
```sql
CREATE USER 'allianceserver'@'localhost' IDENTIFIED BY 'PASSWORD';
@@ -138,7 +252,7 @@ Once your database is set up, you can leave the SQL shell with `exit`.
Add timezone tables to your mysql installation:
```bash
mysql_tzinfo_to_sql /usr/share/zoneinfo | mysql -u root -p mysql
mysql_tzinfo_to_sql /usr/share/zoneinfo | sudo mysql -u root mysql
```
```eval_rst
@@ -162,29 +276,47 @@ mysql_secure_installation
For security and permissions, its highly recommended you create a separate user to install auth under. Do not log in as this account.
Ubuntu:
Ubuntu 1804, 2004, 2204:
```bash
adduser --disabled-login allianceserver
```
CentOS:
CentOS 7, Stream 8, Stream 9:
```bash
sudo useradd -s /bin/bash allianceserver
```
```bash
useradd -s /bin/nologin allianceserver
sudo passwd -l allianceserver
```
### Prepare Directories
```bash
sudo mkdir -p /var/www/myauth/static
```
```bash
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::
sudo su allianceserver
```
### Virtual Environment
Create a Python virtual environment and put it somewhere convenient (e.g. `/home/allianceserver/venv/auth/`)
```bash
python3 -m venv /home/allianceserver/venv/auth/
```eval_rst
.. note::
Your python3.x command/version may vary depending on your installed python version.
```
```eval_rst
.. warning::
The python3 command may not be available on all installations. Try a specific version such as ``python3.7`` if this is the case.
```bash
python3.10 -m venv /home/allianceserver/venv/auth/
```
```eval_rst
@@ -216,6 +348,12 @@ In `local.py` you will need to set `ESI_USER_CONTACT_EMAIL` to an email address
### Alliance Auth Project
Update Pip before installing python packages:
```bash
pip install -U pip setuptools
```
Ensure wheel is available before continuing:
```bash
@@ -246,7 +384,7 @@ 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`. Be sure to configure the EVE SSO and Email settings.
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.
@@ -257,7 +395,6 @@ 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
mkdir -p /var/www/myauth/static
python /home/allianceserver/myauth/manage.py collectstatic
```
@@ -267,10 +404,12 @@ Check to ensure your settings are valid.
python /home/allianceserver/myauth/manage.py check
```
Finally, ensure the allianceserver user has read/write permissions to this directory before proceeding.
```bash
chown -R allianceserver:allianceserver /home/allianceserver/myauth
```eval_rst
.. 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
@@ -283,32 +422,62 @@ To run the **Alliance Auth** website a [WSGI Server](https://www.fullstackpython
The default configuration is good enough for most installations. Additional information is available in the [gunicorn](gunicorn.md) 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.
```bash
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](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. Installation varies by OS:
[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::
Many package managers will install Supervisor 3 by default, which requires Python 2.
You will need to exit the allianceserver user back to a user with sudo capabilities to install supervisor::
exit
```
Ubuntu:
Ubuntu 1804, 2004, 2204:
```bash
apt-get install supervisor
sudo apt-get install supervisor
```
CentOS:
CentOS 7:
```bash
yum install supervisor
systemctl enable supervisord.service
systemctl start supervisord.service
sudo dnf install supervisor
```
```bash
sudo systemctl enable supervisord.service
```
```bash
sudo systemctl start supervisord.service
```
CentOS Stream 8, Stream 9:
```bash
sudo dnf install supervisor
```
```bash
sudo systemctl enable supervisord.service
```
```bash
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:
Ubuntu 1804, 2004:
```bash
ln -s /home/allianceserver/myauth/supervisor.conf /etc/supervisor/conf.d/myauth.conf
@@ -337,23 +506,23 @@ Once installed, decide on whether you're going to use [NGINX](nginx.md) or [Apac
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.
## 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
python /home/allianceserver/myauth/manage.py createsuperuser
```
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.
## Updating
Periodically [new releases](https://gitlab.com/allianceauth/allianceauth/tags) are issued with bug fixes and new features. Be sure to read the [release notes](https://gitlab.com/allianceauth/allianceauth/-/releases) which will highlight changes.
To update your install, simply activate your virtual environment and update with:
To update your install, swap to your allianceserver user
```bash
sudo su allianceserver
```
Activate your virtual environment
```bash
source /home/allianceserver/venv/auth/bin/activate
```
and update with:
```bash
pip install --upgrade allianceauth

View File

@@ -8,19 +8,39 @@ If you're using a small VPS to host services with very limited memory, consider
## Installation
Ubuntu:
Ubuntu 1804, 2004:
```bash
apt-get install apache2
```
apt-get install apache2
CentOS 7:
```bash
yum install httpd
```
Centos Stream 8, Stream 9
```bash
dnf install httpd
```
CentOS:
yum install httpd
systemctl enable httpd
systemctl start httpd
CentOS 7, Stream 8, Stream 9
```bash
systemctl enable httpd
```
```bash
systemctl start httpd
```
## Configuration
Apache needs to be able to read the folder containing your auth project's static files. On Ubuntu: `chown -R www-data:www-data /var/www/myauth/static`, and on CentOS: `chown -R apache:apache /var/www/myauth/static`
Apache needs to be able to read the folder containing your auth project's static files.
Ubuntu 1804, 2004:
```
chown -R www-data:www-data /var/www/myauth/static
```
CentOS 7, Stream 8, Stream 9
```
chown -R apache:apache /var/www/myauth/static
```
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.
@@ -29,13 +49,20 @@ A virtual host for auth need only proxy requests to your WSGI server (Gunicorn i
### Ubuntu
To proxy and modify headers a few mods need to be enabled.
a2enmod proxy
a2enmod proxy_http
a2enmod headers
```bash
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`.
```eval_rst
.. warning::
In some scenarios, the Apache default page is still enabled. To disable it use::
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`.

View File

@@ -15,10 +15,16 @@ Check out the full [Gunicorn docs](http://docs.gunicorn.org/en/latest/index.html
```eval_rst
.. note::
If you're using a virtual environment, activate it now. ``source /path/to/venv/bin/activate``.
If you're using a virtual environment, activate it now::
sudo su allianceserver
source /home/allianceserver/venv/auth/bin/activate
```
Install Gunicorn using pip, `pip install gunicorn`.
Install Gunicorn using pip
```bash
pip install gunicorn
```
In your `myauth` base directory, try running `gunicorn --bind 0.0.0.0:8000 myauth.wsgi`. You should be able to browse to `http://yourserver:8000` and see your Alliance Auth installation running. Images and styling will be missing, but don't worry, your web server will provide them.
@@ -26,7 +32,7 @@ Once you validate its running, you can kill the process with Ctrl+C and continue
## Running Gunicorn with Supervisor
You should use [Supervisor](allianceauth.md#supervisor) to keep all of Alliance Auth components running (instead of using screen). You don't _have to_ but we will be using it to start and run Gunicorn so you might as well.
If you are following this guide, we already use [Supervisor](allianceauth.md#supervisor) to keep all of Alliance Auth components running. You don't _have to_ but we will be using it to start and run Gunicorn for consistency.
### Sample Supervisor config
@@ -43,7 +49,6 @@ 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.
@@ -71,11 +76,14 @@ Change it by adding `--workers=5` to the command.
##### Running with a virtual environment
If you're running with a virtual environment, you'll need to add the path to the `command=` config line.
Following this guide, you are running with a virtual environment. Therefore you'll need to add the path to the `command=` config line.
e.g. `command=/path/to/venv/bin/gunicorn myauth.wsgi`
The example config is using the myauth venv from the main installation guide: `command=/home/allianceserver/venv/auth/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
```
### Starting via Supervisor
@@ -89,4 +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:
`supervisorctl restart gunicorn`, or the service name you chose for it.
```bash
supervisorctl restart myauth:gunicorn
```

View File

@@ -35,17 +35,36 @@ Nginx needs to be able to read the folder containing your auth project's 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`.
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.
### Ubuntu
## Install
Ubuntu 1804, 2004. 2204:
```bash
sudo apt-get install nginx
```
CentOS 7
```bash
sudo yum install nginx
```
CentOS Stream 8, Stream 9:
```bash
sudo dnf install nginx
```
Create a config file in `/etc/nginx/sites-available` and call it `alliance-auth.conf` or whatever your preferred name is.
Create a symbolic link to enable the site `ln -s /etc/nginx/sites-available/alliance-auth.conf /etc/nginx/sites-enabled/`
Create a symbolic link to enable the site
```bash
ln -s /etc/nginx/sites-available/alliance-auth.conf /etc/nginx/sites-enabled/
```
### CentOS

View File

@@ -2,10 +2,7 @@
This guide describes how to upgrade an existing Alliance Auth (AA) installation to a newer Python 3 version.
```eval_rst
.. hint::
In accordance with the installation guide we will assume you perform all actions as root. If you are not running as root you need to add ``sudo`` to some commands.
```
This guide shares many similarities with the Alliance Auth install guide, but it is targeted towards existing installs needing to update.
```eval_rst
.. note::
@@ -16,33 +13,35 @@ This guide describes how to upgrade an existing Alliance Auth (AA) installation
To run AA with a newer Python 3 version than your system's default you need to install it first. Technically it would be possible to upgrade your system's default Python 3, but since many of your system's tools have been tested to work with that specific version we would not recommend it. Instead we recommend to install an additional Python 3 version alongside your default version and use that for AA.
```eval_rst
.. note::
For stability and performance we currently recommend to run AA with Python 3.7. It has proven to be the fastest and most stable version in use currently.
```
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 1604 1804:
Ubuntu 1804, 2004:
```eval_rst
.. note::
Ubuntu 2004 ships with Python 3.8, No updates required.
Ubuntu 2204 ships with Python 3.10 already
```
```bash
add-apt-repository ppa:deadsnakes/ppa
sudo add-apt-repository ppa:deadsnakes/ppa
```
```bash
apt-get update
sudo apt-get update
```
```bash
apt-get install python3.7 python3.7-dev python3.7-venv
sudo apt-get install python3.10 python3.10-dev python3.10-venv
```
CentOS 7/8:
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
```
```bash
cd ~
@@ -53,15 +52,15 @@ sudo yum install gcc openssl-devel bzip2-devel libffi-devel wget
```
```bash
wget https://www.python.org/ftp/python/3.7.11/Python-3.7.11.tgz
wget https://www.python.org/ftp/python/3.10.5/Python-3.10.5.tgz
```
```bash
tar xvf Python-3.7.11.tgz
tar xvf Python-3.10.5.tgz
```
```bash
cd Python-3.7.11/
cd Python-3.10.5/
```
```bash
@@ -69,7 +68,7 @@ cd Python-3.7.11/
```
```bash
make altinstall
sudo make altinstall
```
## Preparing your venv
@@ -77,6 +76,13 @@ Before updating your venv it is important to make sure that your current install
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::
sudo su allianceserver
```
Activate your venv:
```bash
@@ -117,12 +123,21 @@ If you unsure which apps you have installed from repos check `INSTALLED_APPS` in
pip list
```
Repeat as needed for your apps
```bash
python manage.py migrate
pip install -U APP_NAME
```
Make sure to run migrations and collect static files for all upgraded apps.
```bash
python manage.py migrate
```
```bash
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.
@@ -182,10 +197,10 @@ mv /home/allianceserver/venv/auth /home/allianceserver/venv/auth_old
## Create your new venv
Now let's create our new venv with Python 3.7 and activate it:
Now let's create our new venv with Python 3.10 and activate it:
```bash
python3.7 -m venv /home/allianceserver/venv/auth
python3.10 -m venv /home/allianceserver/venv/auth
```
```bash
@@ -199,15 +214,7 @@ Now we need to reinstall all packages into your new venv.
### Install basic packages
```bash
pip install --upgrade pip
```
```bash
pip install --upgrade setuptools
```
```bash
pip install wheel
pip install -U pip setuptools wheel
```
### Installing AA & Gunicorn