Merge branch 'v4docs' into 'v4.x'

Expand Docker Docs for v4

See merge request allianceauth/allianceauth!1577

docs/_static/css/rtd_dark.css

@@ -24,8 +24,13 @@
         color: aliceblue;
     }
 
-    .method dt, .class dt, .data dt, .attribute dt, .function dt,
+    .method dt,
-    .descclassname, .descname {
+    .class dt,
+    .data dt,
+    .attribute dt,
+    .function dt,
+    .descclassname,
+    .descname {
         background-color: #525252 !important;
         color: white !important;
     }
@@ -51,11 +56,13 @@
         background-color: #2b2b2b !important;
     }
 
-    .xref, .py-meth {
+    .xref,
+    .py-meth {
         color: #7ec3e6 !important;
     }
 
-    .admonition, .note {
+    .admonition,
+    .note {
         background-color: #2d2d2d !important;
     }
 
@@ -64,19 +71,27 @@
         border-bottom: 1px solid #fcfcfc;
     }
 
-    .wy-table thead, .rst-content table.docutils thead, .rst-content table.field-list thead {
+    .wy-table thead,
+    .rst-content table.docutils thead,
+    .rst-content table.field-list thead {
         background-color: #b9b9b9;
     }
 
-    .wy-table thead th, .rst-content table.docutils thead th, .rst-content table.field-list thead th {
+    .wy-table thead th,
+    .rst-content table.docutils thead th,
+    .rst-content table.field-list thead th {
         border: solid 2px #e1e4e5;
     }
 
-    .wy-table thead p, .rst-content table.docutils thead p, .rst-content table.field-list thead p {
+    .wy-table thead p,
+    .rst-content table.docutils thead p,
+    .rst-content table.field-list thead p {
         margin: 0;
     }
 
-    .wy-table-odd td, .wy-table-striped tr:nth-child(2n-1) td, .rst-content table.docutils:not(.field-list) tr:nth-child(2n-1) td {
+    .wy-table-odd td,
+    .wy-table-striped tr:nth-child(2n-1) td,
+    .rst-content table.docutils:not(.field-list) tr:nth-child(2n-1) td {
         background-color: #343131;
     }
 
@@ -91,10 +106,6 @@
 
     /* Name.Variable */
 
-    body {
-        text-align: justify;
-    }
-
     .rst-content .section .admonition ul {
         margin-bottom: 0;
     }

docs/features/services/index.md

@@ -10,10 +10,13 @@
 discord
 discourse
 mumble
+mumble-docker
 openfire
+openfire-docker
 phpbb3
 smf
 teamspeak3
+teamspeak3-docker
 xenforo
 :::
 

docs/features/services/mumble-docker.md

@@ -0,0 +1,207 @@
+# Mumble
+
+An alternate install guide for Mumble using Docker, better suited to an Alliance Auth Docker install
+
+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.
+
+## Configuring Auth
+
+In your auth project's settings file (`aa-docker/conf/local.py`), do the following:
+
+- Add `'allianceauth.services.modules.mumble',` to your `INSTALLED_APPS` list
+- Append the following to your auth project's settings file:
+
+```python
+# Mumble Configuration
+MUMBLE_URL = "mumble.example.com"
+```
+
+Add the following lines to your `.env` file
+
+```env
+# Mumble
+MUMBLE_SUPERUSER_PASSWORD = superuser_password
+MUMBLE_ICESECRETWRITE = icesecretwrite
+MUMBLE_SERVERPASSWORD = serverpassword
+```
+
+Finally, restart your stack and run migrations
+
+```shell
+docker compose --env-file=.env up -d
+docker compose exec allianceauth_gunicorn bash
+auth migrate
+```
+
+## Docker Installations
+
+### Installing Mumble and Authenticator
+
+Inside your `aa-docker` directory, clone the authenticator to a sub directory as follows
+
+```shell
+git clone https://gitlab.com/allianceauth/mumble-authenticator.git
+```
+
+Add the following to your `docker-compose.yml` under the `services:` section
+
+```docker
+  mumble-server:
+    image: mumblevoip/mumble-server:latest
+    restart: always
+    environment:
+    - MUMBLE_SUPERUSER_PASSWORD=${MUMBLE_SUPERUSER_PASSWORD}
+    - MUMBLE_CONFIG_ice="tcp -h 127.0.0.1 -p 6502"
+    - MUMBLE_CONFIG_icesecretwrite=${MUMBLE_ICESECRETWRITE}
+    - MUMBLE_CONFIG_serverpassword=${MUMBLE_SERVERPASSWORD}
+    - MUMBLE_CONFIG_opusthreshold=0
+    - MUMBLE_CONFIG_suggestPushToTalk=true
+    - MUMBLE_CONFIG_suggestVersion=1.4.0
+    ports:
+      - 64738:64738
+      - 64738:64738/udp
+    logging:
+      driver: "json-file"
+      options:
+        max-size: "10Mb"
+        max-file: "5"
+
+  mumble-authenticator:
+    build
+      context: .
+      dockerfile: ./mumble-authenticator/Dockerfile
+    restart: always
+    volumes:
+      - ./mumble-authenticator/authenticator.py:/authenticator.py
+      - ./mumble-authenticator/authenticator.ini.docker:/authenticator.ini
+    environment:
+    - MUMBLE_SUPERUSER_PASSWORD=${MUMBLE_SUPERUSER_PASSWORD}
+    - MUMBLE_CONFIG_ice="tcp -h 127.0.0.1 -p 6502"
+    - MUMBLE_CONFIG_icesecretwrite=${MUMBLE_ICESECRETWRITE}
+    - MUMBLE_CONFIG_serverpassword=${MUMBLE_SERVERPASSWORD}
+    depends_on:
+      - mumble-server
+      - auth_mysql
+    logging:
+      driver: "json-file"
+      options:
+        max-size: "10Mb"
+        max-file: "5"
+```
+
+## Permissions
+
+To use this service, users will require some of the following.
+
+```{eval-rst}
++---------------------------------------+------------------+--------------------------------------------------------------------------+
+| Permission                            | Admin Site       | Auth Site                                                                |
++=======================================+==================+==========================================================================+
+| mumble.access_mumble                  | None             | Can Access the Mumble Service                                            |
++---------------------------------------+------------------+--------------------------------------------------------------------------+
+```
+
+## ACL configuration
+
+On a freshly installed mumble server only your superuser has the right to configure ACLs and create channels. The credentials for logging in with your superuser are:
+
+- user: `SuperUser`
+- password: *what you defined when configuring your mumble server*
+
+## Optimizing a Mumble Server
+
+The needs and available resources will vary between Alliance Auth installations. Consider yours when applying these settings.
+
+### Bandwidth
+
+<https://wiki.mumble.info/wiki/Murmur.ini#bandwidth>
+This is likely the most important setting for scaling a Mumble install, The default maximum Bandwidth is 72000bps Per User. Reducing this value will cause your clients to automatically scale back their bandwidth transmitted, while causing a reduction in voice quality. A value thats still high may cause robotic voices or users with bad connections to drop due entirely due to network load.
+
+Please tune this value to your individual needs, the below scale may provide a rough starting point.
+72000 - Superior voice quality - Less than 50 users.
+54000 - No noticeable reduction in quality - 50+ Users or many channels with active audio.
+36000 - Mild reduction in quality - 100+ Users
+30000 - Noticeable reduction in quality but not function - 250+ Users
+
+### Forcing Opus
+
+<https://wiki.mumble.info/wiki/Murmur.ini#opusthreshold>
+A Mumble server by default, will fall back to the older CELT codec as soon as a single user connects with an old client. This will significantly reduce your audio quality and likely place higher load on your server. We *highly* reccommend setting this to Zero, to force OPUS to be used at all times. Be aware any users with Mumble clients prior to 1.2.4 (From 2013...) Will not hear any audio.
+
+Our default config sets this as follows
+
+```docker
+  mumble-authenticator:
+    environment:
+      `MUMBLE_CONFIG_opusthreshold=0`
+```
+
+### AutoBan and Rate Limiting
+
+<https://wiki.mumble.info/wiki/Murmur.ini#autobanAttempts.2C_autobanTimeframe_and_autobanTime>
+The AutoBan feature has some sensible settings by default, You may wish to tune these if your users keep locking themselves out by opening two clients by mistake, or if you are receiving unwanted attention
+
+<https://wiki.mumble.info/wiki/Murmur.ini#messagelimit_and_messageburst>
+This too, is set to a sensible configuration by default. Take note on upgrading older installs, as this may actually be set too restrictively and will rate-limit your admins accidentally, take note of the configuration in <https://github.com/mumble-voip/mumble/blob/master/scripts/murmur.ini#L156>
+
+```docker
+  mumble-authenticator:
+    environment:
+      MUMBLE_CONFIG_messagelimit=
+      MUMBLE_CONFIG_messageburst=
+      MUMBLE_CONFIG_autobanAttempts=10
+      MUMBLE_CONFIG_autobanTimeframe=120
+      MUMBLE_CONFIG_autobanTime=30
+      MUMBLE_CONFIG_autobanSuccessfulConnections=false
+```
+
+### "Suggest" Options
+
+There is no way to force your users to update their clients or use Push to Talk, but these options will throw an error into their Mumble Client.
+
+<https://wiki.mumble.info/wiki/Murmur.ini#Miscellany>
+
+We suggest using Mumble 1.4.0+ for your server and Clients, you can tune this to the latest Patch version.
+If Push to Talk is to your tastes, configure the suggestion as follows
+
+```docker
+  mumble-authenticator:
+    environment:
+      MUMBLE_CONFIG_suggestVersion=s1.4.287
+      MUMBLE_CONFIG_suggestPushToTalk=true
+
+```
+
+## General notes
+
+### Server password
+
+With the default Mumble configuration your mumble server is public. Meaning that everyone who has the address can at least connect to it and might also be able join all channels that don't have any permissions set (Depending on your ACL configured for the root channel).
+
+We have changed this behaviour by setting a Server Password by default, to change this password modify `MUMBLE_SERVERPASSWORD` in `.env`.
+
+Restart the container to apply the change.
+
+```shell
+docker compose restart mumble-server
+```
+
+It is not reccommended to share/use this password, instead use the Mumble Authenticator whenever possible.
+
+As only registered member can join your mumble server. If you still want to allow guests to join you have 2 options.
+
+- Allow the "Guest" state to activate the Mumble service in your Auth instance
+- Use [Mumble temporary links](https://github.com/pvyParts/allianceauth-mumble-temp)
+
+### Enabling Avatars in Overlay (V1.0.0+)
+
+Ensure you have an up to date Mumble-Authenticator, this feature was added in V1.0.0
+
+Edit `authenticator.ini` and change (or add for older installs) This code block.
+
+```ini
+;If enabled, textures are automatically set as player's EvE avatar for use on overlay.
+avatar_enable = True
+;Get EvE avatar images from this location. {charid} will be filled in.
+ccp_avatar_url = https://images.evetech.net/characters/{charid}/portrait?size=32
+```

docs/features/services/mumble.md

@@ -9,7 +9,8 @@ Note that this guide assumes that you have installed Auth with the official :doc
 :::{warning}
 This guide is currently for Ubuntu only.
 :::
-## Installations
+
+## Bare Metal Installations
 
 ### Installing Mumble Server
 
@@ -35,7 +36,6 @@ sudo apt-get install python-software-properties mumble-server libqt5sql5-mysql
 :::
 ::::
 
-
 ### Installing Mumble Authenticator
 
 Next, we need to download the latest authenticator release from the [authenticator repository](https://gitlab.com/allianceauth/mumble-authenticator).
@@ -236,7 +236,7 @@ Please tune this value to your individual needs, the below scale may provide a r
 ### Forcing Opus
 
 <https://wiki.mumble.info/wiki/Murmur.ini#opusthreshold>
-A Mumble server, by default, will fall back to the older CELT codec as soon as a single user connects with an old client. This will significantly reduce your audio quality and likely place a higher load on your server. We _highly_ reccommend setting this to Zero, to force OPUS to be used at all times. Be aware any users with Mumble clients prior to 1.2.4 (From 2013...) Will not hear any audio.
+A Mumble server, by default, will fall back to the older CELT codec as soon as a single user connects with an old client. This will significantly reduce your audio quality and likely place a higher load on your server. We *highly* recommend setting this to Zero, to force OPUS to be used at all times. Be aware any users with Mumble clients prior to 1.2.4 (From 2013...) Will not hear any audio.
 
 `opusthreshold=0`
 
@@ -255,7 +255,7 @@ There is no way to force your users to update their clients or use Push to Talk,
 <https://wiki.mumble.info/wiki/Murmur.ini#Miscellany>
 
 We suggest using Mumble 1.4.0+ for your server and Clients, you can tune this to the latest Patch version.
-`suggestVersion=1.4.230`
+`suggestVersion=1.4.287`
 
 If Push to Talk is to your tastes, configure the suggestion as follows
 `suggestPushToTalk=true`

docs/features/services/openfire-docker.md

@@ -0,0 +1,180 @@
+# Openfire
+
+An alternate install guide for Openfire using Docker, better suited to an Alliance Auth Docker install
+
+Openfire is a Jabber (XMPP) server.
+
+## Configuring Auth
+
+In your auth project's settings file (`aa-docker/conf/local.py`), do the following:
+
+- 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 = SITE_URL
+JABBER_PORT = os.environ.get('JABBER_PORT', 5223)
+JABBER_SERVER = SITE_URL
+OPENFIRE_ADDRESS = SITE_URL
+OPENFIRE_SECRET_KEY = os.environ.get('OPENFIRE_SECRET_KEY', '')
+BROADCAST_USER = ""
+BROADCAST_USER_PASSWORD = os.environ.get('BROADCAST_USER_PASSWORD', '127.0.0.1')
+BROADCAST_SERVICE_NAME = "broadcast"
+```
+
+Add the following lines to your `.env` file
+
+```env
+# Openfire
+OPENFIRE_SECRET_KEY = superuser_password
+BROADCAST_USER_PASSWORD = icesecretwrite
+
+```
+
+Finally, restart your stack and run migrations
+
+```shell
+docker compose --env-file=.env up -d
+docker compose exec allianceauth_gunicorn bash
+auth migrate
+```
+
+## Docker Installation
+
+Add the following to your `docker-compose.yml` under the `services:` section
+
+```docker
+  openfire:
+    image: nasqueron/openfire:4.7.5
+    ports:
+      - "5222:5222/tcp"
+      - "5223:5223/tcp"
+      - "7777:7777/tcp"
+    volumes:
+      - openfire-data:/var/lib/openfire
+    depends_on:
+    - auth_mysql
+  logging:
+    driver: "json-file"
+    options:
+      max-size: "50Mb"
+      max-file: "5"
+```
+
+### Create Database
+
+We have a Mariadb container already as part of the Alliance Auth stack, enter it and create a database for it.
+
+```shell
+docker exec -it auth_mysql
+mysql -u root -p $AA_DB_ROOT_PASSWORD
+```
+
+```sql
+create database alliance_jabber;
+grant all privileges on alliance_jabber . * to 'aauth'@'localhost';
+exit;
+exit
+```
+
+### Configure Webserver
+
+In Nginx Proxy Manager `http://yourdomain:81/`, go to `Proxy Hosts`, Click `Add Proxy Host`. You can refer to :doc:`/installation-containerized/docker`
+
+Domain Name: `jabber.yourdomain`
+Forward Hostname `openfire`
+forward port `9090` for http, `9091` for https
+
+### Web Configuration
+
+The remainder of the setup occurs through Openfire’s web interface. Navigate to <http://jabber.yourdomain.com>
+
+Select your language, our guide will assume English
+
+Under Server Settings, set the Domain to `jabber.yourdomain.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]`: `auth_mysql`
+- `[database]`: `alliance_jabber`
+- `[user]`: `aauth`
+- `[password]`: Your database users password
+
+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 (`aa-docker/conf/local.py`) 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 `jabber.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 and Nginx Proxy Manager
+
+### 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.
+
+## Permissions
+
+To use this service, users will require some of the following.
+
+```{eval-rst}
++---------------------------------------+------------------+--------------------------------------------------------------------------+
+| Permission                            | Admin Site       | Auth Site                                                                |
++=======================================+==================+==========================================================================+
+| openfire.access_openfire              | None             | Can Access the Openfire Service                                          |
++---------------------------------------+------------------+--------------------------------------------------------------------------+
+```

docs/features/services/teamspeak3-docker.md

@@ -0,0 +1,179 @@
+# 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.
+
+## Configuring Auth
+
+In your auth project's settings file (`aa-docker/conf/local.py`), do the following:
+
+- Add `'allianceauth.services.modules.teamspeak',` to your `INSTALLED_APPS` list
+- Append the following to your auth project's settings file:
+
+```python
+# Teamspeak3 Configuration
+TEAMSPEAK3_SERVER_IP = os.environ.get('TEAMSPEAK3_SERVER_IP', '127.0.0.1')
+TEAMSPEAK3_SERVER_PORT = os.environ.get('TEAMSPEAK3_SERVER_PORT', 10011)
+TEAMSPEAK3_SERVERQUERY_USER = os.environ.get('TEAMSPEAK3_SERVERQUERY_USER', "serverquery")
+TEAMSPEAK3_SERVERQUERY_PASSWORD = os.environ.get('TEAMSPEAK3_SERVERQUERY_PASSWORD', "")
+TEAMSPEAK3_VIRTUAL_SERVER = os.environ.get('TEAMSPEAK3_VIRTUAL_SERVER', 1)
+TEAMSPEAK3_PUBLIC_URL = SITE_URL
+
+CELERYBEAT_SCHEDULE['run_ts3_group_update'] = {
+    'task': 'allianceauth.services.modules.teamspeak3.tasks.run_ts3_group_update',"
+    'schedule': crontab(minute='*/30'),
+}
+```
+
+Add the following lines to your `.env` file
+
+```env
+# Temspeak
+TEAMSPEAK3_SERVERQUERY_USER = "serverquery"
+TEAMSPEAK3_SERVERQUERY_PASSWORD = ""
+```
+
+## Docker Installation
+
+Add the following to your `docker-compose.yml` under the `services:` section
+
+```docker
+  teamspeak:
+    image: teamspeak:3.13
+    restart: always
+    environment:
+      TS3SERVER_LICENSE: accept
+    ports:
+      - 9987:9987/udp
+      - 30033:30033
+    volumes:
+      - teamspeak-data:/var/ts3server/
+    logging:
+      driver: "json-file"
+      options:
+        max-size: "10Mb"
+        max-file: "5"
+```
+
+### Update Settings
+
+In (`aa-docker/conf/local.py`), update the following
+
+- `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://
+
+In your `.env` file, update the following, obtained from the logs of the Teamspeak server initaliztion `docker compose logs teamspeak`
+
+- `TEAMSPEAK3_SERVERQUERY_USER` is `loginname` from the above bash command (usually `serveradmin`)
+- `TEAMSPEAK3_SERVERQUERY_PASSWORD` is `password` following the equals in `serveradmin_password=`
+
+Once settings are entered, run migrations and restart your stack
+
+```shell
+docker compose --env-file=.env up -d
+docker compose exec allianceauth_gunicorn bash
+auth migrate
+```
+
+### 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 `Teamspeak3`, select `Auth / TS Groups`.
+
+In the top-right corner click, first click on `Update TS3 Groups` to fetch the newly created server groups from TS3 (this may take a minute to complete). Then click on `Add Auth / TS Group` to link Auth groups with TS3 server groups.
+
+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 you start the process from the admin site or from the Django shell.
+
+#### Admin Site
+
+Navigate to the AllianceAuth admin interface and under `Teamspeak3`, select `Auth / TS Groups`.
+
+Then, in the top-right corner click, click on `Update TS3 Groups` to start the process of fetching the server groups from TS3 (this may take a minute to complete).
+
+#### Django Shell
+
+Start a django shell with:
+
+```shell
+docker compose exec allianceauth_gunicorn bash
+auth shell
+```
+
+And execute the update as follows:
+
+```python
+from allianceauth.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  `query_ip_allowlist.txt` (named `query_ip_whitelist.txt` on older teamspeak versions).
+
+### `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.
+
+## Permissions
+
+To use and configure this service, users will require some of the following.
+
+```{eval-rst}
++---------------------------------------+------------------+--------------------------------------------------------------------------+
+| Permission                            | Admin Site       | Auth Site                                                                |
++=======================================+==================+==========================================================================+
+| teamspeak.access_teamspeak            | None             | Can Access the TeamSpeak Service                                         |
++---------------------------------------+------------------+--------------------------------------------------------------------------+
+| teamspeak.add_authts                  | Can Add Model    | None                                                                     |
++---------------------------------------+------------------+--------------------------------------------------------------------------+
+| teamspeak.change_authts               | Can Change Model | None                                                                     |
++---------------------------------------+------------------+--------------------------------------------------------------------------+
+| teamspeak.delete_authts               | Can Delete Model | None                                                                     |
++---------------------------------------+------------------+--------------------------------------------------------------------------+
+| teamspeak.view_authts                 | Can View Model   | None                                                                     |
++---------------------------------------+------------------+--------------------------------------------------------------------------+
+```

docs/installation-containerized/docker.md

@@ -8,13 +8,17 @@ You should have the following available on the system you are using to set this
 * git
 * curl
 
+:::{hint}
+If at any point `docker compose` does not work, but `docker-compose` does, you have an older version of Docker (and Compose), please update before continuing. Be cautious of these two commands and any suggestions copy and pasted from the internet
+:::
+
 ## Setup Guide
 
 1. run `bash <(curl -s https://gitlab.com/allianceauth/allianceauth/-/raw/master/docker/scripts/download.sh)`. This will download all the files you need to install Alliance Auth and place them in a directory named `aa-docker`. Feel free to rename/move this folder.
 1. run `./scripts/prepare-env.sh` to set up your environment
 1. (optional) Change `PROTOCOL` to `http://` if not using SSL in `.env`
-1. run `docker-compose --env-file=.env up -d` (NOTE: if this command hangs, follow the instructions [here](https://www.digitalocean.com/community/tutorials/how-to-setup-additional-entropy-for-cloud-servers-using-haveged))
+1. run `docker compose --env-file=.env up -d` (NOTE: if this command hangs, follow the instructions [here](https://www.digitalocean.com/community/tutorials/how-to-setup-additional-entropy-for-cloud-servers-using-haveged))
-1. run `docker-compose exec allianceauth bash` to open up a terminal inside your auth container
+1. run `docker compose exec allianceauth_gunicorn bash` to open up a terminal inside an auth container
 1. run `auth migrate`
 1. run `auth collectstatic`
 1. run `auth createsuperuser`
@@ -24,7 +28,7 @@ You should have the following available on the system you are using to set this
 1. click "Add Proxy Host", with the following settings for auth. The example uses `auth.localhost` for the domain, but you'll want to use whatever address you have auth configured on
   ![nginx-host](/_static/images/installation/docker/nginx-host.png)
 1. click "Add Proxy Host", with the following settings for grafana. The example uses `grafana.localhost` for the domain
-  ![grafana-host](/_static/images/installation/docker/grafana-host.png))
+  ![grafana-host](/_static/images/installation/docker/grafana-host.png)
 
 Congrats! You should now see auth running at <http://auth.yourdomain> and grafana at <http://grafana.yourdomain>!
 
@@ -46,7 +50,7 @@ That's it! You should now be able to access your auth install at <https://auth.y
 
 There are a handful of ways to add packages:
 
-* Running `pip install` in the container
+* Running `pip install` in the containers
 * Modifying the container's initial command to install packages
 * Building a custom Docker image (recommended, and less scary than it sounds!)
 
@@ -55,9 +59,25 @@ There are a handful of ways to add packages:
 Using a custom docker image is the preferred approach, as it gives you the stability of packages only changing when you tell them to, along with packages not having to be downloaded every time your container restarts
 
 1. Add each additional package that you want to install to a single line in `conf/requirements.txt`. It is recommended, but not required, that you include a version number as well. This will keep your packages from magically updating. You can lookup packages on <https://package.wiki>, and copy everything after `pip install` from the top of the page to use the most recent version. It should look something like `allianceauth-signal-pings==0.0.7`. Every entry in this file should be on a separate line
-1. In `docker-compose.yml`, comment out the `image` line under `allianceauth` (line 36... ish) and uncomment the `build` section
+1. Modify `docker-compose.yml`, as follows.
-1. run `docker-compose --env-file=.env up -d`, your custom container will be built, and auth will have your new packages. Make sure to follow the package's instructions on config values that go in `local.py`
+    * Comment out the `image` line under `allianceauth`
-1. run `docker-compose exec allianceauth_gunicorn bash` to open up a terminal inside your auth container
+    * Uncomment the `build` section
+    * e.g.
+
+    ```docker
+      x-allianceauth-base: &allianceauth-base
+      # image: ${AA_DOCKER_TAG?err}
+      build:
+        context: .
+        dockerfile: custom.dockerfile
+        args:
+          AA_DOCKER_TAG: ${AA_DOCKER_TAG?err}
+      restart: always
+    ...
+    ```
+
+1. run `docker compose --env-file=.env up -d`, your custom container will be built, and auth will have your new packages. Make sure to follow the package's instructions on config values that go in `local.py`
+1. run `docker compose exec allianceauth_gunicorn bash` to open up a terminal inside your auth container
 1. run `allianceauth update myauth`
 1. run `auth migrate`
 1. run `auth collectstatic`
@@ -71,9 +91,9 @@ _NOTE: It is recommended that you put any secret values (API keys, database cred
 Whether you're using a custom image or not, the version of auth is dictated by $AA_DOCKER_TAG in your `.env` file.
 
 1. To update to a new version of auth, update the version number at the end (or replace the whole value with the tag in the release notes).
-1. run `docker-compose pull`
+1. run `docker compose pull`
-1. run `docker-compose --env-file=.env up -d`
+1. run `docker compose --env-file=.env up -d`
-1. run `docker-compose exec allianceauth bash` to open up a terminal inside your auth container
+1. run `docker compose exec allianceauth_gunicorn bash` to open up a terminal inside your auth container
 1. run `allianceauth update myauth`
 1. run `auth migrate`
 1. run `auth collectstatic`
@@ -83,5 +103,5 @@ _NOTE: If you specify a version of allianceauth in your `requirements.txt` in a
 ### Custom Packages
 
 1. Update the versions in your `requirements.txt` file
-1. Run `docker-compose build`
+1. Run `docker compose build`
-1. Run `docker-compose --env-file=.env up -d`
+1. Run `docker compose --env-file=.env up -d`

docs/installation-containerized/index.md

@@ -10,5 +10,7 @@ There are additional installation steps for activating services and apps that co
 
 :::{toctree}
 :maxdepth: 1
+
 docker
+v4_docker_migration
 :::

docs/installation-containerized/v4_docker_migration.md

@@ -0,0 +1,118 @@
+# Migrating your Docker Compose stack from AA V3.x to AA v4.x
+
+Our Docker Compose stack has both changed significantly, and simplified itself drastically depending on your level of familiarity with Docker.
+
+We have Removed our need to run Supervisor inside the container to run the various tasks needed, and split the stack into multiple containers responsible for each task, as well as modernized many elements.
+
+## aa-docker/conf/*
+
+We are bundling a few often customized files along side our AA install for easier modification by users, you will need to download these into aa-docker/conf
+
+```shell
+wget https://gitlab.com/allianceauth/allianceauth/-/raw/v4.x/docker/conf/celery.py
+wget https://gitlab.com/allianceauth/allianceauth/-/raw/v4.x/docker/conf/urls.py
+wget https://gitlab.com/allianceauth/allianceauth/-/raw/v4.x/docker/conf/memory_check.sh
+wget https://gitlab.com/allianceauth/allianceauth/-/raw/v4.x/docker/conf/redis_healthcheck.sh
+```
+
+## Docker Compose
+
+At this point you should take a copy of your docker-compose and take note of any additional volumes or configurations you have, and why.
+
+Take a complete backup of your local.py, docker-compose and SQL database.
+
+`docker compose down`
+
+Replace your conf/nginx.conf with the contents of <https://gitlab.com/allianceauth/allianceauth/-/blob/v4.x/docker/conf/nginx.conf>
+
+Replace your docker-compose.yml with the contents of <https://gitlab.com/allianceauth/allianceauth/-/raw/v4.x/docker/docker-compose.yml>
+
+V3.x installs likely used a dedicated database for Nginx Proxy Manager, you can either setup NPM again without a database, or uncomment the sections noted to maintain this configuration
+
+```docker-compose
+  proxy:
+  ...
+    # Uncomment this section to use a dedicated database for Nginx Proxy Manager
+    environment:
+      DB_MYSQL_HOST: "proxy-db"
+      DB_MYSQL_PORT: 3306
+      DB_MYSQL_USER: "npm"
+      DB_MYSQL_PASSWORD: "${PROXY_MYSQL_PASS?err}"
+      DB_MYSQL_NAME: "npm"
+  ...
+  # Uncomment this section to use a dedicated database for Nginx Proxy Manager
+  proxy-db:
+    image: 'jc21/mariadb-aria:latest'
+    restart: always
+    environment:
+      MYSQL_ROOT_PASSWORD: "${PROXY_MYSQL_PASS_ROOT?err}"
+      MYSQL_DATABASE: 'npm'
+      MYSQL_USER: 'npm'
+      MYSQL_PASSWORD: "${PROXY_MYSQL_PASS?err}"
+    ports:
+      - 3306
+    volumes:
+      - proxy-db:/var/lib/mysql
+    logging:
+      driver: "json-file"
+      options:
+        max-size: "1Mb"
+        max-file: "5"
+```
+
+## .env
+
+You will need to add some entries to your .env file
+
+```env
+AA_DB_CHARSET=utf8mb4
+GF_SECURITY_ADMIN_USERNAME=admin
+```
+
+and
+`GF_SECURITY_ADMIN_PASSWORD`
+
+The password field is intentionally not filled so that you create one. You can either use the grafana credentials you have been using, or create a suitably secure password now.
+
+You will also need to update the `AA_DOCKER_TAG` to the version of V4.x you want to install. Either follow the pattern or check <https://gitlab.com/allianceauth/allianceauth/-/releases>
+
+## (Optional) Build Custom Container
+
+If you are using a docker container with a requirements.txt, You will need to reinstate some customizations.
+
+Modify `docker-compose.yml`, as follows.
+
+* Comment out the `image` line under `allianceauth`
+* Uncomment the `build` section
+* e.g.
+
+  ```docker
+    x-allianceauth-base: &allianceauth-base
+    # image: ${AA_DOCKER_TAG?err}
+    build:
+      context: .
+      dockerfile: custom.dockerfile
+      args:
+        AA_DOCKER_TAG: ${AA_DOCKER_TAG?err}
+    restart: always
+  ...
+  ```
+
+Now build your custom image
+
+```shell
+docker compose pull
+docker compose build
+```
+
+## Bring docker back up, migrate, collect static
+
+```shell
+docker compose --env-file=.env up -d --remove-orphans
+
+docker compose exec allianceauth_gunicorn bash
+
+allianceauth update myauth
+auth migrate
+auth collectstatic --clear
+```

docs/installation/allianceauth.md

@@ -85,9 +85,9 @@ We need to build Python from source
 ```bash
 cd ~
 sudo yum install gcc openssl-devel bzip2-devel libffi-devel wget
-wget https://www.python.org/ftp/python/3.11.5/Python-3.11.5.tgz
+wget https://www.python.org/ftp/python/3.11.7/Python-3.11.7.tgz
-tar xvf Python-3.11.5.tgz
+tar xvf Python-3.11.7.tgz
-cd Python-3.11.5/
+cd Python-3.11.7/
 ./configure --enable-optimizations --enable-shared
 sudo make altinstall
 ```
@@ -99,9 +99,9 @@ We need to build Python from source
 ```bash
 cd ~
 sudo yum install gcc openssl-devel bzip2-devel libffi-devel wget
-wget https://www.python.org/ftp/python/3.11.5/Python-3.11.5.tgz
+wget https://www.python.org/ftp/python/3.11.7/Python-3.11.7.tgz
-tar xvf Python-3.11.5.tgz
+tar xvf Python-3.11.7.tgz
-cd Python-3.11.5/
+cd Python-3.11.7/
 ./configure --enable-optimizations --enable-shared
 sudo make altinstall
 ```
@@ -113,9 +113,9 @@ We need to build Python from source
 ```bash
 cd ~
 sudo yum install gcc openssl-devel bzip2-devel libffi-devel wget
-wget https://www.python.org/ftp/python/3.11.5/Python-3.11.5.tgz
+wget https://www.python.org/ftp/python/3.11.7/Python-3.11.7.tgz
-tar xvf Python-3.11.5.tgz
+tar xvf Python-3.11.7.tgz
-cd Python-3.11.5/
+cd Python-3.11.7/
 ./configure --enable-optimizations --enable-shared
 sudo make altinstall
 ```

docs/installation/upgrade_python.md

@@ -15,7 +15,7 @@ To run AA with a newer Python 3 version than your system's default, you need to
 To install other Python versions than those included with your distribution, you need to add a new installation repository. Then you can install the specific Python 3 to your system.
 
 :::{note}
-    Ubuntu 2204 ships with Python 3.10 already
+Ubuntu 2204 ships with Python 3.10 already
 :::
 
 Centos Stream 8/9:
@@ -39,9 +39,9 @@ sudo apt-get install python3.11 python3.11-dev python3.11-venv
 ```bash
 cd ~
 sudo yum install gcc openssl-devel bzip2-devel libffi-devel wget
-wget https://www.python.org/ftp/python/3.11.5/Python-3.11.5.tgz
+wget https://www.python.org/ftp/python/3.11.7/Python-3.11.7.tgz
-tar xvf Python-3.11.5.tgz
+tar xvf Python-3.11.7.tgz
-cd Python-3.11.5/
+cd Python-3.11.7/
 ./configure --enable-optimizations --enable-shared
 sudo make altinstall
 ```
@@ -52,9 +52,9 @@ sudo make altinstall
 ```bash
 cd ~
 sudo yum install gcc openssl-devel bzip2-devel libffi-devel wget
-wget https://www.python.org/ftp/python/3.11.5/Python-3.11.5.tgz
+wget https://www.python.org/ftp/python/3.11.7/Python-3.11.7.tgz
-tar xvf Python-3.11.5.tgz
+tar xvf Python-3.11.7.tgz
-cd Python-3.11.5/
+cd Python-3.11.7/
 ./configure --enable-optimizations --enable-shared
 sudo make altinstall
 ```
@@ -65,9 +65,9 @@ sudo make altinstall
 ```bash
 cd ~
 sudo yum install gcc openssl-devel bzip2-devel libffi-devel wget
-wget https://www.python.org/ftp/python/3.11.5/Python-3.11.5.tgz
+wget https://www.python.org/ftp/python/3.11.7/Python-3.11.7.tgz
-tar xvf Python-3.11.5.tgz
+tar xvf Python-3.11.7.tgz
-cd Python-3.11.5/
+cd Python-3.11.7/
 ./configure --enable-optimizations --enable-shared
 sudo make altinstall
 ```