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

MyST conversion

Browse Source
This commit is contained in:
Ariel Rin
2023-10-31 23:31:41 +10:00
parent 7024552c4e
commit 98e91fe207
25 changed files with 348 additions and 332 deletions
Download Patch File Download Diff File Expand all files Collapse all files

62
docs/installation/allianceauth.md
View File

@@ -32,13 +32,7 @@ It is recommended to ensure your OS is fully up to date before proceeding. We ma
```shell
sudo apt-get update
```
```shell
sudo apt-get upgrade
```
```shell
sudo do-dist-upgrade
```
@@ -47,9 +41,6 @@ sudo do-dist-upgrade
```shell
yum install epel-release
```
```shell
sudo yum upgrade
```
@@ -58,13 +49,7 @@ sudo yum upgrade
```shell
sudo dnf config-manager --set-enabled powertools
```
```shell
sudo dnf install epel-release epel-next-release
```
```shell
sudo yum upgrade
```
@@ -73,13 +58,7 @@ sudo yum upgrade
```shell
sudo dnf config-manager --set-enabled crb
```
```shell
sudo dnf install epel-release epel-next-release
```
```shell
sudo yum upgrade
```
@@ -96,13 +75,7 @@ Install Python 3.11 and related tools on your system.
```shell
sudo add-apt-repository ppa:deadsnakes/ppa
```
```shell
sudo apt-get update
```
```shell
sudo apt-get install python3.11 python3.11-dev python3.11-venv
```
@@ -110,31 +83,13 @@ sudo apt-get install python3.11 python3.11-dev python3.11-venv
:::{group-tab} CentOS 7, Stream 8, Stream 9
We need to build Python from source
```shell
```bash
cd ~
```
```shell
sudo yum install gcc openssl-devel bzip2-devel libffi-devel wget
```
```shell
wget https://www.python.org/ftp/python/3.11.5/Python-3.11.5.tgz
```
```shell
tar xvf Python-3.11.5.tgz
```
```shell
cd Python-3.11.5/
```
```shell
./configure --enable-optimizations --enable-shared
```
```shell
sudo make altinstall
```
@@ -219,9 +174,6 @@ sudo yum install gcc gcc-c++ unzip git redis curl bzip2-devel openssl-devel libf
```shell
sudo systemctl enable redis.service
```
```shell
sudo systemctl start redis.service
```
@@ -234,9 +186,6 @@ sudo dnf install gcc gcc-c++ unzip git redis curl bzip2-devel openssl-devel libf
```shell
sudo systemctl enable redis.service
```
```shell
sudo systemctl start redis.service
```
@@ -249,9 +198,6 @@ sudo dnf install gcc gcc-c++ unzip git redis curl bzip2-devel openssl-devel libf
```shell
sudo systemctl enable redis.service
```
```shell
sudo systemctl start redis.service
```
@@ -285,7 +231,7 @@ mysql_tzinfo_to_sql /usr/share/zoneinfo | sudo mysql -u root mysql
:::{note}
You may see errors when you add the timezone tables. To make sure that they were correctly added run the following commands and check for the ``time_zone`` tables
```bash
```shell
mysql -u root -p
use mysql;
show tables;
@@ -476,7 +422,7 @@ python /home/allianceserver/myauth/manage.py check
:::{hint}
If you are using root, ensure the allianceserver user has read/write permissions to this directory before proceeding::
```
```shell
chown -R allianceserver:allianceserver /home/allianceserver/myauth
```
@@ -511,7 +457,7 @@ The default configuration is good enough for most installations. Additional info
:::{note}
You will need to exit the allianceserver user back to a user with sudo capabilities to install supervisor::
```bash
```shell
exit
```

4
docs/installation/apache.md
View File

@@ -130,7 +130,7 @@ a2dissite 000-default.conf
## Sample Config File
```conf
```ini
<VirtualHost *:80>
ServerName auth.example.com
@@ -168,7 +168,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:
```conf
```ini
RequestHeader set X-FORWARDED-PROTOCOL https
RequestHeader set X-FORWARDED-SSL On
```

14
docs/installation/gunicorn.md
View File

@@ -7,16 +7,16 @@ 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).
:::{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.
```
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
:::{note}
If you're using a virtual environment, activate it now::
sudo su allianceserver
source /home/allianceserver/venv/auth/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
@@ -47,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.
@@ -79,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
```

32
docs/installation/nginx.md
View File

@@ -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/)
@@ -34,7 +33,6 @@ 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`.
:::{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.
:::
@@ -43,24 +41,41 @@ You will need to have [Gunicorn](gunicorn.md) or some other WSGI server setup fo
## Install
Ubuntu 1804, 2004, 2204:
::::{tabs}
:::{group-tab} Ubuntu 2004, 2204
```shell
sudo apt-get install nginx
```
CentOS 7
:::
:::{group-tab} CentOS 7
```shell
sudo yum install nginx
```
CentOS Stream 8, Stream 9:
:::
:::{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):
```shell
ln -s /etc/nginx/sites-available/alliance-auth.conf /etc/nginx/sites-enabled/
```
@@ -69,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;
@@ -106,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
@@ -122,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;

108
docs/installation/upgrade_python.md
View File

@@ -5,8 +5,8 @@ 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.
:::{note}
This guide will upgrade the software components only but not change any data or configuration.
```
This guide will upgrade the software components only but not change any data or configuration.
:::
## Install a new Python version
@@ -14,59 +14,67 @@ 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:
:::{note}
Ubuntu 2204 ships with Python 3.10 already
```
```shell
sudo add-apt-repository ppa:deadsnakes/ppa
```
```shell
sudo apt-get update
```
```shell
sudo apt-get install python3.10 python3.10-dev python3.10-venv
```
CentOS 7:
We need to build Python from source
:::
Centos Stream 8/9:
:::{note}
A Python 3.9 Package is available for Stream 8 and 9. You _may_ use this instead of building your own package. But our documentation will assume Python3.10 and you may need to substitute as neccessary
sudo dnf install python39 python39-devel
```
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 ~
```
```shell
sudo yum install gcc openssl-devel bzip2-devel libffi-devel wget
```
```shell
wget https://www.python.org/ftp/python/3.10.5/Python-3.10.5.tgz
```
```shell
tar xvf Python-3.10.5.tgz
```
```shell
cd Python-3.10.5/
```
```shell
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
```
```shell
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.
@@ -74,9 +82,10 @@ 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`
:::{note}
If you installed Alliance Auth under the allianceserver user, as reccommended. Remember to switch users for easier permission management::
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:
@@ -134,6 +143,7 @@ python manage.py migrate
```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.
@@ -166,10 +176,10 @@ At this point we recommend creating a list of the additional packages that you n
- Additional tools you are using (e.g. flower, django-extensions)
:::{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.
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.
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:
@@ -190,10 +200,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.10 and activate it:
Now let's create our new venv with Python 3.11 and activate it:
```shell
python3.10 -m venv /home/allianceserver/venv/auth
python3.11 -m venv /home/allianceserver/venv/auth
```
```shell