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

94
docs/features/services/discord.md Normal file
View File

@@ -0,0 +1,94 @@
# 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:
```python
# 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.

130
docs/features/services/discourse.md Normal file
View File

@@ -0,0 +1,130 @@
# 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:
```python
# 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.

29
docs/features/services/index.md Normal file
View File

@@ -0,0 +1,29 @@
# Services
**Alliance Auth** supports managing access to many 3rd party services and apps. This section describes which services are supported and how to install and configure them. Please note that any service need to be installed and configured before it can be used.
## Supported Services
```eval_rst
.. toctree::
:maxdepth: 1
discord
discourse
mumble
openfire
phpbb3
smf
teamspeak3
xenforo
```
## Tools
```eval_rst
.. toctree::
:maxdepth: 1
nameformats
permissions
```

106
docs/features/services/mumble.md Normal file
View File

@@ -0,0 +1,106 @@
# 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:
```python
# 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.

82
docs/features/services/nameformats.md Normal file
View File

@@ -0,0 +1,82 @@
# Services Name Formats
This app allows you to customize how usernames for services are created.
Each service's username or nickname, depending on which the service supports, can be customized through the use of the Name Formatter config provided the service supports custom formats. This config can be found in the admin panel under **Services -> Name format config**
Currently the following services support custom name formats:
```eval_rst
+-------------+-----------+-------------------------------------+
| Service | Used with | Default Formatter |
+=============+===========+=====================================+
| Discord | Nickname | ``{character_name}`` |
+-------------+-----------+-------------------------------------+
| Discourse | Username | ``{character_name}`` |
+-------------+-----------+-------------------------------------+
| IPS4 | Username | ``{character_name}`` |
+-------------+-----------+-------------------------------------+
| Mumble | Username | ``[{corp_ticker}]{character_name}`` |
+-------------+-----------+-------------------------------------+
| Openfire | Username | ``{character_name}`` |
+-------------+-----------+-------------------------------------+
| phpBB3 | Username | ``{character_name}`` |
+-------------+-----------+-------------------------------------+
| SMF | Username | ``{character_name}`` |
+-------------+-----------+-------------------------------------+
| Teamspeak 3 | Nickname | ``[{corp_ticker}]{character_name}`` |
+-------------+-----------+-------------------------------------+
| Xenforo | Username | ``{character_name}`` |
+-------------+-----------+-------------------------------------+
```
```eval_rst
.. note::
It's important to note here, before we get into what you can do with a name formatter, that before the generated name is passed off to the service to create an account it will be sanitized to remove characters (the letters and numbers etc.) that the service cannot support. This means that, despite what you configured, the service may display something different. It is up to you to test your formatter and understand how your format may be disrupted by a certain services sanitization function.
```
## Available format data
The following fields are available from a users account and main character:
- `username` - Alliance Auth username
- `character_id`
- `character_name`
- `corp_id`
- `corp_name`
- `corp_ticker`
- `alliance_id`
- `alliance_name`
- `alliance_ticker`
- `alliance_or_corp_name` (defaults to Corporation name if there is no Alliance)
- `alliance_or_corp_ticker` (defaults to Corporation ticker if there is no Alliance)
## Building a formatter string
The name formatter uses the advanced string formatting specified by [PEP-3101](https://www.python.org/dev/peps/pep-3101/). Anything supported by this specification is supported in a name formatter.
A more digestible documentation of string formatting in Python is available on the [PyFormat](https://pyformat.info/) website.
Some examples of strings you could use:
```eval_rst
+------------------------------------------+---------------------------+
| Formatter | Result |
+==========================================+===========================+
| ``{alliance_ticker} - {character_name}`` | ``MYALLI - My Character`` |
+------------------------------------------+---------------------------+
| ``[{corp_ticker}] {character_name}`` | ``[CORP] My Character`` |
+------------------------------------------+---------------------------+
| ``{{{corp_name}}}{character_name}`` | ``{My Corp}My Character`` |
+------------------------------------------+---------------------------+
```
```eval_rst
.. important::
For most services, name formats only take effect when a user creates an account. This means if you create or update a name formatter it wont retroactively alter the format of users names. There are some exceptions to this where the service updates nicknames on a periodic basis. Check the service's documentation to see which of these apply.
```
```eval_rst
.. important::
You must only create one formatter per service per state. E.g. don't create two formatters for Mumble for the Member state. In this case one of the formatters will be used and it may not be the formatter you are expecting.
```

137
docs/features/services/openfire.md Normal file
View File

@@ -0,0 +1,137 @@
# 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:
```python
# 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/features/services/permissions.md Normal file
View File

@@ -0,0 +1,33 @@
# 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.

156
docs/features/services/phpbb3.md Normal file
View File

@@ -0,0 +1,156 @@
# 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:
```python
# 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`.
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`.
## 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.

118
docs/features/services/smf.md Normal file
View File

@@ -0,0 +1,118 @@
# 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:
```python
# 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.

131
docs/features/services/teamspeak3.md Normal file
View File

@@ -0,0 +1,131 @@
# 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:
```python
# 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.

41
docs/features/services/xenforo.md Normal file
View File

@@ -0,0 +1,41 @@
# 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:
```python
# 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.