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

Documentation overhaul

Browse Source
This commit is contained in:
Erik Kalkoken
2020-03-05 02:23:58 +00:00
committed by Ariel Rin
parent 9c880eae8a
commit 8137f1023a
84 changed files with 844 additions and 530 deletions
Download Patch File Download Diff File Expand all files Collapse all files

339
docs/installation/allianceauth.md Normal file
View File

@@ -0,0 +1,339 @@
# Alliance Auth
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 [Features](/features/index) for details.
```
## Dependencies
### Operating System
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.
```eval_rst
.. hint::
CentOS: A few packages are included in a non-default repository. Add it and update the package lists. ::
yum -y install https://centos7.iuscommunity.org/ius-release.rpm
yum update
```
### Python
Alliance Auth requires python3.5 or higher. Ensure it is installed on your server before proceeding.
Ubuntu:
```bash
apt-get install python3 python3-dev python3-venv python3-setuptools python3-pip
```
CentOS:
```bash
yum install python36u python36u-devel python36u-setuptools python36u-pip
```
### Database
It's recommended to use a database service instead of SQLite. Many options are available, but this guide will use MariaDB. Note that Alliance Auth requires Maria DB 10.2.x or higher.
Ubuntu:
```bash
apt-get install mariadb-server mariadb-client libmysqlclient-dev
```
CentOS:
```bash
yum install mariadb-server mariadb-devel mariadb-shared mariadb
```
```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.
```
### Redis and Other Tools
A few extra utilities are also required for installation of packages.
Ubuntu:
```bash
apt-get install unzip git redis-server curl libssl-dev libbz2-dev libffi-dev
```
CentOS:
```bash
yum install gcc gcc-c++ unzip git redis curl bzip2-devel
```
```eval_rst
.. important::
CentOS: Make sure Redis is running before continuing. ::
systemctl enable redis.service
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:
```sql
CREATE USER 'allianceserver'@'localhost' IDENTIFIED BY 'PASSWORD';
CREATE DATABASE alliance_auth CHARACTER SET utf8mb4;
GRANT ALL PRIVILEGES ON alliance_auth . * TO 'allianceserver'@'localhost';
```
Add timezone tables to your mysql installation:
```bash
mysql_tzinfo_to_sql /usr/share/zoneinfo | mysql -u root -p mysql
```
```eval_rst
.. note::
You may see errors when you add the timezone tables. To make sure that they were correctly added run the following commands and check for the ``time_zone`` tables::
mysql -u root -p
use mysql;
show tables;
```
Close the SQL shell and secure your database server with this command:
```bash
mysql_secure_installation
```
## Auth Install
### User Account
For security and permissions, it’s highly recommended you create a separate user to install auth under. Do not log in as this account.
Ubuntu:
```bash
adduser --disabled-login allianceserver
```
CentOS:
```bash
useradd -s /bin/nologin 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
.. warning::
The python3 command may not be available on all installations. Try a specific version such as ``python3.6`` if this is the case.
```
```eval_rst
.. tip::
A virtual environment provides support for creating a lightweight "copy" of Python with their own site directories. Each virtual environment has its own Python binary (allowing creation of environments with various Python versions) and can have its own independent set of installed Python packages in its site directories. You can read more about virtual environments on the Python_ docs.
.. _Python: https://docs.python.org/3/library/venv.html
```
Activate the virtual environment with (Note the `/bin/activate` on the end of the path):
```bash
source /home/allianceserver/venv/auth/bin/activate
```
```eval_rst
.. hint::
Each time you come to do maintenance on your Alliance Auth installation, you should activate your virtual environment first. When finished, deactivate it with the ``deactivate`` command.
```
### Eve Online SSO
You need to have a dedicated Eve SSO app for Alliance auth. Please go to [EVE Developer](https://developers.eveonline.com/applications) to create one.
For **scopes** your SSO app needs to have at least `publicData`. Additional scopes depends on which Alliance Auth apps you will be using. For convenience we recommend adding all available ESO scopes to your SSO app. Note that Alliance Auth will always ask the users to approve specific scopes before they are used.
As **callback URL** you want to define the URL of your Alliance Auth site plus the route: `/sso/callback`. Example for a valid callback URL: `https://auth.example.com/sso/callback`
### Alliance Auth Project
Ensure wheel is available before continuing:
```bash
pip install wheel
```
You can install **Alliance Auth** with the following command. This will install AA and all its Python dependencies.
```bash
pip install allianceauth
```
Now you need to create the application that will run the **Alliance Auth** install. Ensure you are in the allianceserver home directory by issuing:
```bash
cd /home/allianceserver
```
The following command bootstraps a Django project which will run your **Alliance Auth** instance. You can rename it from `myauth` to anything you'd like. Note that this name is shown by default as the site name but that can be changed later.
```bash
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.
Django needs to install models to the database before it can start.
```bash
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
```
Check to ensure your settings are valid.
```bash
python /home/allianceserver/myauth/manage.py check
```
And finally ensure the allianceserver user has read/write permissions to this directory before proceeding.
```bash
chown -R allianceserver:allianceserver /home/allianceserver/myauth
```
## Services
Alliance Auth needs some additional services to run, which we will setup 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.
Use this command to install Gunicorn:
```bash
pip install gunicorn
```
### 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:
Ubuntu:
```bash
apt-get install supervisor
```
CentOS:
```bash
yum install supervisor
systemctl enable supervisord.service
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:
```bash
ln -s /home/allianceserver/myauth/supervisor.conf /etc/supervisor/conf.d/myauth.conf
```
CentOS:
```bash
ln -s /home/allianceserver/myauth/supervisor.conf /etc/supervisord.d/myauth.ini
```
And activate it with `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.
```eval_rst
.. note::
Any time the code or your settings change you'll need to restart Gunicorn and Celery. ::
supervisorctl restart myauth:
```
## Webserver
Once installed, decide on whether you're going to use [NGINX](nginx.md) or [Apache](apache.md) and follow the respective guide.
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:
```bash
pip install --upgrade allianceauth
```
Some releases come with changes to the base settings. Update your project's settings with:
```bash
allianceauth update /home/allianceserver/myauth
```
Some releases come with new or changed models. Update your database to reflect this with:
```bash
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
```
Always restart AA, Celery and Gunicorn after updating:
```bash
supervisorctl restart myauth:
```

0
docs/installation/auth/apache.md → docs/installation/apache.md
View File

224
docs/installation/auth/allianceauth.md
View File

@@ -1,224 +0,0 @@
# Alliance Auth Installation
```eval_rst
.. tip::
If you are uncomfortable with Linux permissions follow the steps below as the root user.
```
## Dependencies
Alliance Auth can be installed on any operating system. Dependencies are provided below for two of the most popular server platforms, Ubuntu and CentOS. To install on your favourite flavour of Linux, identify and install equivalent packages to the ones listed here.
```eval_rst
.. hint::
CentOS: A few packages are included in a non-default repository. Add it and update the package lists. ::
yum -y install https://centos7.iuscommunity.org/ius-release.rpm
yum update
```
### Python
Alliance Auth requires python3.5 or higher. Ensure it is installed on your server before proceeding.
Ubuntu:
apt-get install python3 python3-dev python3-venv python3-setuptools python3-pip
CentOS:
yum install python36u python36u-devel python36u-setuptools python36u-pip
### Database
It's recommended to use a database service instead of SQLite. Many options are available, but this guide will use MariaDB.
Ubuntu:
apt-get install mariadb-server mariadb-client libmysqlclient-dev
CentOS:
yum install mariadb-server mariadb-devel mariadb-shared mariadb
```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.
```
### Redis and Other Tools
A few extra utilities are also required for installation of packages.
Ubuntu:
apt-get install unzip git redis-server curl libssl-dev libbz2-dev libffi-dev
CentOS:
yum install gcc gcc-c++ unzip git redis curl bzip2-devel
```eval_rst
.. important::
CentOS: Make sure Redis is running before continuing. ::
systemctl enable redis.service
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:
CREATE USER 'allianceserver'@'localhost' IDENTIFIED BY 'PASSWORD';
CREATE DATABASE alliance_auth CHARACTER SET utf8mb4;
GRANT ALL PRIVILEGES ON alliance_auth . * TO 'allianceserver'@'localhost';
Add timezone tables to your mysql installation:
mysql_tzinfo_to_sql /usr/share/zoneinfo | mysql -u root -p mysql
```eval_rst
.. note::
You may see errors when you add the timezone tables. To make sure that they were correctly added run the following commands and check for the ``time_zone`` tables::
mysql -u root -p
use mysql;
show tables;
```
Close the SQL shell and secure your database server with the `mysql_secure_installation` command.
## Auth Install
### User Account
For security and permissions, it’s highly recommended you create a separate user to install auth under. Do not log in as this account.
Ubuntu:
adduser --disabled-login allianceserver
CentOS:
useradd -s /bin/nologin allianceserver
### Virtual Environment
Create a Python virtual environment and put it somewhere convenient (e.g. `/home/allianceserver/venv/auth/`)
python3 -m venv /home/allianceserver/venv/auth/
```eval_rst
.. warning::
The python3 command may not be available on all installations. Try a specific version such as ``python3.6`` if this is the case.
```
```eval_rst
.. tip::
A virtual environment provides support for creating a lightweight "copy" of Python with their own site directories. Each virtual environment has its own Python binary (allowing creation of environments with various Python versions) and can have its own independent set of installed Python packages in its site directories. You can read more about virtual environments on the Python_ docs.
.. _Python: https://docs.python.org/3/library/venv.html
```
Activate the virtualenv using `source /home/allianceserver/venv/auth/bin/activate`. Note the `/bin/activate` on the end of the path.
```eval_rst
.. hint::
Each time you come to do maintenance on your Alliance Auth installation, you should activate your virtual environment first. When finished, deactivate it with the ``deactivate`` command.
```
Ensure wheel is available with `pip install wheel` before continuing.
### Alliance Auth Project
You can install the library using `pip install allianceauth`. This will install Alliance Auth and all its python dependencies. You should also install Gunicorn with `pip install gunicorn` before proceeding.
Now you need to create the application that will run the Alliance Auth install. Ensure you are in the allianceserver home directory by issuing `cd /home/allianceserver`.
The `allianceauth start myauth` command bootstraps a Django project which will run Alliance Auth. You can rename it from `myauth` to anything you'd like: this name is shown by default as the site name but that can be changed later.
The settings file needs configuring. Edit the template at `myauth/myauth/settings/local.py`. Be sure to configure the EVE SSO and Email settings.
Django needs to install models to the database before it can start.
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.
mkdir -p /var/www/myauth/static
python /home/allianceserver/myauth/manage.py collectstatic
Check to ensure your settings are valid.
python /home/allianceserver/myauth/manage.py check
And finally ensure the allianceserver user has read/write permissions to this directory before proceeding.
chown -R allianceserver:allianceserver /home/allianceserver/myauth
## Background Tasks
### Gunicorn
To run the auth website a [WSGI Server](https://www.fullstackpython.com/wsgi-servers.html) is required. [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. Installation varies by OS:
Ubuntu:
apt-get install supervisor
CentOS:
yum install supervisor
systemctl enable supervisord.service
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:
ln -s /home/allianceserver/myauth/supervisor.conf /etc/supervisor/conf.d/myauth.conf
CentOS:
ln -s /home/allianceserver/myauth/supervisor.conf /etc/supervisord.d/myauth.ini
And activate it with `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.
```eval_rst
.. note::
Any time the code or your settings change you'll need to restart Gunicorn and Celery. ::
supervisorctl restart myauth:
```
## Webserver
Once installed, decide on whether you're going to use [NGINX](nginx.md) or [Apache](apache.md) and follow the respective guide.
## 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.
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. To update your install, simply activate your virtual environment and update with `pip install --upgrade allianceauth`. Be sure to read the release notes which will highlight changes.
Some releases come with changes to settings: update your project's settings with `allianceauth update /home/allianceserver/myauth`.
Some releases come with new or changed models. Update your database to reflect this with `python /home/allianceserver/myauth/manage.py migrate`.
Always restart Celery and Gunicorn after updating.

11
docs/installation/auth/index.md
View File

@@ -1,11 +0,0 @@
# Auth
```eval_rst
.. toctree::
allianceauth
upgradev1
gunicorn
nginx
apache
```

21
docs/installation/auth/gunicorn.md → docs/installation/gunicorn.md
View File

@@ -6,6 +6,11 @@ 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).
```eval_rst
.. 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.
```
## Setting up Gunicorn
```eval_rst
@@ -24,8 +29,10 @@ Once you validate its running, you can kill the process with Ctrl+C and continue
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.
### Sample Supervisor config
You'll want to edit `/etc/supervisor/conf.d/myauth_gunicorn.conf` (or whatever you want to call the config file)
```
```text
[program:myauth-gunicorn]
user = allianceserver
directory=/home/allianceserver/myauth/
@@ -45,20 +52,23 @@ stopsignal=INT
See the [Commonly Used Arguments](http://docs.gunicorn.org/en/latest/run.html#commonly-used-arguments) or [Full list of settings](http://docs.gunicorn.org/en/stable/settings.html) for more information.
##### Where to bind Gunicorn to?
What address are you going to use to reference it? By default, without a bind parameter, Gunicorn will bind to `127.0.0.1:8000`. This might be fine for your application. If it clashes with another application running on that port you will need to change it. I would suggest using UNIX sockets too, if you can.
For UNIX sockets add `--bind=unix:/run/allianceauth.sock` (or to a path you wish to use). Remember that your web server will need to be able to access this socket file.
For a TCP address add `--bind=127.0.0.1:8001` (or to the address/port you wish to use, but I would strongly advise against binding it to an external address).
Whatever you decide to use, remember it because we'll need it when configuring your webserver.
##### Number of workers
By default Gunicorn will spawn only one worker. The number you set this to will depend on your own server environment, how many visitors you have etc. Gunicorn suggests between 2-4 workers per core. Really you could probably get away with 2-4 in total for most installs.
Change it by adding `--workers=2` 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.
e.g. `command=/path/to/venv/bin/gunicorn myauth.wsgi`
@@ -67,13 +77,12 @@ e.g. `command=/path/to/venv/bin/gunicorn myauth.wsgi`
Once you have your configuration all sorted, you will need to reload your supervisor config `service supervisor reload` and then you can start the Gunicorn server via `supervisorctl start aauth-gunicorn` (or whatever you renamed it to). You should see something like the following `aauth-gunicorn: started`. If you get some other message, you'll need to consult the Supervisor log files, usually found in `/var/log/supervisor/`.
## Configuring your webserver
Any web server capable of proxy passing should be able to sit in front of Gunicorn. Consult their documentation armed with your `--bind=` address and you should be able to find how to do it relatively easy.
## Restarting Gunicorn
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 myauth-gunicorn`, or the service name you chose for it.

14
docs/installation/index.md
View File

@@ -1,10 +1,16 @@
# Installation
This chapter contains the main installation guides for **Alliance Auth**.
In addition to main guide for installation Alliance Auth you also find guides for configuring web servers (Apache, NGINX) and the recommended WSGI server (Gunicorn).
```eval_rst
.. toctree::
:maxdepth: 2
auth/index
services/index
:maxdepth: 1
allianceauth
nginx
apache
gunicorn
upgradev1
```

0
docs/installation/auth/nginx.md → docs/installation/nginx.md
View File

81
docs/installation/services/discord.md
View File

@@ -1,81 +0,0 @@
# Discord
## Overview
Discord is a web-based instant messaging client with voice. Kind of like TeamSpeak meets Slack meets Skype. It also has a standalone app for phones and desktop.
Discord is very popular amongst ad-hoc small groups and larger organizations seeking a modern technology. Alternative voice communications should be investigated for larger than small-medium groups for more advanced features.
## Setup
```eval_rst
.. warning::
Do not run the `discord.update_*` periodic tasks on a regular schedule, doing so can cause your discord service to stop syncing completely.
```
### Prepare Your Settings File
In your auth project's settings file, do the following:
- Add `'allianceauth.services.modules.discord',` to your `INSTALLED_APPS` list
- Append the following to the bottom of the settings file:
# Discord Configuration
DISCORD_GUILD_ID = ''
DISCORD_CALLBACK_URL = ''
DISCORD_APP_ID = ''
DISCORD_APP_SECRET = ''
DISCORD_BOT_TOKEN = ''
DISCORD_SYNC_NAMES = False
### Creating a Server
Navigate to the [Discord site](https://discordapp.com/) and register an account, or log in if you have one already.
On the left side of the screen you’ll see a circle with a plus sign. This is the button to create a new server. Go ahead and do that, naming it something obvious.
Now retrieve the server ID [following this procedure.](https://support.discordapp.com/hc/en-us/articles/206346498-Where-can-I-find-my-User-Server-Message-ID-)
Update your auth project's settings file, inputting the server ID as `DISCORD_GUILD_ID`
```eval_rst
.. note::
If you already have a Discord server skip the creation step, but be sure to retrieve the server ID
```
### Registering an Application
Navigate to the [Discord Developers site.](https://discordapp.com/developers/applications/me) Press the plus sign to create a new application.
Give it a name and description relating to your auth site. Add a redirect to `https://example.com/discord/callback/`, substituting your domain. Press Create Application.
Update your auth project's settings file, inputting this redirect address as `DISCORD_CALLBACK_URL`
On the application summary page, press Create a Bot User.
Update your auth project's settings file with these pieces of information from the summary page:
- From the App Details panel, `DISCORD_APP_ID` is the Client/Application ID
- From the App Details panel, `DISCORD_APP_SECRET` is the Secret
- From the App Bot Users panel, `DISCORD_BOT_TOKEN` is the Token
### Preparing Auth
Before continuing it is essential to run migrations and restart Gunicorn and Celery.
### Adding a Bot to the Server
Once created, navigate to the services page of your Alliance Auth install as the superuser account. At the top there is a big green button labelled Link Discord Server. Click it, then from the drop down select the server you created, and then Authorize.
This adds a new user to your Discord server with a `BOT` tag, and a new role with the same name as your Discord application. Don't touch either of these. If for some reason the bot loses permissions or is removed from the server, click this button again.
To manage roles, this bot role must be at the top of the hierarchy. Edit your Discord server, roles, and click and drag the role with the same name as your application to the top of the list. This role must stay at the top of the list for the bot to work. Finally, the owner of the bot account must enable 2 Factor Authentication (this is required from Discord for kicking and modifying member roles). If you are unsure what 2FA is or how to set it up, refer to [this support page](https://support.discordapp.com/hc/en-us/articles/219576828). It is also recommended to force 2FA on your server (this forces any admins or moderators to have 2fa enabled to perform similar functions on discord).
Note that the bot will never appear online as it does not participate in chat channels.
### Linking Accounts
Instead of the usual account creation procedure, for Discord to work we need to link accounts to Alliance Auth. When attempting to enable the Discord service, users are redirected to the official Discord site to authenticate. They will need to create an account if they don't have one prior to continuing. Upon authorization, users are redirected back to Alliance Auth with an OAuth code which is used to join the Discord server.
### Syncing Nicknames
If you want users to have their Discord nickname changed to their in-game character name, set `DISCORD_SYNC_NAMES` to `True`
## Managing Roles
Once users link their accounts you’ll notice Roles get populated on Discord. These are the equivalent to Groups on every other service. The default permissions should be enough for members to use text and audio communications. Add more permissions to the roles as desired through the server management window.
## Troubleshooting
### "Unknown Error" on Discord site when activating service
This indicates your callback URL doesn't match. Ensure the `DISCORD_CALLBACK_URL` setting exactly matches the URL entered on the Discord developers site. This includes http(s), trailing slash, etc.

125
docs/installation/services/discourse.md
View File

@@ -1,125 +0,0 @@
# Discourse
## Prepare Your Settings
In your auth project's settings file, do the following:
- Add `'allianceauth.services.modules.discourse',` to your `INSTALLED_APPS` list
- Append the following to your local.py settings file:
# Discourse Configuration
DISCOURSE_URL = ''
DISCOURSE_API_USERNAME = ''
DISCOURSE_API_KEY = ''
DISCOURSE_SSO_SECRET = ''
## Install Docker
wget -qO- https://get.docker.io/ | sh
## Install Discourse
### Download Discourse
mkdir /var/discourse
git clone https://github.com/discourse/discourse_docker.git /var/discourse
### Configure
cd /var/discourse
cp samples/standalone.yml containers/app.yml
nano containers/app.yml
Change the following:
- `DISCOURSE_DEVELOPER_EMAILS` should be a list of admin account email addresses separated by commas.
- `DISCOUSE_HOSTNAME` should be `discourse.example.com` or something similar.
- Everything with `SMTP` depends on your mail settings. [There are plenty of free email services online recommended by Discourse](https://github.com/discourse/discourse/blob/master/docs/INSTALL-email.md#recommended-email-providers-for-discourse) if you haven't set one up for auth already.
To install behind Apache/Nginx, look for this section:
...
## which TCP/IP ports should this container expose?
expose:
- "80:80" # fwd host port 80 to container port 80 (http)
...
Change it to this:
...
## which TCP/IP ports should this container expose?
expose:
- "7890:80" # fwd host port 7890 to container port 80 (http)
...
Or any other port will do, if taken. Remember this number.
### Build and launch
nano /etc/default/docker
Uncomment this line:
DOCKER_OPTS="--dns 8.8.8.8 --dns 8.8.4.4"
Restart Docker:
service docker restart
Now build:
./launcher bootstrap app
./launcher start app
## Web Server Configuration
You will need to configure your web server to proxy requests to Discourse.
A minimal Apache config might look like:
<VirtualHost *:80>
ServerName discourse.example.com
ProxyPass / http://0.0.0.0:7890/
ProxyPassReverse / http://0.0.0.0:7890/
</VirtualHost>
A minimal Nginx config might look like:
server {
listen 80;
server_name discourse.example.com;
location / {
include proxy_params;
proxy_pass http://127.0.0.1:7890;
}
}
## Configure API
### Generate admin account
From the `/var/discourse` directory,
./launcher enter app
rake admin:create
Follow prompts, being sure to answer `y` when asked to allow admin privileges.
### Create API key
Navigate to `discourse.example.com` and log on. Top right press the 3 lines and select `Admin`. Go to API tab and press `Generate Master API Key`.
Add the following values to your auth project's settings file:
- `DISCOURSE_URL`: `https://discourse.example.com` (do not add a trailing slash!)
- `DISCOURSE_API_USERNAME`: the username of the admin account you generated the API key with
- `DISCOURSE_API_KEY`: the key you just generated
### Configure SSO
Navigate to `discourse.example.com` and log in. Back to the admin site, scroll down to find SSO settings and set the following:
- `enable_sso`: True
- `sso_url`: `http://example.com/discourse/sso`
- `sso_secret`: some secure key
Save, now set `DISCOURSE_SSO_SECRET` in your auth project's settings file to the secure key you just put in Discourse.
Finally run migrations and restart Gunicorn and Celery.

18
docs/installation/services/index.md
View File

@@ -1,18 +0,0 @@
# Services
```eval_rst
.. toctree::
permissions
discord
discourse
mumble
openfire
phpbb3
smf
teamspeak3
xenforo
jacknife
pathfinder
```

105
docs/installation/services/mumble.md
View File

@@ -1,105 +0,0 @@
# Mumble
## Prepare Your Settings
In your auth project's settings file, do the following:
- Add `'allianceauth.services.modules.mumble',` to your `INSTALLED_APPS` list
- Append the following to your local.py settings file:
# Mumble Configuration
MUMBLE_URL = ""
## Overview
Mumble is a free voice chat server. While not as flashy as TeamSpeak, it has all the functionality and is easier to customize. And is better. I may be slightly biased.
## Dependencies
The mumble server package can be retrieved from a repository we need to add, mumble/release.
apt-add-repository ppa:mumble/release
apt-get update
Now two packages need to be installed:
apt-get install python-software-properties mumble-server
Download the appropriate authenticator release from [the authenticator repository](https://gitlab.com/allianceauth/mumble-authenticator) and install the python dependencies for it:
pip install -r requirements.txt
## Configuring Mumble
Mumble ships with a configuration file that needs customization. By default it’s located at /etc/mumble-server.ini. Open it with your favourite text editor:
nano /etc/mumble-server.ini
REQUIRED: To enable the ICE authenticator, edit the following:
- `icesecretwrite=MY_CLEVER_PASSWORD`, obviously choosing a secure password
- ensure the line containing `Ice="tcp -h 127.0.0.1 -p 6502"` is uncommented
By default mumble operates on SQLite which is fine, but slower than a dedicated MySQL server. To customize the database, edit the following:
- uncomment the database line, and change it to `database=alliance_mumble`
- `dbDriver=QMYSQL`
- `dbUsername=allianceserver` or whatever you called the Alliance Auth MySQL user
- `dbPassword=` that user’s password
- `dbPort=3306`
- `dbPrefix=murmur_`
To name your root channel, uncomment and set `registerName=` to whatever cool name you want
Save and close the file.
To get Mumble superuser account credentials, run the following:
dpkg-reconfigure mumble-server
Set the password to something you’ll remember and write it down. This is needed to manage ACLs.
Now restart the server to see the changes reflected.
service mumble-server restart
That’s it! Your server is ready to be connected to at example.com:64738
## Configuring the Authenticator
The ICE authenticator lives in the mumble-authenticator repository, cd to the directory where you cloned it.
Make a copy of the default config:
cp authenticator.ini.example authenticator.ini
Edit `authenticator.ini` and change these values:
- `[database]`
- `user = ` your allianceserver MySQL user
- `password = ` your allianceserver MySQL user's password
- `[ice]`
- `secret = ` the `icewritesecret` password set earlier
Test your configuration by starting it: `python authenticator.py`
## Running the 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:
```
[program:authenticator]
command=/path/to/venv/bin/python authenticator.py
directory=/path/to/authenticator/directory/
user=allianceserver
stdout_logfile=/path/to/authenticator/directory/authenticator.log
stderr_logfile=/path/to/authenticator/directory/authenticator.log
autostart=true
autorestart=true
startsecs=10
priority=998
```
Note that groups will only be created on Mumble automatically when a user joins who is in the group.
## Prepare Auth
In your project's settings file, set `MUMBLE_URL` to the public address of your mumble server. Do not include any leading `http://` or `mumble://`.
Run migrations and restart Gunicorn and Celery to complete setup.

135
docs/installation/services/openfire.md
View File

@@ -1,135 +0,0 @@
# Openfire
Openfire is a Jabber (XMPP) server.
## Prepare Your Settings
- Add `'allianceauth.services.modules.openfire',` to your `INSTALLED_APPS` list
- Append the following to your auth project's settings file:
# Jabber Configuration
JABBER_URL = ""
JABBER_PORT = 5223
JABBER_SERVER = ""
OPENFIRE_ADDRESS = ""
OPENFIRE_SECRET_KEY = ""
BROADCAST_USER = ""
BROADCAST_USER_PASSWORD = ""
BROADCAST_SERVICE_NAME = "broadcast"
## Dependencies
Openfire require a Java 8 runtime environment.
Ubuntu:
apt-get install openjdk-8-jdk
CentOS:
yum -y install java-1.8.0-openjdk java-1.8.0-openjdk-devel
## Setup
### Download Installer
Openfire is not available through repositories so we need to get a package from the developer.
On your PC, navigate to the [Ignite Realtime downloads section](https://www.igniterealtime.org/downloads/index.jsp), and under Openfire select Linux, click on the Ubuntu: Debian package (second from bottom of list, ends with .deb) or CentOS: RPM Package (no JRE bundled, as we have installed it on the host)
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 ~`
Now download the package. Replace the link below with the link you got earlier.
wget https://www.igniterealtime.org/downloadServlet?filename=openfire/openfire_4.2.3_all.deb
Now install from the package. Replace the filename with your filename (the last part of the download URL is the file name)
Ubuntu:
dpkg -i openfire_4.2.3_all.deb
CentOS:
yum install -y openfire-4.2.3-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:
mysql -u root -p
create database alliance_jabber;
grant all privileges on alliance_jabber . * to 'allianceserver'@'localhost';
exit;
### Web Configuration
The remainder of the setup occurs through Openfire’s web interface. Navigate to http://example.com:9090, or if you’re behind CloudFlare, go straight to your server’s IP:9090.
Select your language. I sure hope it’s English if you’re reading this guide.
Under Server Settings, set the Domain to `example.com` replacing it with your actual domain. Don’t touch the rest.
Under Database Settings, select `Standard Database Connection`
On the next page, select `MySQL` from the dropdown list and change the following:
- `[server]` is replaced by `127.0.0.1`
- `[database]` is replaced by the name of the database to be used by Openfire
- enter the login details for your auth project's database user
If Openfire returns with a failed to connect error, re-check these settings. Note the lack of square brackets.
Under Profile Settings, leave `Default` selected.
Create an administrator account. The actual name is irrelevant, just don’t lose this login information.
Finally, log in to the console with your admin account.
Edit your auth project's settings file and enter the values you just set:
- `JABBER_URL` is the pubic address of your jabber server
- `JABBER_PORT` is the port for clients to connect to (usually 5223)
- `JABBER_SERVER` is the name of the jabber server. If you didn't alter it during install it'll usually be your domain (eg `example.com`)
- `OPENFIRE_ADDRESS` is the web address of Openfire's web interface. Use http:// with port 9090 or https:// with port 9091 if you configure SSL in Openfire
### REST API Setup
Navigate to the `plugins` tab, and then `Available Plugins` on the left navigation bar. You’ll need to fetch the list of available plugins by clicking the link.
Once loaded, press the green plus on the right for `REST API`.
Navigate the `Server` tab, `Sever Settings` subtab. At the bottom of the left navigation bar select `REST API`.
Select `Enabled`, and `Secret Key Auth`. Update your auth project's settings with this secret key as `OPENFIRE_SECRET_KEY`.
### Broadcast Plugin Setup
Navigate to the `Users/Groups` tab and select `Create New User` from the left navigation bar.
Pick a username (e.g. `broadcast`) and password for your ping user. Enter these in your auth project's settings file as `BROADCAST_USER` and `BROADCAST_USER_PASSWORD`. Note that `BROADCAST_USER` needs to be in the format `user@example.com` matching your jabber server name. Press `Create User` to save this user.
Broadcasting requires a plugin. Navigate to the `plugins` tab, press the green plus for the `Broadcast` plugin.
Navigate to the `Server` tab, `Server Manager` subtab, and select `System Properties`. Enter the following:
- Name: `plugin.broadcast.disableGroupPermissions`
- Value: `True`
- Do not encrypt this property value
- Name: `plugin.broadcast.allowedUsers`
- Value: `broadcast@example.com`, replacing the domain name with yours
- Do not encrypt this property value
If you have troubles getting broadcasts to work, you can try setting the optional (you will need to add it) `BROADCAST_IGNORE_INVALID_CERT` setting to `True`. This will allow invalid certificates to be used when connecting to the Openfire server to send a broadcast.
### Preparing Auth
Once all settings are entered, run migrations and restart Gunicorn and Celery.
### Group Chat
Channels are available which function like a chat room. Access can be controlled either by password or ACL (not unlike mumble).
Navigate to the `Group Chat` tab and select `Create New Room` from the left navigation bar.
- Room ID is a short, easy-to-type version of the room’s name users will connect to
- Room Name is the full name for the room
- Description is short text describing the room’s purpose
- Set a password if you want password authentication
- Every other setting is optional. Save changes.
Now select your new room. On the left navigation bar, select `Permissions`.
ACL is achieved by assigning groups to each of the three tiers: `Owners`, `Admins` and `Members`. `Outcast` is the blacklist. You’ll usually only be assigning groups to the `Member` category.

33
docs/installation/services/permissions.md
View File

@@ -1,33 +0,0 @@
# Service Permissions
In the past, access to services was dictated by a list of settings in `settings.py`, granting access to each particular service for Members and/or Blues. This meant that granting access to a service was very broad and rigidly structured around these two states.
## Permissions based access
Instead of granting access to services by the previous rigid structure, access to services is now granted by the built in Django permissions system. This means that service access can be more granular, allowing only certain states, certain groups, for instance Corp CEOs, or even individual user access to each enabled service.
```eval_rst
.. important::
If you grant access to an individual user, they will have access to that service regardless of whether or not they are a member.
```
Each service has an access permission defined, named like `Can access the <service name> service`.
To mimick the old behaviour of enabling services for all members, you would select the `Member` group from the admin panel, add the required service permission to the group and save. Likewise for Blues, select the `Blue` group and add the required permission.
A user can be granted the same permission from multiple sources. e.g. they may have it granted by several groups and directly granted on their account as well. Auth will not remove their account until all instances of the permission for that service have been revoked.
## Removing access
```eval_rst
.. danger::
Access removal is processed immediately after removing a permission from a user or group. If you remove access from a large group, such as Member, it will immediately remove all users from that service.
```
When you remove a service permission from a user, a signal is triggered which will activate an immediate permission check. For users this will trigger an access check for all services. For groups, due to the potential extra load, only the services whose permissions have changed will be verified, and only the users in that group.
If a user no longer has permission to access the service when this permissions check is triggered, that service will be immediately disabled for them.
### Disabling user accounts
When you unset a user as active in the admin panel, all of that users service accounts will be immediately disabled or removed. This is due to the built in behaviour of the Django permissions system, which will return False for all permissions if a users account is disabled, regardless of their actual permissions state.

158
docs/installation/services/phpbb3.md
View File

@@ -1,158 +0,0 @@
# phpBB3
## Overview
phpBB is a free PHP-based forum.
## Dependencies
phpBB3 requires PHP installed in your web server. Apache has `mod_php`, NGINX requires `php-fpm`. See [the official guide](https://www.phpbb.com/community/docs/INSTALL.html) for PHP package requirements.
## Prepare Your Settings
In your auth project's settings file, do the following:
- Add `'allianceauth.services.modules.phpbb3',` to your `INSTALLED_APPS` list
- Append the following to the bottom of the settings file:
# PHPBB3 Configuration
PHPBB3_URL = ''
DATABASES['phpbb3'] = {
'ENGINE': 'django.db.backends.mysql',
'NAME': 'alliance_forum',
'USER': 'allianceserver-phpbb3',
'PASSWORD': 'password',
'HOST': '127.0.0.1',
'PORT': '3306',
}
## Setup
### Prepare the Database
Create a database to install phpBB3 in.
mysql -u root -p
create database alliance_forum;
grant all privileges on alliance_forum . * to 'allianceserver'@'localhost';
exit;
Edit your auth project's settings file and fill out the `DATABASES['phpbb3']` part.
### Download phpBB3
phpBB3 is available as a zip from their website. Navigate to the website’s [downloads section](https://www.phpbb.com/downloads/) using your PC browser and copy the URL for the latest version zip.
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
wget https://www.phpbb.com/files/release/phpBB-3.2.2.zip
This needs to be unpackaged. Unzip it, replacing the file name with that of the file you just downloaded
unzip phpBB-3.2.2.zip
Now we need to move this to our web directory. Usually `/var/www/forums`.
mv phpBB3 /var/www/forums
The web server needs read/write permission to this folder
Apache: `chown -R www-data:www-data /var/www/forums`
Nginx: `chown -R nginx:nginx /var/www/forums`
```eval_rst
.. tip::
Nginx: Some distributions use the ``www-data:www-data`` user:group instead of ``nginx:nginx``. If you run into problems with permissions try it instead.
..
```
### Configuring Web Server
You will need to configure you web server to serve PHPBB3 before proceeding with installation.
A minimal Apache config file might look like:
<VirtualHost *:80>
ServerName forums.example.com
DocumentRoot /var/www/forums
<Directory /var/www/forums>
Require all granted
DirectoryIndex index.php
</Directory>
</VirtualHost>
A minimal Nginx config file might look like:
server {
listen 80;
server_name forums.example.com;
root /var/www/forums;
index index.php;
access_log /var/logs/forums.access.log;
location ~ /(config\.php|common\.php|cache|files|images/avatars/upload|includes|store) {
deny all;
return 403;
}
location ~* \.(gif|jpe?g|png|css)$ {
expires 30d;
}
location ~ \.php$ {
try_files $uri =404;
fastcgi_pass unix:/tmp/php.socket;
fastcgi_index index.php;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
include fastcgi_params;
}
}
Enter your forum's web address as the `PHPBB3_URL` setting in your auth project's settings file.
### Web Install
Navigate to your forums web address where you will be presented with an installer.
Click on the `Install` tab.
All the requirements should be met. Press `Start Install`.
Under Database Settings, set the following:
- Database Type is `MySQL`
- Database Server Hostname is `127.0.0.1`
- Database Server Port is left blank
- Database Name is `alliance_forum`
- Database Username is your auth MySQL user, usually `allianceserver`
- Database Password is this user’s password
If you use a table prefix other than the standard `phpbb_` you need to add an additional setting to your auth project's settings file, `PHPBB3_TABLE_PREFIX = ''`, and enter the prefix.
You should see `Successful Connection` and proceed.
Enter administrator credentials on the next page.
Everything from here should be intuitive.
phpBB will then write its own config file.
### Open the Forums
Before users can see the forums, we need to remove the install directory
rm -rf /var/www/forums/install
### Enabling Avatars
AllianceAuth sets user avatars to their character portrait when the account is created or password reset. We need to allow external URLs for avatars for them to behave properly. Navigate to the admin control panel for phpbb3, and under the `General` tab, along the left navigation bar beneath `Board Configuration`, select `Avatar Settings`. Set `Enable Remote Avatars` to `Yes` and then `Submit`.
![location of the remote avatar setting](/_static/images/installation/services/phpbb3/avatar_settings.png)
You can allow members to overwrite the portrait with a custom image if desired. Navigate to `Users and Groups`, `Group Permissions`, select the appropriate group (usually `Member` if you want everyone to have this ability), expand `Advanced Permissions`, under the `Profile` tab, set `Can Change Avatars` to `Yes`, and press `Apply Permissions`.
![location of change avatar setting](/_static/images/installation/services/phpbb3/avatar_permissions.png)
## Setting the default theme
Users generated via Alliance Auth do not have a default theme set. You will need to set this on the phpbb_users table in SQL
mysql -u root -p
use alliance_forum;
alter table phpbb_users change user_style user_style int not null default 1
If you would like to use a theme that is NOT prosilver or theme "1". You will need to deactivate prosilver, this will then fall over to the set forum wide default.
### Prepare Auth
Once settings have been configured, run migrations and restart Gunicorn and Celery.

117
docs/installation/services/smf.md
View File

@@ -1,117 +0,0 @@
# SMF
## Overview
SMF is a free PHP-based forum.
## Dependencies
SMF requires PHP installed in your web server. Apache has `mod_php`, NGINX requires `php-fpm`. More details can be found in the [SMF requirements page.](https://download.simplemachines.org/requirements.php)
## Prepare Your Settings
In your auth project's settings file, do the following:
- Add `'allianceauth.services.modules.smf',` to your `INSTALLED_APPS` list
- Append the following to the bottom of the settings file:
# SMF Configuration
SMF_URL = ''
DATABASES['smf'] = {
'ENGINE': 'django.db.backends.mysql',
'NAME': 'alliance_smf',
'USER': 'allianceserver-smf',
'PASSWORD': 'password',
'HOST': '127.0.0.1',
'PORT': '3306',
}
## Setup
### Download SMF
Using your browser, you can download the latest version of SMF to your desktop computer. All SMF downloads can be found at SMF Downloads. The latest recommended version will always be available at http://www.simplemachines.org/download/index.php/latest/install/. Retrieve the file location from the hyperlinked box icon for the zip full install, depending on your browser you may have a Copy Link or similar option in your right click menu.
Download using wget, replacing the URL with the URL for the package you just retrieved
wget https://download.simplemachines.org/index.php?thanks;filename=smf_2-0-15_install.zip
This needs to be unpackaged. Unzip it, replacing the file name with that of the file you just downloaded
unzip smf_2-0-15_install.zip
Now we need to move this to our web directory. Usually `/var/www/forums`.
mv smf /var/www/forums
The web server needs read/write permission to this folder
Apache: `chown -R www-data:www-data /var/www/forums`
Nginx: `chown -R nginx:nginx /var/www/forums`
```eval_rst
.. tip::
Nginx: Some distributions use the ``www-data:www-data`` user:group instead of ``nginx:nginx``. If you run into problems with permissions try it instead.
..
```
### Database Preparation
SMF needs a database. Create one:
mysql -u root -p
create database alliance_smf;
grant all privileges on alliance_smf . * to 'allianceserver'@'localhost';
exit;
Enter the database information into the `DATABASES['smf']` section of your auth project's settings file.
### Web Server Configuration
Your web server needs to be configured to serve SMF.
A minimal Apache config might look like:
<VirtualHost *:80>
ServerName forums.example.com
DocumentRoot /var/www/forums
<Directory "/var/www/forums">
DirectoryIndex index.php
</Directory>
</VirtualHost>
A minimal Nginx config might look like:
server {
listen 80;
server_name forums.example.com;
root /var/www/forums;
index index.php;
access_log /var/logs/forums.access.log;
location ~ \.php$ {
try_files $uri =404;
fastcgi_pass unix:/tmp/php.socket;
fastcgi_index index.php;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
include fastcgi_params;
}
}
Enter the web address to your forums into the `SMF_URL` setting in your auth project's settings file.
### Web Install
Navigate to your forums address where you will be presented with an installer.
Click on the `Install` tab.
All the requirements should be met. Press `Start Install`.
Under Database Settings, set the following:
- Database Type is `MySQL`
- Database Server Hostname is `127.0.0.1`
- Database Server Port is left blank
- Database Name is `alliance_smf`
- Database Username is your auth MySQL user, usually `allianceserver`
- Database Password is this user’s password
If you use a table prefix other than the standard `smf_` you need to add an additional setting to your auth project's settings file, `SMF_TABLE_PREFIX = ''`, and enter the prefix.
Follow the directions in the installer.
### Preparing Auth
Once settings are entered, apply migrations and restart Gunicorn and Celery.

130
docs/installation/services/teamspeak3.md
View File

@@ -1,130 +0,0 @@
# TeamSpeak 3
## Overview
TeamSpeak3 is the most popular VOIP program for gamers.
But have you considered using Mumble? Not only is it free, but it has features and performance far superior to Teamspeak3.
## Setup
Sticking with TS3? Alright, I tried.
### Prepare Your Settings
In your auth project's settings file, do the following:
- Add `'allianceauth.services.modules.teamspeak3',` to your `INSTALLED_APPS` list
- Append the following to the bottom of the settings file:
# Teamspeak3 Configuration
TEAMSPEAK3_SERVER_IP = '127.0.0.1'
TEAMSPEAK3_SERVER_PORT = 10011
TEAMSPEAK3_SERVERQUERY_USER = 'serveradmin'
TEAMSPEAK3_SERVERQUERY_PASSWORD = ''
TEAMSPEAK3_VIRTUAL_SERVER = 1
TEAMSPEAK3_PUBLIC_URL = ''
CELERYBEAT_SCHEDULE['run_ts3_group_update'] = {
'task': 'allianceauth.services.modules.teamspeak3.tasks.run_ts3_group_update',
'schedule': crontab(minute='*/30'),
}
### 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.
Download the server, replacing the link with the link you got earlier.
http://dl.4players.de/ts/releases/3.1.1/teamspeak3-server_linux_amd64-3.1.1.tar.bz2
Now we need to extract the file.
tar -xf teamspeak3-server_linux_amd64-3.1.0.tar.bz2
### Create User
TeamSpeak needs its own user.
adduser --disabled-login teamspeak
### Install Binary
Now we move the server binary somewhere more accessible and change its ownership to the new user.
mv teamspeak3-server_linux_amd64 /usr/local/teamspeak
chown -R teamspeak:teamspeak /usr/local/teamspeak
### Startup
Now we generate a startup script so TeamSpeak comes up with the server.
ln -s /usr/local/teamspeak/ts3server_startscript.sh /etc/init.d/teamspeak
update-rc.d teamspeak defaults
Finally we start the server.
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**.
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
- `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://
Once settings are entered, run migrations and restart Gunicorn and Celery.
### Generate User Account
And now we can generate ourselves a user account. Navigate to the services in Alliance Auth for your user account and press the checkmark for TeamSpeak 3.
Click the URL provided to automatically connect to our server. It will prompt you to redeem the serveradmin token, enter the `token` from startup.
### Groups
Now we need to make groups. AllianceAuth handles groups in teamspeak differently: instead of creating groups it creates an association between groups in TeamSpeak and groups in AllianceAuth. Go ahead and make the groups you want to associate with auth groups, keeping in mind multiple TeamSpeak groups can be associated with a single auth group.
Navigate back to the AllianceAuth admin interface (example.com/admin) and under `Services`, select `Auth / TS Groups`. In the top-right corner click `Add`.
The dropdown box provides all auth groups. Select one and assign TeamSpeak groups from the panels below. If these panels are empty, wait a minute for the database update to run, or see the [troubleshooting section](#ts-group-models-not-populating-on-admin-site) below.
## Troubleshooting
### `Insufficient client permissions (failed on Invalid permission: 0x26)`
Using the advanced permissions editor, ensure the `Guest` group has the permission `Use Privilege Keys to gain permissions` (under `Virtual Server` expand the `Administration` section)
To enable advanced permissions, on your client go to the `Tools` menu, `Application`, and under the `Misc` section, tick `Advanced permission system`
### TS group models not populating on admin site
The method which populates these runs every 30 minutes. To populate manually, start a django shell:
python manage.py shell
And execute the update:
from services.modules.teamspeak3.tasks import Teamspeak3Tasks
Teamspeak3Tasks.run_ts3_group_update()
Ensure that command does not return an error.
### `2564 access to default group is forbidden`
This usually occurs because auth is trying to remove a user from the `Guest` group (group ID 8). The guest group is only assigned to a user when they have no other groups, unless you have changed the default teamspeak server config.
Teamspeak servers v3.0.13 and up are especially susceptible to this. Ensure the Channel Admin Group is not set to `Guest (8)`. Check by right clicking on the server name, `Edit virtual server`, and in the middle of the panel select the `Misc` tab.
### `TypeError: string indices must be integers, not str`
This error generally means teamspeak returned an error message that went unhandled. The full traceback is required for proper debugging, which the logs do not record. Please check the superuser notifications for this record and get in touch with a developer.
### `3331 flood ban`
This most commonly happens when your teamspeak server is externally hosted. You need to add the auth server IP to the teamspeak serverquery whitelist. This varies by provider.
If you have SSH access to the server hosting it, you need to locate the teamspeak server folder and add the auth server IP on a new line in `server_query_whitelist.txt`
### `520 invalid loginname or password`
The serverquery account login specified in local.py is incorrect. Please verify `TEAMSPEAK3_SERVERQUERY_USER` and `TEAMSPEAK3_SERVERQUERY_PASSWORD`. The [installation section](#update-settings) describes where to get them.
### `2568 insufficient client permissions`
This usually occurs if you've created a separate serverquery user to use with auth. It has not been assigned sufficient permissions to complete all the tasks required of it. The full list of required permissions is not known, so assign liberally.

40
docs/installation/services/xenforo.md
View File

@@ -1,40 +0,0 @@
# XenForo
## Overview
[XenForo](https://xenforo.com/) is a popular paid forum. This guide will assume that you already have XenForo installed with a valid license (please keep in mind that XenForo is not free nor open-source, therefore you need to purchase a license first). If you come across any problems related with the installation of XenForo please contact their support service.
## Prepare Your Settings
In your auth project's settings file, do the following:
- Add `'allianceauth.services.modules.xenforo',` to your `INSTALLED_APPS` list
- Append the following to your local.py settings file:
# XenForo Configuration
XENFORO_ENDPOINT = 'example.com/api.php'
XENFORO_DEFAULT_GROUP = 0
XENFORO_APIKEY = 'yourapikey'
## XenAPI
By default XenForo does not support any kind of API, however there is a third-party package called [XenAPI](https://github.com/Contex/XenAPI) which provides a simple REST interface by which we can access XenForo's functions in order to create and edit users.
The installation of XenAPI is pretty straight forward. The only thing you need to do is to download the `api.php` from the official repository and upload it in the root folder of your XenForo installation. The final result should look like this:
*forumswebsite.com/***api.php**
Now that XenAPI is installed the only thing left to do is to provide a key.
```php
$restAPI = new RestAPI('REPLACE_THIS_WITH_AN_API_KEY');
```
## Configuration
The settings you created earlier now need to be filled out.
`XENFORO_ENDPOINT` is the address to the API you added. No leading `http://`, but be sure to include the `/api.php` at the end.
`XENFORO_DEFAULT_GROUP` is the ID of the group in XenForo auth users will be added to. Unfortunately XenAPI **cannot create new groups**, therefore you have to create a group manually and then get its ID.
`XENFORO_API_KEY` is the API key value you set earlier.
Once these are entered, run migrations and restart Gunicorn and Celery.

18
docs/installation/auth/upgradev1.md → docs/installation/upgradev1.md
View File

@@ -1,4 +1,4 @@
# Upgrading from v1.15
# Upgrading from AA v1.15
It's possible to preserve a v1 install's database and migrate it to v2. This will retain all service accounts, user accounts with their main character, but will purge API keys and alts.
@@ -44,19 +44,21 @@ Because character ownership is tracked separately of main character it is not po
### Members and Blues
The new [state system](../../features/states.md) allows configuring dynamic membership states through the admin page. Unfortunately if you make a change after migrating it will immediately assess user states and see that no one should be a member. You can add additional settings to your auth project's settings file to generate the member and blue states as you have them defined in v1:
- `ALLIANCE_IDS = []` a list of member alliance IDs
- `CORP_IDS = []` a list of member corporation IDs
- `BLUE_ALLIANCE_IDS = []` a list of blue alliance IDs
- `BLUE_CORP_IDS = []` a list of blue corporation IDs
The new [state system](../../features/core/states.md) allows configuring dynamic membership states through the admin page. Unfortunately if you make a change after migrating it will immediately assess user states and see that no one should be a member. You can add additional settings to your auth project's settings file to generate the member and blue states as you have them defined in v1:
- `ALLIANCE_IDS = []` a list of member alliance IDs
- `CORP_IDS = []` a list of member corporation IDs
- `BLUE_ALLIANCE_IDS = []` a list of blue alliance IDs
- `BLUE_CORP_IDS = []` a list of blue corporation IDs
Put comma-separated IDs into the brackets and the migration will create states with the members and blues you had before. This will prevent unexpected state purging when you edit states via the admin site.
### Default Groups
If you used member/blue group names other than the standard "Member" and "Blue" you can enter settings to have the member/blue states created through this migration take these names.
- `DEFAULT_AUTH_GROUP = ""` the desired name of the "Member" state
- `DEFAULT_BLUE_GROUP = ""` the desired name of the "Blue" state
- `DEFAULT_AUTH_GROUP = ""` the desired name of the "Member" state
- `DEFAULT_BLUE_GROUP = ""` the desired name of the "Blue" state
Any permissions assigned to these groups will be copied to the state replacing them. Because these groups are no longer managed they pose a security risk and so are deleted at the end of the migration automatically.