mirror of
https://gitlab.com/allianceauth/allianceauth.git
synced 2025-07-09 12:30:15 +02:00
Refactor Docs with OS Versions and non-root
This commit is contained in:
Ariel Rin
parent
f40ebbfba4
commit
f5d70a2c48
@ -63,7 +63,7 @@ master_doc = 'index'
|
||||
# General information about the project.
|
||||
project = 'Alliance Auth'
|
||||
copyright = '2018-2022, Alliance Auth'
|
||||
author = 'R4stl1n'
|
||||
author = 'Alliance Auth Team'
|
||||
|
||||
# The version info for the project you're documenting, acts as replacement for
|
||||
# |version| and |release|, also used in various other places throughout the
|
||||
@ -174,6 +174,7 @@ texinfo_documents = [
|
||||
'Miscellaneous'),
|
||||
]
|
||||
|
||||
|
||||
def setup(app):
|
||||
app.add_config_value('recommonmark_config', {
|
||||
'auto_toc_tree_section': 'Contents',
|
||||
|
||||
@ -7,11 +7,6 @@ Mumble is a free voice chat server. While not as flashy as TeamSpeak, it has all
|
||||
Note that this guide assumes that you have installed Auth with the official :doc:`/installation/allianceauth` guide under ``/home/allianceserver`` and that it is called ``myauth``. Accordingly it assumes that you have a service user called ``allianceserver`` that is used to run all Auth services under supervisor.
|
||||
```
|
||||
|
||||
```eval_rst
|
||||
.. note::
|
||||
Same as the official installation guide this guide is assuming you are performing all steps as ``root`` user.
|
||||
```
|
||||
|
||||
```eval_rst
|
||||
.. warning::
|
||||
This guide is currently for Ubuntu only.
|
||||
@ -24,17 +19,17 @@ Mumble is a free voice chat server. While not as flashy as TeamSpeak, it has all
|
||||
The mumble server package can be retrieved from a repository, which we need to add:
|
||||
|
||||
```bash
|
||||
apt-add-repository ppa:mumble/release
|
||||
sudo apt-add-repository ppa:mumble/release
|
||||
```
|
||||
|
||||
```bash
|
||||
apt-get update
|
||||
sudo apt-get update
|
||||
```
|
||||
|
||||
Now three packages need to be installed:
|
||||
|
||||
```bash
|
||||
apt-get install python-software-properties mumble-server libqt5sql5-mysql
|
||||
sudo apt-get install python-software-properties mumble-server libqt5sql5-mysql
|
||||
```
|
||||
|
||||
### Installing Mumble Authenticator
|
||||
@ -51,7 +46,7 @@ We will now install the authenticator into your Auth virtual environment. Please
|
||||
source /home/allianceserver/venv/auth/bin/activate
|
||||
```
|
||||
|
||||
Install the python dependencies for the mumble authenticator. Note that this process can take a couple minutes to complete.
|
||||
Install the python dependencies for the mumble authenticator. Note that this process can take 2-10 minutes to complete.
|
||||
|
||||
```bash
|
||||
pip install -r requirements.txt
|
||||
@ -72,7 +67,7 @@ GRANT ALL PRIVILEGES ON alliance_mumble . * TO 'allianceserver'@'localhost';
|
||||
Mumble ships with a configuration file that needs customization. By default it’s located at `/etc/mumble-server.ini`. Open it with your favorite text editor:
|
||||
|
||||
```bash
|
||||
nano /etc/mumble-server.ini
|
||||
sudo nano /etc/mumble-server.ini
|
||||
```
|
||||
|
||||
We need to enable the ICE authenticator. Edit the following:
|
||||
@ -96,7 +91,7 @@ Save and close the file.
|
||||
To get Mumble superuser account credentials, run the following:
|
||||
|
||||
```bash
|
||||
dpkg-reconfigure mumble-server
|
||||
sudo dpkg-reconfigure mumble-server
|
||||
```
|
||||
|
||||
Set the password to something you’ll remember and write it down. This is your superuser password and later needed to manage ACLs.
|
||||
@ -104,7 +99,7 @@ Set the password to something you’ll remember and write it down. This is your
|
||||
Now restart the server to see the changes reflected.
|
||||
|
||||
```bash
|
||||
service mumble-server restart
|
||||
sudo service mumble-server restart
|
||||
```
|
||||
|
||||
That’s it! Your server is ready to be connected to at example.com:64738
|
||||
@ -136,7 +131,7 @@ python /home/allianceserver/mumble-authenticator/authenticator.py
|
||||
And finally ensure the allianceserver user has read/write permissions to the mumble authenticator files before proceeding:
|
||||
|
||||
```bash
|
||||
chown -R allianceserver:allianceserver /home/allianceserver/mumble-authenticator
|
||||
sudo chown -R allianceserver:allianceserver /home/allianceserver/mumble-authenticator
|
||||
```
|
||||
|
||||
The authenticator needs to be running 24/7 to validate users on Mumble. This can be achieved by adding a section to your auth project's supervisor config file like the following example:
|
||||
@ -165,8 +160,8 @@ priority=999
|
||||
To enable the changes in your supervisor configuration you need to restart the supervisor process itself. And before we do that we are shutting down the current Auth supervisors gracefully:
|
||||
|
||||
```bash
|
||||
supervisor stop myauth:
|
||||
systemctl restart supervisor
|
||||
sudo supervisor stop myauth:
|
||||
sudo systemctl restart supervisor
|
||||
```
|
||||
|
||||
## Configuring Auth
|
||||
@ -255,8 +250,8 @@ There is no way to force your users to update their clients or use Push to Talk,
|
||||
|
||||
<https://wiki.mumble.info/wiki/Murmur.ini#Miscellany>
|
||||
|
||||
We suggest using Mumble 1.3.0+ for your server and Clients, you can tune this to the latest Patch version.
|
||||
`suggestVersion=1.3.0`
|
||||
We suggest using Mumble 1.4.0+ for your server and Clients, you can tune this to the latest Patch version.
|
||||
`suggestVersion=1.4.230`
|
||||
|
||||
If Push to Talk is to your tastes, configure the suggestion as follows
|
||||
`suggestPushToTalk=true`
|
||||
@ -268,7 +263,7 @@ If Push to Talk is to your tastes, configure the suggestion as follows
|
||||
With the default configuration your mumble server is public. Meaning that everyone who has the address can at least connect to it and might also be able join all channels that don't have any permissions set (Depending on your ACL configured for the root channel). If you want only registered member being able to join your mumble, you have to set a server password. To do so open your mumble server configuration which is by default located at `/etc/mumble-server.ini`.
|
||||
|
||||
```bash
|
||||
nano /etc/mumble-server.ini
|
||||
sudo nano /etc/mumble-server.ini
|
||||
```
|
||||
|
||||
Now search for `serverpassword=` and set your password here. If there is no such line, simply add it.
|
||||
@ -280,7 +275,7 @@ serverpassword=YourSuperSecretServerPassword
|
||||
Save the file and restart your mumble server afterwards.
|
||||
|
||||
```bash
|
||||
service mumble-server restart
|
||||
sudo service mumble-server restart
|
||||
```
|
||||
|
||||
From now on, only registered member can join your mumble server. Now if you still want to allow guests to join you have 2 options.
|
||||
|
||||
@ -19,20 +19,25 @@ BROADCAST_USER_PASSWORD = ""
|
||||
BROADCAST_SERVICE_NAME = "broadcast"
|
||||
```
|
||||
|
||||
## Dependencies
|
||||
## OS Dependencies
|
||||
|
||||
Openfire require a Java 8 runtime environment.
|
||||
|
||||
Ubuntu:
|
||||
Ubuntu 1804, 2004, 2204:
|
||||
|
||||
```bash
|
||||
apt-get install openjdk-8-jdk
|
||||
sudo apt-get install openjdk-11-jre
|
||||
```
|
||||
|
||||
CentOS:
|
||||
Centos 7:
|
||||
|
||||
```bash
|
||||
yum -y install java-1.8.0-openjdk java-1.8.0-openjdk-devel
|
||||
sudo yum install java-11-openjdk java-11-openjdk-devel
|
||||
```
|
||||
|
||||
Centos Stream 8, Stream 9:
|
||||
```bash
|
||||
sudo dnf install java-11-openjdk java-11-openjdk-devel
|
||||
```
|
||||
|
||||
## Setup
|
||||
@ -45,22 +50,26 @@ On your PC, navigate to the [Ignite Realtime downloads section](https://www.igni
|
||||
|
||||
Retrieve the file location by copying the URL from the “click here” link, depending on your browser you may have a Copy Link or similar option in your right click menu.
|
||||
|
||||
In the console, ensure you’re in your user’s home directory: `cd ~`
|
||||
In the console, ensure you’re in your user’s home directory:
|
||||
```bash
|
||||
cd ~
|
||||
```
|
||||
|
||||
Now download the package. Replace the link below with the link you got earlier.
|
||||
Download and install the package, replacing the URL with the latest you got from the Openfire download page earlier
|
||||
|
||||
`wget https://www.igniterealtime.org/downloadServlet?filename=openfire/openfire_4.2.3_all.deb`
|
||||
Ubuntu 1804, 2004, 2204:
|
||||
|
||||
Now install from the package. Replace the filename with your filename (the last part of the download URL is the file name)
|
||||
```bash
|
||||
wget https://www.igniterealtime.org/downloadServlet?filename=openfire/openfire_4.7.2_all.deb
|
||||
dpkg -i openfire_4.7.2_all.deb
|
||||
```
|
||||
|
||||
Ubuntu:
|
||||
|
||||
`dpkg -i openfire_4.2.3_all.deb`
|
||||
|
||||
CentOS:
|
||||
|
||||
`yum install -y openfire-4.2.3-1.noarch.rpm`
|
||||
Centos 7, Stream 8, Stream 9:
|
||||
|
||||
```bash
|
||||
wget https://www.igniterealtime.org/downloadServlet?filename=openfire/openfire-4.7.2-1.noarch.rpm
|
||||
yum install -y openfire-4.7.2-1.noarch.rpm
|
||||
```
|
||||
### Create Database
|
||||
|
||||
Performance is best when working from a SQL database. If you installed MySQL or MariaDB alongside your auth project, go ahead and create a database for Openfire:
|
||||
|
||||
@ -52,13 +52,13 @@ In the console, navigate to your user’s home directory: `cd ~`
|
||||
Now download using wget, replacing the URL with the URL for the package you just retrieved
|
||||
|
||||
```bash
|
||||
wget https://www.phpbb.com/files/release/phpBB-3.2.2.zip
|
||||
wget https://download.phpbb.com/pub/release/3.3/3.3.8/phpBB-3.3.8.zip
|
||||
```
|
||||
|
||||
This needs to be unpackaged. Unzip it, replacing the file name with that of the file you just downloaded
|
||||
|
||||
```bash
|
||||
unzip phpBB-3.2.2.zip
|
||||
unzip phpBB-3.3.8.zip
|
||||
```
|
||||
|
||||
Now we need to move this to our web directory. Usually `/var/www/forums`.
|
||||
|
||||
@ -36,17 +36,17 @@ Using your browser, you can download the latest version of SMF to your desktop c
|
||||
|
||||
Download using wget, replacing the URL with the URL for the package you just retrieved
|
||||
|
||||
```shell
|
||||
wget https://download.simplemachines.org/index.php?thanks;filename=smf_2-0-15_install.zip
|
||||
```bash
|
||||
wget https://download.simplemachines.org/index.php?thanks;filename=smf_2-1-2_install.tar.gz
|
||||
```
|
||||
|
||||
This needs to be unpackaged. Unzip it, replacing the file name with that of the file you just downloaded
|
||||
```shell
|
||||
unzip smf_2-0-15_install.zip
|
||||
````
|
||||
```bash
|
||||
unzip smf_2-1-2_install.zip
|
||||
```
|
||||
|
||||
Now we need to move this to our web directory. Usually `/var/www/forums`.
|
||||
```shell
|
||||
```bash
|
||||
mv smf /var/www/forums
|
||||
````
|
||||
|
||||
|
||||
@ -34,18 +34,19 @@ CELERYBEAT_SCHEDULE['run_ts3_group_update'] = {
|
||||
|
||||
### Download Installer
|
||||
|
||||
To install we need a copy of the server. You can find the latest version from [this dl server](http://dl.4players.de/ts/releases/) (I’d recommend getting the latest stable version – find this version number from the [TeamSpeak site](https://www.teamspeak.com/downloads#)). Be sure to get a link to the Linux version.
|
||||
To install we need a copy of the server. You can find the latest version from the [TeamSpeak site](https://www.teamspeak.com/downloads#)). Be sure to get a link to the Linux version.
|
||||
|
||||
Download the server, replacing the link with the link you got earlier.
|
||||
|
||||
```text
|
||||
http://dl.4players.de/ts/releases/3.13.2/teamspeak3-server_linux_amd64-3.13.2.tar.bz2
|
||||
``` bash
|
||||
cd ~
|
||||
wget https://files.teamspeak-services.com/releases/server/3.13.7/teamspeak3-server_linux_amd64-3.13.7.tar.bz2
|
||||
```
|
||||
|
||||
Now we need to extract the file.
|
||||
|
||||
```bash
|
||||
tar -xf teamspeak3-server_linux_amd64-3.1.0.tar.bz2
|
||||
tar -xf teamspeak3-server_linux_amd64-3.13.7.tar.bz2
|
||||
```
|
||||
|
||||
### Create User
|
||||
@ -82,14 +83,19 @@ service teamspeak start
|
||||
|
||||
### Update Settings
|
||||
|
||||
The console will spit out a block of text. If it does not appear, it can be found with `service teamspeak status`. **SAVE THIS**.
|
||||
Set your Teamspeak Serveradmin password to a random string
|
||||
|
||||
```bash
|
||||
./ts3server_minimal_runscript.sh inifile=ts3server.ini serveradmin_password=pleasegeneratearandomstring
|
||||
|
||||
```
|
||||
|
||||
If you plan on claiming the ServerAdmin token, do so with a different TeamSpeak client profile than the one used for your auth account, or you will lose your admin status.
|
||||
|
||||
Edit the settings you added to your auth project's settings file earlier, entering the following:
|
||||
|
||||
- `TEAMSPEAK3_SERVERQUERY_USER` is `loginname` from that block of text it just spat out (usually `serveradmin`)
|
||||
- `TEAMSPEAK3_SERVERQUERY_PASSWORD` is `password` from that block of text it just spat out
|
||||
- `TEAMSPEAK3_SERVERQUERY_USER` is `loginname` from the above bash command (usually `serveradmin`)
|
||||
- `TEAMSPEAK3_SERVERQUERY_PASSWORD` is `password` following the equals in `serveradmin_password=`
|
||||
- `TEAMSPEAK_VIRTUAL_SERVER` is the virtual server ID of the server to be managed - it will only ever not be 1 if your server is hosted by a professional company
|
||||
- `TEAMSPEAK3_PUBLIC_URL` is the public address of your TeamSpeak server. Do not include any leading http:// or teamspeak://
|
||||
|
||||
|
||||
@ -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, it’s 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
|
||||
|
||||
@ -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`.
|
||||
|
||||
@ -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
|
||||
```
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user