mirror of
https://gitlab.com/allianceauth/allianceauth.git
synced 2025-07-09 04:20:17 +02:00
find and replace fixes, will introduce errors
This commit is contained in:
Ariel Rin
parent
b9d128259e
commit
ffb526ab0c
@ -2,7 +2,7 @@
|
||||
|
||||
It is possible to customize your **Alliance Auth** instance.
|
||||
|
||||
```eval_rst
|
||||
```{eval-rst}
|
||||
.. warning::
|
||||
Keep in mind that you may need to update some of your customizations manually after new Auth releases (e.g. when replacing templates).
|
||||
```
|
||||
@ -82,7 +82,7 @@ First you need to create the folder for the template on your server. For AA to p
|
||||
|
||||
If you have a default installation you can create the folder like this:
|
||||
|
||||
```sh
|
||||
```shell
|
||||
mkdir -p /home/allianceserver/myauth/myauth/templates/allianceauth
|
||||
```
|
||||
|
||||
@ -90,7 +90,7 @@ mkdir -p /home/allianceserver/myauth/myauth/templates/allianceauth
|
||||
|
||||
Next you need to download a copy of the original template file we want to change. For that let's move into the above folder and then download the file into the current folder with:
|
||||
|
||||
```sh
|
||||
```shell
|
||||
cd /home/allianceserver/myauth/myauth/templates/allianceauth
|
||||
wget <https://gitlab.com/allianceauth/allianceauth/-/raw/master/allianceauth/templates/allianceauth/side-menu.html>
|
||||
```
|
||||
@ -99,11 +99,11 @@ wget <https://gitlab.com/allianceauth/allianceauth/-/raw/master/allianceauth/tem
|
||||
|
||||
Now you can modify the template to add your custom link. To create the google link we can add this snippet *between* the `{% menu_items %}` and the `</ul>` tag:
|
||||
|
||||
```sh
|
||||
```shell
|
||||
nano /home/allianceserver/myauth/myauth/templates/allianceauth/side-menu.html
|
||||
```
|
||||
|
||||
```jinja
|
||||
```django
|
||||
<li>
|
||||
<a href="https://www.google.com/" target="_blank">
|
||||
<i class="fab fa-google fa-fw"></i>Google
|
||||
@ -111,7 +111,7 @@ nano /home/allianceserver/myauth/myauth/templates/allianceauth/side-menu.html
|
||||
</li>
|
||||
```
|
||||
|
||||
```eval_rst
|
||||
```{eval-rst}
|
||||
.. hint::
|
||||
You can find other icons with a matching style on the `Font Awesome site <https://fontawesome.com/v5/search?m=free>`_ . AA currently uses Font Awesome version 5. You also want to keep the ``fa-fw`` tag to ensure all icons have the same width.
|
||||
```
|
||||
|
||||
@ -4,13 +4,13 @@ The documentation for Alliance Auth uses [Sphinx](http://www.sphinx-doc.org/) to
|
||||
to specific branches is made (master, primarily), the repository is automatically pulled, docs built and deployed on
|
||||
[readthedocs.org](https://readthedocs.org/).
|
||||
|
||||
|
||||
Documentation was migrated from the GitHub wiki pages and into the repository to allow documentation changes to be
|
||||
included with pull requests. This means that documentation can be guaranteed to be updated when a pull request is
|
||||
accepted rather than hoping documentation is updated afterwards or relying on maintainers to do the work. It also
|
||||
allows for documentation to be maintained at different versions more easily.
|
||||
|
||||
## Building Documentation
|
||||
|
||||
If you're developing new documentation, its likely you'll want or need to test build it before committing to your
|
||||
branch. To achieve this you can use Sphinx to build the documentation locally as it appears on Read the Docs.
|
||||
|
||||
@ -24,15 +24,16 @@ build in the `/docs/_build/` directory.
|
||||
Occasionally you may need to fully rebuild the documents by running `make clean` first, usually when you add or
|
||||
rearrange toctrees.
|
||||
|
||||
|
||||
## Documentation Format
|
||||
|
||||
CommonMark Markdown is the current preferred format, via [recommonmark](https://github.com/rtfd/recommonmark).
|
||||
reStructuredText is supported if required, or you can execute snippets of reST inside Markdown by using a code block:
|
||||
CommonMark-plus Markdown is the current preferred format, via [MyST-Parser](https://github.com/executablebooks/MyST-Parser).
|
||||
reStructuredText is supported if required, or you can execute snippets of MyST inside Markdown by using a code block:
|
||||
|
||||
```eval_rst
|
||||
reStructuredText here
|
||||
```
|
||||
````md
|
||||
```{eval-rst}
|
||||
reStructuredText here
|
||||
```
|
||||
````
|
||||
|
||||
Markdown is used elsewhere on Github so it provides the most portability of documentation from Issues and Pull Requests
|
||||
as well as providing an easier initial migration path from the Github wiki.
|
||||
|
||||
@ -2,10 +2,9 @@
|
||||
|
||||
This section contains important information on how to develop Alliance Auth itself.
|
||||
|
||||
```eval_rst
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
```{toctree}
|
||||
:maxdepth: 1
|
||||
|
||||
documentation
|
||||
code-style
|
||||
documentation
|
||||
code-style
|
||||
```
|
||||
|
||||
@ -2,12 +2,11 @@
|
||||
|
||||
This section describes how to extend **Alliance Auth** with custom apps and services.
|
||||
|
||||
```eval_rst
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
```{toctree}
|
||||
:maxdepth: 1
|
||||
|
||||
integrating-services
|
||||
menu-hooks
|
||||
url-hooks
|
||||
logging
|
||||
integrating-services
|
||||
menu-hooks
|
||||
url-hooks
|
||||
logging
|
||||
```
|
||||
|
||||
@ -46,7 +46,7 @@ In order to integrate with Alliance Auth service modules must provide a `service
|
||||
|
||||
This would register the ExampleService class which would need to be a subclass of `services.hooks.ServiceHook`.
|
||||
|
||||
```eval_rst
|
||||
```{eval-rst}
|
||||
.. important::
|
||||
The hook **MUST** be registered in ``yourservice.auth_hooks`` along with any other hooks you are registering for Alliance Auth.
|
||||
```
|
||||
|
||||
@ -40,7 +40,7 @@ A list of views or namespaces the link should be highlighted on. See [django-nav
|
||||
|
||||
This is a great feature to signal the user, that he has some open issues to take care of within an app. For example Auth uses this feature to show the specific number of open group request to the current user.
|
||||
|
||||
```eval_rst
|
||||
```{eval-rst}
|
||||
.. hint::
|
||||
Here is how to stay consistent with the Auth design philosophy for using this feature:
|
||||
1. Use it to display open items that the current user can close by himself only. Do not use it for items, that the user has no control over.
|
||||
|
||||
@ -18,8 +18,7 @@ In addition is it possible to make views public. Normally, all views are automat
|
||||
|
||||
An app can opt-out of this feature by adding a list of views to be excluded when registering the URLs. See the `excluded_views` parameter for details.
|
||||
|
||||
```eval_rst
|
||||
.. note::
|
||||
:::{note}
|
||||
Note that for a public view to work, administrators need to also explicitly allow apps to have public views in their AA installation, by adding the apps label to ``APPS_WITH_PUBLIC_VIEWS`` setting.
|
||||
```
|
||||
|
||||
@ -59,7 +58,7 @@ When this app is included in the project's `settings.INSTALLED_APPS` users would
|
||||
|
||||
## API
|
||||
|
||||
```eval_rst
|
||||
```{eval-rst}
|
||||
.. autoclass:: allianceauth.services.hooks.UrlHook
|
||||
:members:
|
||||
```
|
||||
|
||||
@ -6,7 +6,7 @@ The main benefit of this setup is that it runs all services and code in the nati
|
||||
|
||||
In addition all tools described in this guide are open source or free software.
|
||||
|
||||
```eval_rst
|
||||
```{eval-rst}
|
||||
.. hint::
|
||||
This guide is meant for development purposes only and not for installing AA in a production environment. For production installation please see chapter **Installation**.
|
||||
```
|
||||
@ -25,8 +25,7 @@ The development environment consists of the following components:
|
||||
|
||||
We will use the build-in Django development web server, so we don't need to setup a WSGI server or a web server.
|
||||
|
||||
```eval_rst
|
||||
.. note::
|
||||
:::{note}
|
||||
This setup works with both WSL 1 and WSL 2. However, due to the significantly better performance we recommend WSL 2.
|
||||
```
|
||||
|
||||
@ -58,13 +57,13 @@ The only requirement is a PC with Windows 10 and Internet connection in order to
|
||||
|
||||
Open a WSL bash and update all software packets:
|
||||
|
||||
```bash
|
||||
```shell
|
||||
sudo apt update && sudo apt upgrade -y
|
||||
```
|
||||
|
||||
### Install Tools
|
||||
|
||||
```bash
|
||||
```shell
|
||||
sudo apt-get install build-essential
|
||||
sudo apt-get install gettext
|
||||
```
|
||||
@ -73,13 +72,12 @@ sudo apt-get install gettext
|
||||
|
||||
Next we need to install Python and related development tools.
|
||||
|
||||
```eval_rst
|
||||
```{eval-rst}
|
||||
.. hint::
|
||||
To check your system's Python 3 version you can enter: ``python3 --version``
|
||||
```
|
||||
|
||||
```eval_rst
|
||||
.. note::
|
||||
:::{note}
|
||||
Should your Ubuntu come with a newer version of Python we recommend to still setup your dev environment with the oldest Python 3 version currently supported by AA (e.g Python 3.8 at this time of writing) to ensure your apps are compatible with all current AA installations
|
||||
You an check out this `page <https://askubuntu.com/questions/682869/how-do-i-install-a-different-python-version-using-apt-get/1195153>`_ on how to install additional Python versions on Ubuntu.
|
||||
|
||||
@ -90,19 +88,19 @@ Next we need to install Python and related development tools.
|
||||
|
||||
Use the following command to install Python 3 with all required libraries with the default version:
|
||||
|
||||
```bash
|
||||
```shell
|
||||
sudo apt-get install python3 python3-dev python3-venv python3-setuptools python3-pip python-pip
|
||||
```
|
||||
|
||||
### Install redis and other tools
|
||||
|
||||
```bash
|
||||
```shell
|
||||
sudo apt-get install unzip git redis-server curl libssl-dev libbz2-dev libffi-dev pkg-config
|
||||
```
|
||||
|
||||
Start redis
|
||||
|
||||
```bash
|
||||
```shell
|
||||
sudo redis-server --daemonize yes
|
||||
```
|
||||
|
||||
@ -110,30 +108,29 @@ sudo redis-server --daemonize yes
|
||||
|
||||
Install MySQL and required libraries with the following command:
|
||||
|
||||
```bash
|
||||
```shell
|
||||
sudo apt-get install mysql-server mysql-client libmysqlclient-dev
|
||||
```
|
||||
|
||||
```eval_rst
|
||||
.. note::
|
||||
:::{note}
|
||||
We chose to use MySQL instead of MariaDB, because the standard version of MariaDB that comes with this Ubuntu distribution will not work with AA.
|
||||
```
|
||||
|
||||
We need to apply a permission fix to mysql or you will get a warning with every startup:
|
||||
|
||||
```bash
|
||||
```shell
|
||||
sudo usermod -d /var/lib/mysql/ mysql
|
||||
```
|
||||
|
||||
Start the mysql server
|
||||
|
||||
```bash
|
||||
```shell
|
||||
sudo service mysql start
|
||||
```
|
||||
|
||||
Create database and user for AA
|
||||
|
||||
```bash
|
||||
```shell
|
||||
sudo mysql -u root
|
||||
```
|
||||
|
||||
@ -147,12 +144,11 @@ exit;
|
||||
|
||||
Add timezone info to mysql:
|
||||
|
||||
```bash
|
||||
```shell
|
||||
sudo mysql_tzinfo_to_sql /usr/share/zoneinfo | sudo mysql -u root mysql
|
||||
```
|
||||
|
||||
```eval_rst
|
||||
.. note::
|
||||
:::{note}
|
||||
If your WSL does not have an init.d service, it will not automatically start your services such as MySQL and Redis when you boot your Windows machine and you have to manually start them. For convenience we recommend putting these commands in a bash script. Here is an example:
|
||||
|
||||
::
|
||||
@ -183,7 +179,7 @@ Following this approach you can also setup additional AA projects, e.g. aa-dev-2
|
||||
|
||||
Create the root folder `aa-dev`.
|
||||
|
||||
```eval_rst
|
||||
```{eval-rst}
|
||||
.. hint::
|
||||
The folders `venv` and `myauth` will be created automatically in later steps. Please do not create them manually as this would lead to errors.
|
||||
```
|
||||
@ -192,19 +188,19 @@ Create the root folder `aa-dev`.
|
||||
|
||||
Create the virtual environment. Run this in your aa-dev folder:
|
||||
|
||||
```bash
|
||||
```shell
|
||||
python3 -m venv venv
|
||||
```
|
||||
|
||||
And activate your venv:
|
||||
|
||||
```bash
|
||||
```shell
|
||||
source venv/bin/activate
|
||||
```
|
||||
|
||||
### Install and update basic Python packages
|
||||
|
||||
```bash
|
||||
```shell
|
||||
pip install -U pip setuptools wheel
|
||||
```
|
||||
|
||||
@ -212,19 +208,19 @@ pip install -U pip setuptools wheel
|
||||
|
||||
### Install and create AA instance
|
||||
|
||||
```bash
|
||||
```shell
|
||||
pip install allianceauth
|
||||
```
|
||||
|
||||
Now we are ready to setup our AA instance. Make sure to run this command in your aa-dev folder:
|
||||
|
||||
```bash
|
||||
```shell
|
||||
allianceauth start myauth
|
||||
```
|
||||
|
||||
Next we will setup our VSC project for aa-dev by starting it directly from the WSL bash:
|
||||
|
||||
```bash
|
||||
```shell
|
||||
code .
|
||||
```
|
||||
|
||||
@ -244,7 +240,7 @@ For the Eve Online related setup you need to create a SSO app on the developer s
|
||||
|
||||
Open your local Django settings with VSC. The file is under `myauth/myauth/settings/local.py`
|
||||
|
||||
```eval_rst
|
||||
```{eval-rst}
|
||||
.. hint::
|
||||
There are two Django settings files: ``base.py`` and ``local.py``. The base settings file is controlled by the AA project and may change at any time. It is therefore recommended to only change the local settings file.
|
||||
```
|
||||
@ -293,14 +289,14 @@ REGISTRATION_VERIFY_EMAIL = False
|
||||
|
||||
Before we can start AA we need to run migrations:
|
||||
|
||||
```bash
|
||||
```shell
|
||||
cd myauth
|
||||
python manage.py migrate
|
||||
```
|
||||
|
||||
We also need to create a superuser for our AA installation:
|
||||
|
||||
```bash
|
||||
```shell
|
||||
python manage.py createsuperuser
|
||||
```
|
||||
|
||||
@ -310,19 +306,18 @@ python manage.py createsuperuser
|
||||
|
||||
We are now ready to run out AA instance with the following command:
|
||||
|
||||
```bash
|
||||
```shell
|
||||
python manage.py runserver
|
||||
```
|
||||
|
||||
Once running you can access your auth site on the browser under `http://localhost:8000`. Or the admin site under `http://localhost:8000/admin`
|
||||
|
||||
```eval_rst
|
||||
```{eval-rst}
|
||||
.. hint::
|
||||
You can start your AA server directly from a terminal window in VSC or with a VSC debug config (see chapter about debugging for details).
|
||||
```
|
||||
|
||||
```eval_rst
|
||||
.. note::
|
||||
:::{note}
|
||||
**Debug vs. Non-Debug mode**
|
||||
Usually it is best to run your dev AA instance in debug mode, so you get all the detailed error messages that helps a lot for finding errors. But there might be cases where you want to test features that do not exist in debug mode (e.g. error pages) or just want to see how your app behaves in non-debug / production mode.
|
||||
|
||||
@ -335,7 +330,7 @@ In addition you can start a celery worker instance for myauth. For development p
|
||||
|
||||
This can be done from the command line with the following command in the myauth folder (where manage.py is located):
|
||||
|
||||
```bash
|
||||
```shell
|
||||
celery -A myauth worker -l info -P solo
|
||||
```
|
||||
|
||||
@ -499,7 +494,7 @@ Open a WSL bash and navigate to the aa-dev folder. Make sure you have activate y
|
||||
|
||||
Run these commands:
|
||||
|
||||
```bash
|
||||
```shell
|
||||
git clone https://gitlab.com/ErikKalkoken/allianceauth-example-plugin.git
|
||||
pip install -e allianceauth-example-plugin
|
||||
```
|
||||
@ -508,7 +503,7 @@ Add `'example'` to INSTALLED_APPS in your `local.py` settings.
|
||||
|
||||
Run migrations and restart your AA server, e.g.:
|
||||
|
||||
```bash
|
||||
```shell
|
||||
cd myauth
|
||||
python manage.py migrate
|
||||
```
|
||||
|
||||
@ -2,9 +2,8 @@
|
||||
|
||||
Here you find guides on how to setup your development environment for AA.
|
||||
|
||||
```eval_rst
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
```{toctree}
|
||||
:maxdepth: 1
|
||||
|
||||
aa-dev-setup-wsl-vsc-v2
|
||||
aa-dev-setup-wsl-vsc-v2
|
||||
```
|
||||
|
||||
@ -2,12 +2,11 @@
|
||||
|
||||
**Alliance Auth** is designed to be extended easily. Learn how to develop your own apps and services for AA or to develop for AA core in the development chapter.
|
||||
|
||||
```eval_rst
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
```{toctree}
|
||||
:maxdepth: 1
|
||||
|
||||
custom/index
|
||||
aa_core/index
|
||||
dev_setup/index
|
||||
tech_docu/index
|
||||
custom/index
|
||||
aa_core/index
|
||||
dev_setup/index
|
||||
tech_docu/index
|
||||
```
|
||||
|
||||
@ -2,16 +2,15 @@
|
||||
|
||||
To reduce redundancy and help speed up development we encourage developers to utilize the following packages when developing apps for Alliance Auth.
|
||||
|
||||
```eval_rst
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
```{toctree}
|
||||
:maxdepth: 1
|
||||
|
||||
discord_client
|
||||
discord_service
|
||||
esi
|
||||
evelinks
|
||||
eveonline
|
||||
notifications
|
||||
testutils
|
||||
utils
|
||||
discord_client
|
||||
discord_service
|
||||
esi
|
||||
evelinks
|
||||
eveonline
|
||||
notifications
|
||||
testutils
|
||||
utils
|
||||
```
|
||||
|
||||
@ -14,8 +14,7 @@ Alliance Auth is an online web application and as such the user expects fast and
|
||||
|
||||
As a rule of thumb we therefore recommend to use celery tasks for every process that can take longer than 1 sec to complete (also think about how long your process might take with large amounts of data).
|
||||
|
||||
```eval_rst
|
||||
.. note::
|
||||
:::{note}
|
||||
Another solution for dealing with long response time in particular when loading pages is to load parts of a page asynchronously, for example with AJAX.
|
||||
```
|
||||
|
||||
@ -106,7 +105,7 @@ In this example we fist add 10 example tasks that need to run one after the othe
|
||||
|
||||
The list of task signatures is then converted to a chain and started asynchronously.
|
||||
|
||||
```eval_rst
|
||||
```{eval-rst}
|
||||
.. hint::
|
||||
In our example we use ``si()``, which is a shortcut for "immutable signatures" and prevents us from having to deal with result sharing between tasks.
|
||||
|
||||
@ -137,7 +136,7 @@ CELERYBEAT_SCHEDULE['structures_update_all_structures'] = {
|
||||
|
||||
In Alliance Auth we have defined task priorities from 0 - 9 as follows:
|
||||
|
||||
```eval_rst
|
||||
```{eval-rst}
|
||||
====== ========= ===========
|
||||
Number Priority Description
|
||||
====== ========= ===========
|
||||
@ -150,14 +149,14 @@ In Alliance Auth we have defined task priorities from 0 - 9 as follows:
|
||||
====== ========= ===========
|
||||
```
|
||||
|
||||
```eval_rst
|
||||
```{eval-rst}
|
||||
.. warning::
|
||||
Please make sure to use task priorities with care and especially do not use higher priorities without a good reason. All apps including Alliance Auth share the same task queues, so using higher task priorities excessively can potentially prevent more important tasks (of other apps) from completing on time.
|
||||
|
||||
You also want to make sure to run use lower priorities if you have a large amount of tasks or long running tasks, which are not super urgent. (e.g. the regular update of all Eve characters from ESI runs with priority 7)
|
||||
```
|
||||
|
||||
```eval_rst
|
||||
```{eval-rst}
|
||||
.. hint::
|
||||
If no priority is specified all tasks will be started with the default priority, which is 5.
|
||||
```
|
||||
@ -170,7 +169,7 @@ Example for starting a task with priority 3:
|
||||
example.apply_async(priority=3)
|
||||
```
|
||||
|
||||
```eval_rst
|
||||
```{eval-rst}
|
||||
.. hint::
|
||||
For defining a priority to tasks you can not use the convenient shortcut ``delay()``, but instead need to start a task with ``apply_async()``, which also requires you to pass parameters to your task function differently. Please check out the `official docs <https://docs.celeryproject.org/en/stable/reference/celery.app.task.html#celery.app.task.Task.apply_async>`_ for details.
|
||||
```
|
||||
|
||||
@ -2,12 +2,11 @@
|
||||
|
||||
In this section you find topics useful for app developers.
|
||||
|
||||
```eval_rst
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
```{toctree}
|
||||
:maxdepth: 1
|
||||
|
||||
api/index
|
||||
celery
|
||||
core_models
|
||||
templatetags
|
||||
api/index
|
||||
celery
|
||||
core_models
|
||||
templatetags
|
||||
```
|
||||
|
||||
@ -1,7 +1,6 @@
|
||||
# Auto Groups
|
||||
|
||||
```eval_rst
|
||||
.. note::
|
||||
:::{note}
|
||||
New in 2.0
|
||||
```
|
||||
|
||||
@ -19,7 +18,7 @@ When you create an autogroup config you will be given the following options:
|
||||
|
||||
|
||||
|
||||
```eval_rst
|
||||
```{eval-rst}
|
||||
.. warning::
|
||||
After creating a group you wont be able to change the Corp and Alliance group prefixes, name source and the replace spaces settings. Make sure you configure these the way you want before creating the config. If you need to change these you will have to create a new autogroup config.
|
||||
```
|
||||
@ -38,7 +37,7 @@ When you create an autogroup config you will be given the following options:
|
||||
|
||||
Auto Groups are configured via models in the Admin Interface, a user will require the `Staff` Flag in addition to the following permissions.
|
||||
|
||||
```eval_rst
|
||||
```{eval-rst}
|
||||
+-------------------------------------------+------------------+----------------+
|
||||
| Permission | Admin Site | Auth Site |
|
||||
+===========================================+==================+================+
|
||||
|
||||
@ -90,7 +90,7 @@ Characters from all Corp Stats to which the user has view access will be display
|
||||
|
||||
To use this feature, users will require some of the following:
|
||||
|
||||
```eval_rst
|
||||
```{eval-rst}
|
||||
+---------------------------------------+------------------+----------------------------------------------------+
|
||||
| Permission | Admin Site | Auth Site |
|
||||
+=======================================+==================+====================================================+
|
||||
|
||||
@ -16,7 +16,7 @@ To administer this feature, users will require some of the following.
|
||||
|
||||
Users do not require any permissions to interact with FAT Links created.
|
||||
|
||||
```eval_rst
|
||||
```{eval-rst}
|
||||
+---------------------------------------+------------------+--------------------------------------------------------------------------+
|
||||
| Permission | Admin Site | Auth Site |
|
||||
+=======================================+==================+==========================================================================+
|
||||
|
||||
@ -44,7 +44,7 @@ To administer this feature, users will require some of the following.
|
||||
|
||||
Users do not require any permission to apply to a corporation and fill out the form.
|
||||
|
||||
```eval_rst
|
||||
```{eval-rst}
|
||||
+---------------------------------------+------------------+----------------------------------------------------+
|
||||
| Permission | Admin Site | Auth Site |
|
||||
+=======================================+==================+====================================================+
|
||||
|
||||
@ -2,16 +2,15 @@
|
||||
|
||||
**Alliance Auth** comes with a set of apps (also called plugin-apps) which provide basic functions useful to many organizations in Eve Online like a fleet schedule and a timerboard. This section describes which apps are available and how to install and use them. Please note that any app need to be installed before it can be used.
|
||||
|
||||
```eval_rst
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
```{toctree}
|
||||
:maxdepth: 1
|
||||
|
||||
autogroups
|
||||
corpstats
|
||||
fleetactivitytracking
|
||||
hrapplications
|
||||
optimer
|
||||
permissions_tool
|
||||
srp
|
||||
timerboard
|
||||
autogroups
|
||||
corpstats
|
||||
fleetactivitytracking
|
||||
hrapplications
|
||||
optimer
|
||||
permissions_tool
|
||||
srp
|
||||
timerboard
|
||||
```
|
||||
|
||||
@ -12,7 +12,7 @@ Add `'allianceauth.optimer',` to your `INSTALLED_APPS` list in your auth project
|
||||
|
||||
To use and administer this feature, users will require some of the following.
|
||||
|
||||
```eval_rst
|
||||
```{eval-rst}
|
||||
+---------------------------------------+------------------+--------------------------------------------------------------------------+
|
||||
| Permission | Admin Site | Auth Site |
|
||||
+=======================================+==================+==========================================================================+
|
||||
|
||||
@ -42,7 +42,7 @@ Please note that users may appear multiple times if this permission is granted v
|
||||
|
||||
To use this feature, users will require some of the following.
|
||||
|
||||
```eval_rst
|
||||
```{eval-rst}
|
||||
+---------------------------------------+------------------+--------------------------------------------------------------------------+
|
||||
| Permission | Admin Site | Auth Site |
|
||||
+=======================================+==================+==========================================================================+
|
||||
|
||||
@ -12,7 +12,7 @@ Add `'allianceauth.srp',` to your `INSTALLED_APPS` list in your auth project's s
|
||||
|
||||
To use and administer this feature, users will require some of the following.
|
||||
|
||||
```eval_rst
|
||||
```{eval-rst}
|
||||
+----------------------+------------------+------------------------------------------------------------+
|
||||
| Permission | Admin Site | Auth Site |
|
||||
+======================+==================+============================================================+
|
||||
|
||||
@ -12,7 +12,7 @@ Add `'allianceauth.timerboard',` to your `INSTALLED_APPS` list in your auth proj
|
||||
|
||||
To use and administer this feature, users will require some of the following.
|
||||
|
||||
```eval_rst
|
||||
```{eval-rst}
|
||||
+---------------------------------------+------------------+--------------------------------------------------------------------------+
|
||||
| Permission | Admin Site | Auth Site |
|
||||
+=======================================+==================+==========================================================================+
|
||||
|
||||
@ -10,7 +10,7 @@ You can open the admin site by clicking on "Admin" in the drop down menu for a u
|
||||
|
||||
For small to medium size alliances it is often sufficient to have no more then two superuser admins (admins that also are superusers). Having two admins usually makes sense, so you can have one primary and one backup.
|
||||
|
||||
```eval_rst
|
||||
```{eval-rst}
|
||||
.. warning::
|
||||
Superusers have read & write access to everything on your AA installation. Superusers also automatically have all permissions and therefore access to all features of your apps. Therefore we recommend to be very careful to whom you give superuser privileges.
|
||||
```
|
||||
@ -26,8 +26,7 @@ To create a staff admin you need to do two things:
|
||||
1. Enable the `is_staff` property for a user
|
||||
1. Give the user permissions for admin tasks
|
||||
|
||||
```eval_rst
|
||||
.. note::
|
||||
:::{note}
|
||||
Note that staff admins have the following limitations:
|
||||
|
||||
- Can not promote users to staff
|
||||
@ -42,7 +41,7 @@ To create a staff admin you need to do two things:
|
||||
Access to the admin site is restricted. Users needs to have the `is_staff` property to be able to open the site at all. The superuser that is created during the installation
|
||||
process will automatically have access to the admin site.
|
||||
|
||||
```eval_rst
|
||||
```{eval-rst}
|
||||
.. hint::
|
||||
Without any permissions a "staff user" can open the admin site, but can neither view nor edit anything except for viewing the list of permissions.
|
||||
```
|
||||
|
||||
@ -64,7 +64,7 @@ This data is stored in a Team Google Analytics Dashboard. The Maintainers all ha
|
||||
|
||||
### Analytics Event
|
||||
|
||||
```eval_rst
|
||||
```{eval-rst}
|
||||
.. automodule:: allianceauth.analytics.tasks
|
||||
:members: analytics_event
|
||||
:undoc-members:
|
||||
|
||||
@ -13,7 +13,7 @@ For admin users the dashboard shows additional technical information about the
|
||||
Here is a list of available settings for the dashboard. They can be configured by adding them to your AA settings file (``local.py``).
|
||||
Note that all settings are optional and the app will use the documented default settings if they are not used.
|
||||
|
||||
```eval_rst
|
||||
```{eval-rst}
|
||||
+-----------------------------------------------------+-------------------------------------------------------------------------+-----------+
|
||||
| Name | Description | Default |
|
||||
+=====================================================+=========================================================================+===========+
|
||||
|
||||
@ -42,7 +42,7 @@ Most people won't have a use for public groups, though it can be useful if you w
|
||||
|
||||
When a group is restricted only superuser admins can directly add or remove them to/from users. The purpose of this property is prevent staff admins from assigning themselves to groups that are security sensitive. The "restricted" property can be combined with all the other properties.
|
||||
|
||||
```eval_rst
|
||||
```{eval-rst}
|
||||
.. _ref-reserved-group-names:
|
||||
```
|
||||
|
||||
@ -50,8 +50,7 @@ When a group is restricted only superuser admins can directly add or remove them
|
||||
|
||||
When using Alliance Auth to manage external services like Discord, Auth will automatically duplicate groups on those services. E.g. on Discord Auth will create roles of the same name as groups. However, there may be cases where you want to manage groups on external services by yourself or by another bot. For those cases you can define a list of reserved group names. Auth will ensure that you can not create groups with a reserved name. You will find this list on the admin site under groupmanagement.
|
||||
|
||||
```eval_rst
|
||||
.. note::
|
||||
:::{note}
|
||||
While this feature can help to avoid naming conflicts with groups on external services, the respective service component in Alliance Auth also needs to be build in such a way that it knows how to prevent these conflicts. Currently only the Discord and Teamspeak3 services have this ability.
|
||||
```
|
||||
|
||||
@ -101,8 +100,7 @@ By default, in AA both requests and leaves for non-open groups must be approved
|
||||
GROUPMANAGEMENT_AUTO_LEAVE = True
|
||||
```
|
||||
|
||||
```eval_rst
|
||||
.. note::
|
||||
:::{note}
|
||||
Before you set `GROUPMANAGEMENT_AUTO_LEAVE = True`, make sure there are no pending leave requests, as this option will hide the "Leave Requests" tab.
|
||||
```
|
||||
|
||||
@ -111,7 +109,7 @@ GROUPMANAGEMENT_AUTO_LEAVE = True
|
||||
Here is a list of available settings for Group Management. They can be configured by adding them to your AA settings file (``local.py``).
|
||||
Note that all settings are optional and the app will use the documented default settings if they are not used.
|
||||
|
||||
```eval_rst
|
||||
```{eval-rst}
|
||||
+---------------------------------------------+---------------------------------------------------------------------------+------------+
|
||||
| Name | Description | Default |
|
||||
+=============================================+===========================================================================+============+
|
||||
@ -127,14 +125,13 @@ In order to join a group other than a public group, the permission `groupmanagem
|
||||
|
||||
When a user loses this permission, they will be removed from all groups _except_ Public groups.
|
||||
|
||||
```eval_rst
|
||||
.. note::
|
||||
:::{note}
|
||||
By default, the ``groupmanagement.request_groups`` permission is applied to the ``Member`` group. In most instances this, and perhaps adding it to the ``Blue`` group, should be all that is ever needed. It is unsupported and NOT advisable to apply this permission to a public group. See #697 for more information.
|
||||
```
|
||||
|
||||
Group Management should be mostly done using group leaders, a series of permissions are included below for thoroughness:
|
||||
|
||||
```eval_rst
|
||||
```{eval-rst}
|
||||
+--------------------------------+-------------------+------------------------------------------------------------------------------------+
|
||||
| Permission | Admin Site | Auth Site |
|
||||
+================================+===================+====================================================================================+
|
||||
|
||||
@ -2,14 +2,13 @@
|
||||
|
||||
Managing access to applications and services is one of the core functions of **Alliance Auth**. The related key concepts and functionalities are describes in this section.
|
||||
|
||||
```eval_rst
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
```{toctree}
|
||||
:maxdepth: 1
|
||||
|
||||
dashboard
|
||||
states
|
||||
groups
|
||||
analytics
|
||||
notifications
|
||||
admin_site
|
||||
dashboard
|
||||
states
|
||||
groups
|
||||
analytics
|
||||
notifications
|
||||
admin_site
|
||||
```
|
||||
|
||||
@ -2,13 +2,12 @@
|
||||
|
||||
Learn about the features of **Alliance Auth** and how to install and use them.
|
||||
|
||||
```eval_rst
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
```{toctree}
|
||||
:maxdepth: 1
|
||||
|
||||
overview
|
||||
core/index
|
||||
services/index
|
||||
apps/index
|
||||
community/index
|
||||
overview
|
||||
core/index
|
||||
services/index
|
||||
apps/index
|
||||
community/index
|
||||
```
|
||||
|
||||
@ -33,8 +33,7 @@ CELERYBEAT_SCHEDULE['discord.update_all_usernames'] = {
|
||||
}
|
||||
```
|
||||
|
||||
```eval_rst
|
||||
.. note::
|
||||
:::{note}
|
||||
You will have to add most the values for these settings, e.g. your Discord server ID (aka guild ID), later in the setup process.
|
||||
```
|
||||
|
||||
@ -48,8 +47,7 @@ Now retrieve the server ID [following this procedure.](https://support.discord.c
|
||||
|
||||
Update your auth project's settings file, inputting the server ID as `DISCORD_GUILD_ID`
|
||||
|
||||
```eval_rst
|
||||
.. note::
|
||||
:::{note}
|
||||
If you already have a Discord server skip the creation step, but be sure to retrieve the server ID
|
||||
```
|
||||
|
||||
@ -107,12 +105,11 @@ Second, it is possible to exclude Discord roles from being managed by Auth at al
|
||||
|
||||
To exclude roles from being managed by Auth you only have to add them to the list of reserved group names in Group Management.
|
||||
|
||||
```eval_rst
|
||||
.. note::
|
||||
:::{note}
|
||||
Role names on Discord are case sensitive, while reserved group names on Auth are not. Therefore reserved group names will cover all roles regardless of their case. For example if you have reserved the group name "alpha", then the Discord roles "alpha" and "Alpha" will both be persisted.
|
||||
```
|
||||
|
||||
```eval_rst
|
||||
```{eval-rst}
|
||||
.. seealso::
|
||||
For more information see :ref:`ref-reserved-group-names`.
|
||||
```
|
||||
@ -123,11 +120,11 @@ The Discord service contains a number of tasks that can be run to manually perfo
|
||||
|
||||
You can run any of these tasks from the command line. Please make sure that you are in your venv and then you can run this command from the same folder that your manage.py is located:
|
||||
|
||||
```bash
|
||||
```shell
|
||||
celery -A myauth call discord.update_all_groups
|
||||
```
|
||||
|
||||
```eval_rst
|
||||
```{eval-rst}
|
||||
======================== ====================================================
|
||||
Name Description
|
||||
======================== ====================================================
|
||||
@ -138,8 +135,7 @@ Name Description
|
||||
======================== ====================================================
|
||||
```
|
||||
|
||||
```eval_rst
|
||||
.. note::
|
||||
:::{note}
|
||||
Depending on how many users you have, running these tasks can take considerable time to finish. You can calculate roughly 1 sec per user for all tasks, except update_all, which needs roughly 3 secs per user.
|
||||
```
|
||||
|
||||
@ -147,7 +143,7 @@ Name Description
|
||||
|
||||
You can configure your Discord services with the following settings:
|
||||
|
||||
```eval_rst
|
||||
```{eval-rst}
|
||||
=================================== ============================================================================================= =======
|
||||
Name Description Default
|
||||
=================================== ============================================================================================= =======
|
||||
@ -168,7 +164,7 @@ Name Description
|
||||
|
||||
To use this service, users will require some of the following.
|
||||
|
||||
```eval_rst
|
||||
```{eval-rst}
|
||||
+---------------------------------------+------------------+--------------------------------------------------------------------------+
|
||||
| Permission | Admin Site | Auth Site |
|
||||
+=======================================+==================+==========================================================================+
|
||||
|
||||
@ -17,7 +17,7 @@ DISCOURSE_SSO_SECRET = ''
|
||||
|
||||
## Install Docker
|
||||
|
||||
```bash
|
||||
```shell
|
||||
wget -qO- https://get.docker.io/ | sh
|
||||
```
|
||||
|
||||
@ -25,14 +25,14 @@ wget -qO- https://get.docker.io/ | sh
|
||||
|
||||
### Download Discourse
|
||||
|
||||
```bash
|
||||
```shell
|
||||
mkdir /var/discourse
|
||||
git clone https://github.com/discourse/discourse_docker.git /var/discourse
|
||||
```
|
||||
|
||||
### Configure
|
||||
|
||||
```bash
|
||||
```shell
|
||||
cd /var/discourse
|
||||
cp samples/standalone.yml containers/app.yml
|
||||
nano containers/app.yml
|
||||
@ -68,7 +68,7 @@ Or any other port will do, if taken. Remember this number.
|
||||
|
||||
### Build and launch
|
||||
|
||||
```bash
|
||||
```shell
|
||||
nano /etc/default/docker
|
||||
```
|
||||
|
||||
@ -80,13 +80,13 @@ Uncomment this line:
|
||||
|
||||
Restart Docker:
|
||||
|
||||
```bash
|
||||
```shell
|
||||
service docker restart
|
||||
```
|
||||
|
||||
Now build:
|
||||
|
||||
```bash
|
||||
```shell
|
||||
./launcher bootstrap app
|
||||
./launcher start app
|
||||
```
|
||||
@ -124,7 +124,7 @@ server {
|
||||
|
||||
From the `/var/discourse` directory,
|
||||
|
||||
```bash
|
||||
```shell
|
||||
./launcher enter app
|
||||
rake admin:create
|
||||
```
|
||||
@ -157,7 +157,7 @@ Finally run migrations and restart Gunicorn and Celery.
|
||||
|
||||
To use this service, users will require some of the following.
|
||||
|
||||
```eval_rst
|
||||
```{eval-rst}
|
||||
+---------------------------------------+------------------+--------------------------------------------------------------------------+
|
||||
| Permission | Admin Site | Auth Site |
|
||||
+=======================================+==================+==========================================================================+
|
||||
|
||||
@ -4,26 +4,24 @@
|
||||
|
||||
## Supported Services
|
||||
|
||||
```eval_rst
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
```{toctree}
|
||||
:maxdepth: 1
|
||||
|
||||
discord
|
||||
discourse
|
||||
mumble
|
||||
openfire
|
||||
phpbb3
|
||||
smf
|
||||
teamspeak3
|
||||
xenforo
|
||||
discord
|
||||
discourse
|
||||
mumble
|
||||
openfire
|
||||
phpbb3
|
||||
smf
|
||||
teamspeak3
|
||||
xenforo
|
||||
```
|
||||
|
||||
## Tools
|
||||
|
||||
```eval_rst
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
```{toctree}
|
||||
:maxdepth: 1
|
||||
|
||||
nameformats
|
||||
permissions
|
||||
nameformats
|
||||
permissions
|
||||
```
|
||||
|
||||
@ -2,12 +2,11 @@
|
||||
|
||||
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.
|
||||
|
||||
```eval_rst
|
||||
.. note::
|
||||
:::{note}
|
||||
Note that this guide assumes that you have installed Auth with the official :doc:`/installation/allianceauth` guide under ``/home/allianceserver`` and that it is called ``myauth``. Accordingly it assumes that you have a service user called ``allianceserver`` that is used to run all Auth services under supervisor.
|
||||
```
|
||||
|
||||
```eval_rst
|
||||
```{eval-rst}
|
||||
.. warning::
|
||||
This guide is currently for Ubuntu only.
|
||||
```
|
||||
@ -18,17 +17,17 @@ Mumble is a free voice chat server. While not as flashy as TeamSpeak, it has all
|
||||
|
||||
The mumble server package can be retrieved from a repository, which we need to add:
|
||||
|
||||
```bash
|
||||
```shell
|
||||
sudo apt-add-repository ppa:mumble/release
|
||||
```
|
||||
|
||||
```bash
|
||||
```shell
|
||||
sudo apt-get update
|
||||
```
|
||||
|
||||
Now three packages need to be installed:
|
||||
|
||||
```bash
|
||||
```shell
|
||||
sudo apt-get install python-software-properties mumble-server libqt5sql5-mysql
|
||||
```
|
||||
|
||||
@ -36,19 +35,19 @@ sudo apt-get install python-software-properties mumble-server libqt5sql5-mysql
|
||||
|
||||
Next, we need to download the latest authenticator release from the [authenticator repository](https://gitlab.com/allianceauth/mumble-authenticator).
|
||||
|
||||
```bash
|
||||
```shell
|
||||
git clone https://gitlab.com/allianceauth/mumble-authenticator /home/allianceserver/mumble-authenticator
|
||||
```
|
||||
|
||||
We will now install the authenticator into your Auth virtual environment. Please make sure to activate it first:
|
||||
|
||||
```bash
|
||||
```shell
|
||||
source /home/allianceserver/venv/auth/bin/activate
|
||||
```
|
||||
|
||||
Install the python dependencies for the mumble authenticator. Note that this process can take 2-10 minutes to complete.
|
||||
|
||||
```bash
|
||||
```shell
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
@ -66,7 +65,7 @@ GRANT ALL PRIVILEGES ON alliance_mumble . * TO 'allianceserver'@'localhost';
|
||||
|
||||
Mumble ships with a configuration file that needs customization. By default it’s located at `/etc/mumble-server.ini`. Open it with your favorite text editor:
|
||||
|
||||
```bash
|
||||
```shell
|
||||
sudo nano /etc/mumble-server.ini
|
||||
```
|
||||
|
||||
@ -90,7 +89,7 @@ Save and close the file.
|
||||
|
||||
To get Mumble superuser account credentials, run the following:
|
||||
|
||||
```bash
|
||||
```shell
|
||||
sudo dpkg-reconfigure mumble-server
|
||||
```
|
||||
|
||||
@ -98,7 +97,7 @@ Set the password to something you’ll remember and write it down. This is your
|
||||
|
||||
Now restart the server to see the changes reflected.
|
||||
|
||||
```bash
|
||||
```shell
|
||||
sudo service mumble-server restart
|
||||
```
|
||||
|
||||
@ -110,7 +109,7 @@ The ICE authenticator lives in the mumble-authenticator repository, cd to the di
|
||||
|
||||
Make a copy of the default config:
|
||||
|
||||
```bash
|
||||
```shell
|
||||
cp authenticator.ini.example authenticator.ini
|
||||
```
|
||||
|
||||
@ -124,19 +123,19 @@ Edit `authenticator.ini` and change these values:
|
||||
|
||||
Test your configuration by starting it:
|
||||
|
||||
```bash
|
||||
```shell
|
||||
python /home/allianceserver/mumble-authenticator/authenticator.py
|
||||
```
|
||||
|
||||
And finally ensure the allianceserver user has read/write permissions to the mumble authenticator files before proceeding:
|
||||
|
||||
```bash
|
||||
```shell
|
||||
sudo chown -R allianceserver:allianceserver /home/allianceserver/mumble-authenticator
|
||||
```
|
||||
|
||||
The authenticator needs to be running 24/7 to validate users on Mumble. This can be achieved by adding a section to your auth project's supervisor config file like the following example:
|
||||
|
||||
```text
|
||||
```ini
|
||||
[program:authenticator]
|
||||
command=/home/allianceserver/venv/auth/bin/python authenticator.py
|
||||
directory=/home/allianceserver/mumble-authenticator
|
||||
@ -151,7 +150,7 @@ priority=996
|
||||
|
||||
In addition we'd recommend to add the authenticator to Auth's restart group in your supervisor conf. For that you need to add it to the group line as shown in the following example:
|
||||
|
||||
```text
|
||||
```ini
|
||||
[group:myauth]
|
||||
programs=beat,worker,gunicorn,authenticator
|
||||
priority=999
|
||||
@ -159,7 +158,7 @@ priority=999
|
||||
|
||||
To enable the changes in your supervisor configuration you need to restart the supervisor process itself. And before we do that we are shutting down the current Auth supervisors gracefully:
|
||||
|
||||
```bash
|
||||
```shell
|
||||
sudo supervisor stop myauth:
|
||||
sudo systemctl restart supervisor
|
||||
```
|
||||
@ -187,11 +186,11 @@ MUMBLE_URL = "mumble.example.com"
|
||||
|
||||
Finally, run migrations and restart your supervisor to complete the setup:
|
||||
|
||||
```bash
|
||||
```shell
|
||||
python /home/allianceserver/myauth/manage.py migrate
|
||||
```
|
||||
|
||||
```bash
|
||||
```shell
|
||||
supervisorctl restart myauth:
|
||||
```
|
||||
|
||||
@ -199,7 +198,7 @@ supervisorctl restart myauth:
|
||||
|
||||
To use this service, users will require some of the following.
|
||||
|
||||
```eval_rst
|
||||
```{eval-rst}
|
||||
+---------------------------------------+------------------+--------------------------------------------------------------------------+
|
||||
| Permission | Admin Site | Auth Site |
|
||||
+=======================================+==================+==========================================================================+
|
||||
@ -262,19 +261,19 @@ If Push to Talk is to your tastes, configure the suggestion as follows
|
||||
|
||||
With the default configuration your mumble server is public. Meaning that everyone who has the address can at least connect to it and might also be able join all channels that don't have any permissions set (Depending on your ACL configured for the root channel). If you want only registered member being able to join your mumble, you have to set a server password. To do so open your mumble server configuration which is by default located at `/etc/mumble-server.ini`.
|
||||
|
||||
```bash
|
||||
```shell
|
||||
sudo nano /etc/mumble-server.ini
|
||||
```
|
||||
|
||||
Now search for `serverpassword=` and set your password here. If there is no such line, simply add it.
|
||||
|
||||
```text
|
||||
```ini
|
||||
serverpassword=YourSuperSecretServerPassword
|
||||
```
|
||||
|
||||
Save the file and restart your mumble server afterwards.
|
||||
|
||||
```bash
|
||||
```shell
|
||||
sudo service mumble-server restart
|
||||
```
|
||||
|
||||
|
||||
@ -6,7 +6,7 @@ Each service's username or nickname, depending on which the service supports, ca
|
||||
|
||||
Currently the following services support custom name formats:
|
||||
|
||||
```eval_rst
|
||||
```{eval-rst}
|
||||
+-------------+-----------+-------------------------------------+
|
||||
| Service | Used with | Default Formatter |
|
||||
+=============+===========+=====================================+
|
||||
@ -30,8 +30,7 @@ Currently the following services support custom name formats:
|
||||
+-------------+-----------+-------------------------------------+
|
||||
```
|
||||
|
||||
```eval_rst
|
||||
.. note::
|
||||
:::{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.
|
||||
```
|
||||
|
||||
@ -59,7 +58,7 @@ A more digestible documentation of string formatting in Python is available on t
|
||||
|
||||
Some examples of strings you could use:
|
||||
|
||||
```eval_rst
|
||||
```{eval-rst}
|
||||
+------------------------------------------+---------------------------+
|
||||
| Formatter | Result |
|
||||
+==========================================+===========================+
|
||||
@ -71,12 +70,12 @@ Some examples of strings you could use:
|
||||
+------------------------------------------+---------------------------+
|
||||
```
|
||||
|
||||
```eval_rst
|
||||
```{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
|
||||
```{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.
|
||||
```
|
||||
|
||||
@ -25,18 +25,18 @@ Openfire require a Java 8 runtime environment.
|
||||
|
||||
Ubuntu 1804, 2004, 2204:
|
||||
|
||||
```bash
|
||||
```shell
|
||||
sudo apt-get install openjdk-11-jre
|
||||
```
|
||||
|
||||
Centos 7:
|
||||
|
||||
```bash
|
||||
```shell
|
||||
sudo yum install java-11-openjdk java-11-openjdk-devel
|
||||
```
|
||||
|
||||
Centos Stream 8, Stream 9:
|
||||
```bash
|
||||
```shell
|
||||
sudo dnf install java-11-openjdk java-11-openjdk-devel
|
||||
```
|
||||
|
||||
@ -51,7 +51,7 @@ On your PC, navigate to the [Ignite Realtime downloads section](https://www.igni
|
||||
Retrieve the file location by copying the URL from the “click here” link, depending on your browser you may have a Copy Link or similar option in your right click menu.
|
||||
|
||||
In the console, ensure you’re in your user’s home directory:
|
||||
```bash
|
||||
```shell
|
||||
cd ~
|
||||
```
|
||||
|
||||
@ -59,14 +59,14 @@ Download and install the package, replacing the URL with the latest you got from
|
||||
|
||||
Ubuntu 1804, 2004, 2204:
|
||||
|
||||
```bash
|
||||
```shell
|
||||
wget https://www.igniterealtime.org/downloadServlet?filename=openfire/openfire_4.7.2_all.deb
|
||||
dpkg -i openfire_4.7.2_all.deb
|
||||
```
|
||||
|
||||
Centos 7, Stream 8, Stream 9:
|
||||
|
||||
```bash
|
||||
```shell
|
||||
wget https://www.igniterealtime.org/downloadServlet?filename=openfire/openfire-4.7.2-1.noarch.rpm
|
||||
yum install -y openfire-4.7.2-1.noarch.rpm
|
||||
```
|
||||
@ -74,7 +74,7 @@ yum install -y openfire-4.7.2-1.noarch.rpm
|
||||
|
||||
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:
|
||||
|
||||
```bash
|
||||
```shell
|
||||
mysql -u root -p
|
||||
create database alliance_jabber;
|
||||
grant all privileges on alliance_jabber . * to 'allianceserver'@'localhost';
|
||||
@ -165,7 +165,7 @@ ACL is achieved by assigning groups to each of the three tiers: `Owners`, `Admin
|
||||
|
||||
To use this service, users will require some of the following.
|
||||
|
||||
```eval_rst
|
||||
```{eval-rst}
|
||||
+---------------------------------------+------------------+--------------------------------------------------------------------------+
|
||||
| Permission | Admin Site | Auth Site |
|
||||
+=======================================+==================+==========================================================================+
|
||||
|
||||
@ -6,7 +6,7 @@ In the past, access to services was dictated by a list of settings in `settings.
|
||||
|
||||
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
|
||||
```{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.
|
||||
```
|
||||
@ -19,7 +19,7 @@ A user can be granted the same permission from multiple sources. e.g. they may h
|
||||
|
||||
## Removing access
|
||||
|
||||
```eval_rst
|
||||
```{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.
|
||||
```
|
||||
|
||||
@ -34,7 +34,7 @@ DATABASES['phpbb3'] = {
|
||||
|
||||
Create a database to install phpBB3 in.
|
||||
|
||||
```bash
|
||||
```shell
|
||||
mysql -u root -p
|
||||
create database alliance_forum;
|
||||
grant all privileges on alliance_forum . * to 'allianceserver'@'localhost';
|
||||
@ -51,19 +51,19 @@ In the console, navigate to your user’s home directory: `cd ~`
|
||||
|
||||
Now download using wget, replacing the URL with the URL for the package you just retrieved
|
||||
|
||||
```bash
|
||||
```shell
|
||||
wget https://download.phpbb.com/pub/release/3.3/3.3.8/phpBB-3.3.8.zip
|
||||
```
|
||||
|
||||
This needs to be unpackaged. Unzip it, replacing the file name with that of the file you just downloaded
|
||||
|
||||
```bash
|
||||
```shell
|
||||
unzip phpBB-3.3.8.zip
|
||||
```
|
||||
|
||||
Now we need to move this to our web directory. Usually `/var/www/forums`.
|
||||
|
||||
```bash
|
||||
```shell
|
||||
mv phpBB3 /var/www/forums
|
||||
```
|
||||
|
||||
@ -72,7 +72,7 @@ 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
|
||||
```{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.
|
||||
..
|
||||
@ -157,7 +157,7 @@ phpBB will then write its own config file.
|
||||
|
||||
Before users can see the forums, we need to remove the install directory
|
||||
|
||||
```bash
|
||||
```shell
|
||||
rm -rf /var/www/forums/install
|
||||
```
|
||||
|
||||
@ -171,7 +171,7 @@ You can allow members to overwrite the portrait with a custom image if desired.
|
||||
|
||||
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
|
||||
|
||||
```bash
|
||||
```shell
|
||||
mysql -u root -p
|
||||
use alliance_forum;
|
||||
alter table phpbb_users change user_style user_style int not null default 1
|
||||
@ -187,7 +187,7 @@ Once settings have been configured, run migrations and restart Gunicorn and Cele
|
||||
|
||||
To use this service, users will require some of the following.
|
||||
|
||||
```eval_rst
|
||||
```{eval-rst}
|
||||
+---------------------------------------+------------------+--------------------------------------------------------------------------+
|
||||
| Permission | Admin Site | Auth Site |
|
||||
+=======================================+==================+==========================================================================+
|
||||
|
||||
@ -36,17 +36,17 @@ Using your browser, you can download the latest version of SMF to your desktop c
|
||||
|
||||
Download using wget, replacing the URL with the URL for the package you just retrieved
|
||||
|
||||
```bash
|
||||
```shell
|
||||
wget https://download.simplemachines.org/index.php?thanks;filename=smf_2-1-2_install.tar.gz
|
||||
```
|
||||
|
||||
This needs to be unpackaged. Unzip it, replacing the file name with that of the file you just downloaded
|
||||
```bash
|
||||
```shell
|
||||
unzip smf_2-1-2_install.zip
|
||||
```
|
||||
|
||||
Now we need to move this to our web directory. Usually `/var/www/forums`.
|
||||
```bash
|
||||
```shell
|
||||
mv smf /var/www/forums
|
||||
````
|
||||
|
||||
@ -55,7 +55,7 @@ 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
|
||||
```{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.
|
||||
..
|
||||
@ -139,7 +139,7 @@ Once settings are entered, apply migrations and restart Gunicorn and Celery.
|
||||
|
||||
To use this service, users will require some of the following.
|
||||
|
||||
```eval_rst
|
||||
```{eval-rst}
|
||||
+---------------------------------------+------------------+--------------------------------------------------------------------------+
|
||||
| Permission | Admin Site | Auth Site |
|
||||
+=======================================+==================+==========================================================================+
|
||||
|
||||
@ -38,14 +38,14 @@ To install we need a copy of the server. You can find the latest version from th
|
||||
|
||||
Download the server, replacing the link with the link you got earlier.
|
||||
|
||||
``` bash
|
||||
```bash
|
||||
cd ~
|
||||
wget https://files.teamspeak-services.com/releases/server/3.13.7/teamspeak3-server_linux_amd64-3.13.7.tar.bz2
|
||||
```
|
||||
|
||||
Now we need to extract the file.
|
||||
|
||||
```bash
|
||||
```shell
|
||||
tar -xf teamspeak3-server_linux_amd64-3.13.7.tar.bz2
|
||||
```
|
||||
|
||||
@ -53,7 +53,7 @@ tar -xf teamspeak3-server_linux_amd64-3.13.7.tar.bz2
|
||||
|
||||
TeamSpeak needs its own user.
|
||||
|
||||
```bash
|
||||
```shell
|
||||
adduser --disabled-login teamspeak
|
||||
```
|
||||
|
||||
@ -61,7 +61,7 @@ adduser --disabled-login teamspeak
|
||||
|
||||
Now we move the server binary somewhere more accessible and change its ownership to the new user.
|
||||
|
||||
```bash
|
||||
```shell
|
||||
mv teamspeak3-server_linux_amd64 /usr/local/teamspeak
|
||||
chown -R teamspeak:teamspeak /usr/local/teamspeak
|
||||
```
|
||||
@ -70,14 +70,14 @@ chown -R teamspeak:teamspeak /usr/local/teamspeak
|
||||
|
||||
Now we generate a startup script so TeamSpeak comes up with the server.
|
||||
|
||||
```bash
|
||||
```shell
|
||||
ln -s /usr/local/teamspeak/ts3server_startscript.sh /etc/init.d/teamspeak
|
||||
update-rc.d teamspeak defaults
|
||||
```
|
||||
|
||||
Finally we start the server.
|
||||
|
||||
```bash
|
||||
```shell
|
||||
service teamspeak start
|
||||
```
|
||||
|
||||
@ -85,7 +85,7 @@ service teamspeak start
|
||||
|
||||
Set your Teamspeak Serveradmin password to a random string
|
||||
|
||||
```bash
|
||||
```shell
|
||||
./ts3server_minimal_runscript.sh inifile=ts3server.ini serveradmin_password=pleasegeneratearandomstring
|
||||
|
||||
```
|
||||
@ -139,7 +139,7 @@ Then, in the top-right corner click, click on `Update TS3 Groups` to start the p
|
||||
|
||||
Start a django shell with:
|
||||
|
||||
```bash
|
||||
```shell
|
||||
python manage.py shell
|
||||
```
|
||||
|
||||
@ -180,7 +180,7 @@ This usually occurs if you've created a separate serverquery user to use with au
|
||||
|
||||
To use and configure this service, users will require some of the following.
|
||||
|
||||
```eval_rst
|
||||
```{eval-rst}
|
||||
+---------------------------------------+------------------+--------------------------------------------------------------------------+
|
||||
| Permission | Admin Site | Auth Site |
|
||||
+=======================================+==================+==========================================================================+
|
||||
|
||||
@ -47,7 +47,7 @@ Once these are entered, run migrations and restart Gunicorn and Celery.
|
||||
|
||||
To use this service, users will require some of the following.
|
||||
|
||||
```eval_rst
|
||||
```{eval-rst}
|
||||
+---------------------------------------+------------------+--------------------------------------------------------------------------+
|
||||
| Permission | Admin Site | Auth Site |
|
||||
+=======================================+==================+==========================================================================+
|
||||
|
||||
@ -7,16 +7,15 @@ Welcome to the official documentation for **Alliance Auth**!
|
||||
|
||||
**Alliance Auth** is a web site that helps Eve Online organizations efficiently manage access to applications and external services.
|
||||
|
||||
```eval_rst
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:caption: Contents
|
||||
```{toctree}
|
||||
:maxdepth: 2
|
||||
:caption: Contents
|
||||
|
||||
installation/index
|
||||
features/index
|
||||
maintenance/index
|
||||
support/index
|
||||
customizing/index
|
||||
development/index
|
||||
contributing/index
|
||||
installation/index
|
||||
features/index
|
||||
maintenance/index
|
||||
support/index
|
||||
customizing/index
|
||||
development/index
|
||||
contributing/index
|
||||
```
|
||||
|
||||
@ -2,10 +2,9 @@
|
||||
|
||||
This document describes how to install **Alliance Auth** from scratch.
|
||||
|
||||
```eval_rst
|
||||
.. note::
|
||||
There are additional installation steps for activating services and apps that come with **Alliance Auth**. Please see the page for the respective service or apps in chapter :doc:`/features/index` for details.
|
||||
```
|
||||
:::{note}
|
||||
There are additional installation steps for activating services and apps that come with **Alliance Auth**. Please see the page for the respective service or apps in chapter :doc:`/features/index` for details.
|
||||
:::
|
||||
|
||||
## Dependencies
|
||||
|
||||
@ -28,234 +27,243 @@ To install on your favorite flavour of Linux, identify and install equivalent pa
|
||||
|
||||
It is recommended to ensure your OS is fully up to date before proceeding. We may also add Package Repositories here, used later in the documentation.
|
||||
|
||||
Ubuntu 1804, 2004, 2204:
|
||||
::::{tabs}
|
||||
|
||||
```bash
|
||||
:::{group-tab} Ubuntu 2004, 2204
|
||||
|
||||
```shell
|
||||
sudo apt-get update
|
||||
```
|
||||
|
||||
```bash
|
||||
```shell
|
||||
sudo apt-get upgrade
|
||||
```
|
||||
|
||||
```bash
|
||||
```shell
|
||||
sudo do-dist-upgrade
|
||||
```
|
||||
|
||||
CentOS 7:
|
||||
:::
|
||||
:::{group-tab} CentOS 7
|
||||
|
||||
```bash
|
||||
```shell
|
||||
yum install epel-release
|
||||
```
|
||||
|
||||
```bash
|
||||
```shell
|
||||
sudo yum upgrade
|
||||
```
|
||||
|
||||
CentOS Stream 8:
|
||||
:::
|
||||
:::{group-tab} CentOS Stream 8
|
||||
|
||||
```bash
|
||||
```shell
|
||||
sudo dnf config-manager --set-enabled powertools
|
||||
```
|
||||
|
||||
```bash
|
||||
```shell
|
||||
sudo dnf install epel-release epel-next-release
|
||||
```
|
||||
|
||||
```bash
|
||||
```shell
|
||||
sudo yum upgrade
|
||||
```
|
||||
|
||||
CentOS Stream 9:
|
||||
:::
|
||||
:::{group-tab} CentOS Stream 9
|
||||
|
||||
```bash
|
||||
```shell
|
||||
sudo dnf config-manager --set-enabled crb
|
||||
```
|
||||
|
||||
```bash
|
||||
dnf install epel-release epel-next-release
|
||||
```shell
|
||||
sudo dnf install epel-release epel-next-release
|
||||
```
|
||||
|
||||
```bash
|
||||
```shell
|
||||
sudo yum upgrade
|
||||
```
|
||||
|
||||
:::
|
||||
::::
|
||||
|
||||
### Python
|
||||
|
||||
Install Python 3.10 and related tools on your system.
|
||||
Install Python 3.11 and related tools on your system.
|
||||
|
||||
Ubuntu 1804, 2004:
|
||||
::::{tabs}
|
||||
|
||||
```bash
|
||||
:::{group-tab} Ubuntu 2004, 2204
|
||||
|
||||
```shell
|
||||
sudo add-apt-repository ppa:deadsnakes/ppa
|
||||
```
|
||||
|
||||
```bash
|
||||
```shell
|
||||
sudo apt-get update
|
||||
```
|
||||
|
||||
```bash
|
||||
sudo apt-get install python3.10 python3.10-dev python3.10-venv
|
||||
```shell
|
||||
sudo apt-get install python3.11 python3.11-dev python3.11-venv
|
||||
```
|
||||
|
||||
Ubuntu 2204:
|
||||
|
||||
```eval_rst
|
||||
.. note::
|
||||
Ubuntu 2204 ships with Python 3.10 already, but some important tools are missing in the default installation.
|
||||
```
|
||||
|
||||
```bash
|
||||
sudo apt-get install python3.10-dev python3.10-venv
|
||||
```
|
||||
|
||||
CentOS 7:
|
||||
:::
|
||||
:::{group-tab} CentOS 7, Stream 8, Stream 9
|
||||
We need to build Python from source
|
||||
|
||||
Centos Stream 8/9:
|
||||
|
||||
```eval_rst
|
||||
.. note::
|
||||
A Python 3.9 Package is available for Stream 8 and 9. You _may_ use this instead of building your own package. But our documentation will assume Python3.10 and you may need to substitute as necessary
|
||||
sudo dnf install python39 python39-devel
|
||||
```
|
||||
|
||||
```bash
|
||||
```shell
|
||||
cd ~
|
||||
```
|
||||
|
||||
```bash
|
||||
```shell
|
||||
sudo yum install gcc openssl-devel bzip2-devel libffi-devel wget
|
||||
```
|
||||
|
||||
```bash
|
||||
wget https://www.python.org/ftp/python/3.10.5/Python-3.10.5.tgz
|
||||
```shell
|
||||
wget https://www.python.org/ftp/python/3.11.5/Python-3.11.5.tgz
|
||||
```
|
||||
|
||||
```bash
|
||||
tar xvf Python-3.10.5.tgz
|
||||
```shell
|
||||
tar xvf Python-3.11.5.tgz
|
||||
```
|
||||
|
||||
```bash
|
||||
cd Python-3.10.5/
|
||||
```shell
|
||||
cd Python-3.11.5/
|
||||
```
|
||||
|
||||
```bash
|
||||
```shell
|
||||
./configure --enable-optimizations --enable-shared
|
||||
```
|
||||
|
||||
```bash
|
||||
```shell
|
||||
sudo make altinstall
|
||||
```
|
||||
|
||||
:::
|
||||
::::
|
||||
|
||||
### Database
|
||||
|
||||
It's recommended to use a database service instead of SQLite. Many options are available, but this guide will use MariaDB.
|
||||
It's recommended to use a database service instead of SQLite. Many options are available, but this guide will use MariaDB 10.11
|
||||
|
||||
```eval_rst
|
||||
.. note::
|
||||
Ubuntu distributions prior to 20.04 come with an older version of Maria DB, which is not compatible with **Alliance Auth**. You need Maria DB 10.3 or higher!
|
||||
For 20.04 we still recommend to install Maria DB from the link below in order to get the newest stable version.
|
||||
For 22.04 we recommend installing from the default Ubuntu distro, since it comes with the newest stable version.
|
||||
```
|
||||
::::{tabs}
|
||||
|
||||
Ubuntu 1804, 2004:
|
||||
:::{group-tab} Ubuntu 2004, 2204
|
||||
Follow the instructions at <https://mariadb.org/download/?t=repo-config&d=20.04+%22focal%22&v=10.11&r_m=osuosl> to add the MariaDB repository to your host.
|
||||
|
||||
```eval_rst
|
||||
.. warning::
|
||||
Please follow these steps to update MariaDB
|
||||
https://mariadb.org/download/?t=repo-config&d=20.04+%22focal%22&v=10.6&r_m=osuosl
|
||||
```
|
||||
|
||||
Ubuntu 1804, 2004, 2204
|
||||
|
||||
```bash
|
||||
```shell
|
||||
sudo apt-get install mariadb-server mariadb-client libmysqlclient-dev
|
||||
```
|
||||
|
||||
CentOS 7:
|
||||
:::
|
||||
:::{group-tab} CentOS 7
|
||||
Follow the instructions at <https://mariadb.org/download/?t=repo-config&d=CentOS+7&v=10.11&r_m=osuosl> to add the MariaDB repository to your host.
|
||||
|
||||
```eval_rst
|
||||
.. warning::
|
||||
Please follow these steps to update MariaDB
|
||||
https://mariadb.org/download/?t=repo-config&d=CentOS+7+%28x86_64%29&v=10.6&r_m=osuosl
|
||||
```
|
||||
|
||||
```bash
|
||||
```shell
|
||||
sudo yum install MariaDB-server MariaDB-client MariaDB-devel MariaDB-shared
|
||||
```
|
||||
|
||||
CentOS Stream 8/9:
|
||||
:::
|
||||
:::{group-tab} CentOS Stream 8
|
||||
Follow the instructions at <https://mariadb.org/download/?t=repo-config&d=CentOS+Stream&v=10.11&r_m=osuosl> to add the MariaDB repository to your host.
|
||||
|
||||
```eval_rst
|
||||
.. note::
|
||||
We recommend using the built in AppStream, as they are maintained by CentOS. Currently an AppStream is not available for 10.6
|
||||
```
|
||||
|
||||
```bash
|
||||
sudo dnf module enable mariadb:10.5
|
||||
```
|
||||
|
||||
```bash
|
||||
```shell
|
||||
sudo dnf install mariadb mariadb-server mariadb-devel
|
||||
```
|
||||
|
||||
```bash
|
||||
sudo systemctl enable mariadb
|
||||
:::
|
||||
:::{group-tab} CentOS Stream 9
|
||||
Follow the instructions at <https://mariadb.org/download/?t=repo-config&d=CentOS+Stream&v=10.11&r_m=osuosl> to add the MariaDB repository to your host.
|
||||
|
||||
```shell
|
||||
sudo dnf install mariadb mariadb-server mariadb-devel
|
||||
```
|
||||
|
||||
```bash
|
||||
sudo systemctl start mariadb
|
||||
```
|
||||
:::
|
||||
::::
|
||||
|
||||
```eval_rst
|
||||
.. important::
|
||||
If you don't plan on running the database on the same server as auth you still need to install the ``libmysqlclient-dev`` package on Ubuntu or ``mariadb-devel`` package on CentOS.
|
||||
```
|
||||
:::::{important}
|
||||
::::{tabs}
|
||||
:::{group-tab} Ubuntu 2004, 2204
|
||||
If you don't plan on running the database on the same server as auth you still need to install the `libmysqlclient-dev` package
|
||||
:::
|
||||
:::{group-tab} CentOS 7
|
||||
If you don't plan on running the database on the same server as auth you still need to install the `mariadb-devel` package
|
||||
:::
|
||||
:::{group-tab} CentOS Stream 8
|
||||
If you don't plan on running the database on the same server as auth you still need to install the `mariadb-devel` package
|
||||
:::
|
||||
:::{group-tab} CentOS Stream 9
|
||||
If you don't plan on running the database on the same server as auth you still need to install the `mariadb-devel` package
|
||||
:::
|
||||
::::
|
||||
:::::
|
||||
|
||||
### Redis and Other Tools
|
||||
|
||||
A few extra utilities are also required for installation of packages.
|
||||
|
||||
Ubuntu 1804, 2004, 2204:
|
||||
::::{tabs}
|
||||
|
||||
```bash
|
||||
:::{group-tab} Ubuntu 2004, 2204
|
||||
|
||||
```shell
|
||||
sudo apt-get install unzip git redis-server curl libssl-dev libbz2-dev libffi-dev build-essential pkg-config
|
||||
```
|
||||
|
||||
CentOS 7:
|
||||
:::
|
||||
:::{group-tab} CentOS 7
|
||||
|
||||
```bash
|
||||
```shell
|
||||
sudo yum install gcc gcc-c++ unzip git redis curl bzip2-devel openssl-devel libffi-devel wget pkg-config
|
||||
```
|
||||
|
||||
```bash
|
||||
```shell
|
||||
sudo systemctl enable redis.service
|
||||
```
|
||||
|
||||
```bash
|
||||
```shell
|
||||
sudo systemctl start redis.service
|
||||
```
|
||||
|
||||
CentOS Stream 8, Stream 9:
|
||||
:::
|
||||
:::{group-tab} CentOS Stream 8
|
||||
|
||||
```bash
|
||||
```shell
|
||||
sudo dnf install gcc gcc-c++ unzip git redis curl bzip2-devel openssl-devel libffi-devel wget
|
||||
```
|
||||
|
||||
```bash
|
||||
```shell
|
||||
sudo systemctl enable redis.service
|
||||
```
|
||||
|
||||
```bash
|
||||
```shell
|
||||
sudo systemctl start redis.service
|
||||
```
|
||||
|
||||
:::
|
||||
:::{group-tab} CentOS Stream 9
|
||||
|
||||
```shell
|
||||
sudo dnf install gcc gcc-c++ unzip git redis curl bzip2-devel openssl-devel libffi-devel wget
|
||||
```
|
||||
|
||||
```shell
|
||||
sudo systemctl enable redis.service
|
||||
```
|
||||
|
||||
```shell
|
||||
sudo systemctl start redis.service
|
||||
```
|
||||
|
||||
:::
|
||||
::::
|
||||
|
||||
## Database Setup
|
||||
|
||||
Alliance Auth needs a MySQL user account and database. Open an SQL shell with
|
||||
|
||||
```bash
|
||||
```shell
|
||||
sudo mysql -u root
|
||||
```
|
||||
|
||||
@ -271,22 +279,24 @@ Once your database is set up, you can leave the SQL shell with `exit`.
|
||||
|
||||
Add timezone tables to your mysql installation:
|
||||
|
||||
```bash
|
||||
```shell
|
||||
mysql_tzinfo_to_sql /usr/share/zoneinfo | sudo mysql -u root 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::
|
||||
:::{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;
|
||||
```bash
|
||||
mysql -u root -p
|
||||
use mysql;
|
||||
show tables;
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
Close the SQL shell and secure your database server with this command:
|
||||
|
||||
```bash
|
||||
```shell
|
||||
mysql_secure_installation
|
||||
```
|
||||
|
||||
@ -295,86 +305,96 @@ mysql_secure_installation
|
||||
### 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.
|
||||
::::{tabs}
|
||||
|
||||
Ubuntu 1804, 2004, 2204:
|
||||
:::{group-tab} Ubuntu 2004, 2204
|
||||
|
||||
```bash
|
||||
sudo adduser --disabled-login allianceserver
|
||||
```
|
||||
|
||||
CentOS 7, Stream 8, Stream 9:
|
||||
|
||||
```bash
|
||||
```shell
|
||||
sudo useradd -s /bin/bash allianceserver
|
||||
```
|
||||
|
||||
```bash
|
||||
:::
|
||||
:::{group-tab} CentOS 7
|
||||
|
||||
```shell
|
||||
sudo passwd -l allianceserver
|
||||
```
|
||||
|
||||
:::
|
||||
:::{group-tab} CentOS Stream 8
|
||||
|
||||
```shell
|
||||
sudo passwd -l allianceserver
|
||||
```
|
||||
|
||||
:::
|
||||
:::{group-tab} CentOS Stream 9
|
||||
|
||||
```shell
|
||||
sudo passwd -l allianceserver
|
||||
```
|
||||
|
||||
:::
|
||||
::::
|
||||
|
||||
### Prepare Directories
|
||||
|
||||
```bash
|
||||
```shell
|
||||
sudo mkdir -p /var/www/myauth/static
|
||||
```
|
||||
|
||||
```bash
|
||||
```shell
|
||||
sudo chown -R allianceserver:allianceserver /var/www/myauth/static/
|
||||
```
|
||||
|
||||
```eval_rst
|
||||
.. note::
|
||||
When installing and performing maintenance on Alliance Auth, using the allianceserver user will greatly simplify permission management::
|
||||
:::{warning}
|
||||
When installing and performing maintenance on Alliance Auth, virtual environments and python packages, _sudo_ means _superuser_ _do_, this will not use your venv or your allianceserver user and will routinely break your permission structure.
|
||||
|
||||
sudo su allianceserver
|
||||
Only use sudo for _system_ management or if you are unsure, when explicitly instructed to do so.
|
||||
|
||||
```shell
|
||||
sudo su allianceserver
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
### Virtual Environment
|
||||
|
||||
Switch to the allianceserver user.
|
||||
|
||||
```bash
|
||||
```shell
|
||||
sudo su allianceserver
|
||||
```
|
||||
|
||||
And switch to it's home directory:
|
||||
|
||||
```bash
|
||||
cd
|
||||
```
|
||||
|
||||
```eval_rst
|
||||
.. note::
|
||||
In general using the allianceserver user will greatly simplify permission management, when installing and performing maintenance on Alliance Auth.
|
||||
```shell
|
||||
cd ~
|
||||
```
|
||||
|
||||
Create a Python virtual environment and put it somewhere convenient (e.g. `/home/allianceserver/venv/auth/`)
|
||||
|
||||
```eval_rst
|
||||
.. note::
|
||||
Your python3.x command/version may vary depending on your installed python version.
|
||||
:::{note}
|
||||
Your python3.x command/version may vary depending on your installed python version.
|
||||
:::
|
||||
|
||||
```shell
|
||||
python3.11 -m venv /home/allianceserver/venv/auth/
|
||||
```
|
||||
|
||||
```bash
|
||||
python3.10 -m venv /home/allianceserver/venv/auth/
|
||||
```
|
||||
|
||||
```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
|
||||
```
|
||||
:::{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. <https://docs.python.org/3/library/venv.html>
|
||||
:::
|
||||
|
||||
Activate the virtual environment with (Note the `/bin/activate` on the end of the path):
|
||||
|
||||
```bash
|
||||
```shell
|
||||
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.
|
||||
```
|
||||
:::{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
|
||||
|
||||
@ -386,22 +406,21 @@ As **callback URL** you want to define the URL of your Alliance Auth site plus t
|
||||
|
||||
### Alliance Auth Project
|
||||
|
||||
```eval_rst
|
||||
.. warning::
|
||||
Before installing any Python packages please double-check that you have activated in the virtual environment. This is usually indicated by your command line in the terminal starting with: `(auth)`.
|
||||
```
|
||||
:::{warning}
|
||||
Before installing any Python packages please double-check that you have activated in the virtual environment. This is usually indicated by your command line in the terminal starting with: `(auth)`.
|
||||
:::
|
||||
|
||||
#### Install Python packages
|
||||
|
||||
Update & install basic tools before installing further Python packages:
|
||||
|
||||
```bash
|
||||
```shell
|
||||
pip install -U pip setuptools wheel
|
||||
```
|
||||
|
||||
You can install **Alliance Auth** with the following command. This will install AA, AA's Python dependencies, superlance for memory monitoring and gunicorn as a wsgi server
|
||||
|
||||
```bash
|
||||
```shell
|
||||
pip install allianceauth superlance gunicorn
|
||||
```
|
||||
|
||||
@ -409,13 +428,13 @@ pip install allianceauth superlance gunicorn
|
||||
|
||||
Now you need to create the Django project that will run **Alliance Auth**. Ensure you are in the allianceserver home directory by issuing:
|
||||
|
||||
```bash
|
||||
```shell
|
||||
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
|
||||
```shell
|
||||
allianceauth start myauth
|
||||
```
|
||||
|
||||
@ -423,7 +442,7 @@ allianceauth start myauth
|
||||
|
||||
Your settings file needs configuring:
|
||||
|
||||
```bash
|
||||
```shell
|
||||
nano myauth/myauth/settings/local.py
|
||||
```
|
||||
|
||||
@ -439,34 +458,36 @@ nano myauth/myauth/settings/local.py
|
||||
|
||||
Django needs to setup the database before it can start.
|
||||
|
||||
```bash
|
||||
```shell
|
||||
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
|
||||
```shell
|
||||
python /home/allianceserver/myauth/manage.py collectstatic --noinput
|
||||
```
|
||||
|
||||
Check to ensure your settings are valid.
|
||||
|
||||
```bash
|
||||
```shell
|
||||
python /home/allianceserver/myauth/manage.py check
|
||||
```
|
||||
|
||||
```eval_rst
|
||||
.. hint::
|
||||
If you are using root, ensure the allianceserver user has read/write permissions to this directory before proceeding::
|
||||
:::{hint}
|
||||
If you are using root, ensure the allianceserver user has read/write permissions to this directory before proceeding::
|
||||
|
||||
chown -R allianceserver:allianceserver /home/allianceserver/myauth
|
||||
```
|
||||
chown -R allianceserver:allianceserver /home/allianceserver/myauth
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
#### Setup 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
|
||||
```shell
|
||||
python /home/allianceserver/myauth/manage.py createsuperuser
|
||||
```
|
||||
|
||||
@ -488,72 +509,117 @@ The default configuration is good enough for most installations. Additional info
|
||||
|
||||
[Supervisor](http://supervisord.org/) is a process watchdog service: it makes sure other processes are started automatically and kept running. It can be used to automatically start the WSGI server and Celery workers for background tasks.
|
||||
|
||||
```eval_rst
|
||||
.. note::
|
||||
:::{note}
|
||||
You will need to exit the allianceserver user back to a user with sudo capabilities to install supervisor::
|
||||
|
||||
```bash
|
||||
exit
|
||||
```
|
||||
|
||||
Ubuntu 1804, 2004, 2204:
|
||||
:::
|
||||
|
||||
```bash
|
||||
::::{tabs}
|
||||
|
||||
:::{group-tab} Ubuntu 2004, 2204
|
||||
|
||||
```shell
|
||||
sudo apt-get install supervisor
|
||||
```
|
||||
|
||||
CentOS 7:
|
||||
:::
|
||||
:::{group-tab} CentOS 7
|
||||
|
||||
```bash
|
||||
```shell
|
||||
sudo dnf install supervisor
|
||||
```
|
||||
|
||||
```bash
|
||||
```shell
|
||||
sudo systemctl enable supervisord.service
|
||||
```
|
||||
|
||||
```bash
|
||||
```shell
|
||||
sudo systemctl start supervisord.service
|
||||
```
|
||||
|
||||
CentOS Stream 8, Stream 9:
|
||||
:::
|
||||
:::{group-tab} CentOS Stream 8
|
||||
|
||||
```bash
|
||||
```shell
|
||||
sudo dnf install supervisor
|
||||
```
|
||||
|
||||
```bash
|
||||
```shell
|
||||
sudo systemctl enable supervisord.service
|
||||
```
|
||||
|
||||
```bash
|
||||
```shell
|
||||
sudo systemctl start supervisord.service
|
||||
```
|
||||
|
||||
:::
|
||||
:::{group-tab} CentOS Stream 9
|
||||
|
||||
```shell
|
||||
sudo dnf install supervisor
|
||||
```
|
||||
|
||||
```shell
|
||||
sudo systemctl enable supervisord.service
|
||||
```
|
||||
|
||||
```shell
|
||||
sudo systemctl start supervisord.service
|
||||
```
|
||||
|
||||
:::
|
||||
::::
|
||||
|
||||
Once installed, it needs a configuration file to know which processes to watch. Your Alliance Auth project comes with a ready-to-use template which will ensure the Celery workers, Celery task scheduler and Gunicorn are all running.
|
||||
::::{tabs}
|
||||
|
||||
Ubuntu 1804, 2004:
|
||||
:::{group-tab} Ubuntu 2004, 2204
|
||||
|
||||
```bash
|
||||
```shell
|
||||
ln -s /home/allianceserver/myauth/supervisor.conf /etc/supervisor/conf.d/myauth.conf
|
||||
```
|
||||
|
||||
CentOS:
|
||||
:::
|
||||
:::{group-tab} CentOS 7
|
||||
|
||||
```bash
|
||||
```shell
|
||||
sudo ln -s /home/allianceserver/myauth/supervisor.conf /etc/supervisord.d/myauth.ini
|
||||
```
|
||||
|
||||
:::
|
||||
:::{group-tab} CentOS Stream 8
|
||||
|
||||
```shell
|
||||
sudo ln -s /home/allianceserver/myauth/supervisor.conf /etc/supervisord.d/myauth.ini
|
||||
```
|
||||
|
||||
:::
|
||||
:::{group-tab} CentOS Stream 9
|
||||
|
||||
```shell
|
||||
sudo ln -s /home/allianceserver/myauth/supervisor.conf /etc/supervisord.d/myauth.ini
|
||||
```
|
||||
|
||||
:::
|
||||
::::
|
||||
|
||||
Activate it with `sudo supervisorctl reload`.
|
||||
|
||||
You can check the status of the processes with `sudo 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. ::
|
||||
:::{note}
|
||||
Any time the code or your settings change you'll need to restart Gunicorn and Celery. ::
|
||||
|
||||
sudo supervisorctl restart myauth:
|
||||
```shell
|
||||
sudo supervisorctl restart myauth:
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
## Web server
|
||||
|
||||
Once installed, decide on whether you're going to use [NGINX](nginx.md) or [Apache](apache.md) and follow the respective guide.
|
||||
@ -566,42 +632,42 @@ Periodically [new releases](https://gitlab.com/allianceauth/allianceauth/tags) a
|
||||
|
||||
To update your install, swap to your allianceserver user
|
||||
|
||||
```bash
|
||||
```shell
|
||||
sudo su allianceserver
|
||||
```
|
||||
|
||||
Activate your virtual environment
|
||||
|
||||
```bash
|
||||
```shell
|
||||
source /home/allianceserver/venv/auth/bin/activate
|
||||
```
|
||||
|
||||
and update with:
|
||||
|
||||
```bash
|
||||
```shell
|
||||
pip install -U allianceauth
|
||||
```
|
||||
|
||||
Some releases come with changes to the base settings. Update your project's settings with:
|
||||
|
||||
```bash
|
||||
```shell
|
||||
allianceauth update /home/allianceserver/myauth
|
||||
```
|
||||
|
||||
Some releases come with new or changed models. Update your database to reflect this with:
|
||||
|
||||
```bash
|
||||
```shell
|
||||
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
|
||||
```shell
|
||||
python /home/allianceserver/myauth/manage.py collectstatic --noinput
|
||||
```
|
||||
|
||||
Always restart AA, Celery and Gunicorn after updating:
|
||||
|
||||
```bash
|
||||
```shell
|
||||
supervisorctl restart myauth:
|
||||
```
|
||||
|
||||
@ -9,25 +9,25 @@ If you're using a small VPS to host services with very limited memory, consider
|
||||
## Installation
|
||||
|
||||
Ubuntu 1804, 2004:
|
||||
```bash
|
||||
```shell
|
||||
apt-get install apache2
|
||||
```
|
||||
|
||||
CentOS 7:
|
||||
```bash
|
||||
```shell
|
||||
yum install httpd
|
||||
```
|
||||
Centos Stream 8, Stream 9
|
||||
```bash
|
||||
```shell
|
||||
dnf install httpd
|
||||
```
|
||||
|
||||
CentOS 7, Stream 8, Stream 9
|
||||
```bash
|
||||
```shell
|
||||
systemctl enable httpd
|
||||
```
|
||||
|
||||
```bash
|
||||
```shell
|
||||
systemctl start httpd
|
||||
```
|
||||
## Configuration
|
||||
@ -49,7 +49,7 @@ A virtual host for auth need only proxy requests to your WSGI server (Gunicorn i
|
||||
### Ubuntu
|
||||
|
||||
To proxy and modify headers a few mods need to be enabled.
|
||||
```bash
|
||||
```shell
|
||||
a2enmod proxy
|
||||
a2enmod proxy_http
|
||||
a2enmod headers
|
||||
@ -57,7 +57,7 @@ a2enmod headers
|
||||
|
||||
Create a new config file for auth e.g. `/etc/apache2/sites-available/myauth.conf` and fill out the virtual host configuration. To enable your config use `a2ensite myauth.conf` and then reload apache with `service apache2 reload`.
|
||||
|
||||
```eval_rst
|
||||
```{eval-rst}
|
||||
.. warning::
|
||||
In some scenarios, the Apache default page is still enabled. To disable it use::
|
||||
a2dissite 000-default.conf
|
||||
|
||||
@ -6,15 +6,13 @@ 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::
|
||||
:::{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
|
||||
.. note::
|
||||
:::{note}
|
||||
If you're using a virtual environment, activate it now::
|
||||
sudo su allianceserver
|
||||
source /home/allianceserver/venv/auth/bin/activate
|
||||
@ -22,7 +20,7 @@ Check out the full [Gunicorn docs](http://docs.gunicorn.org/en/latest/index.html
|
||||
|
||||
Install Gunicorn using pip
|
||||
|
||||
```bash
|
||||
```shell
|
||||
pip install gunicorn
|
||||
```
|
||||
|
||||
@ -38,7 +36,7 @@ If you are following this guide, we already use [Supervisor](allianceauth.md#sup
|
||||
|
||||
You'll want to edit `/etc/supervisor/conf.d/myauth.conf` (or whatever you want to call the config file)
|
||||
|
||||
```text
|
||||
```ini
|
||||
[program:gunicorn]
|
||||
user = allianceserver
|
||||
directory=/home/allianceserver/myauth/
|
||||
@ -97,6 +95,6 @@ Any web server capable of proxy passing should be able to sit in front of Gunico
|
||||
|
||||
In the past when you made changes you restarted the entire Apache server. This is no longer required. When you update or make configuration changes that ask you to restart Apache, instead you can just restart Gunicorn:
|
||||
|
||||
```bash
|
||||
```shell
|
||||
supervisorctl restart myauth:gunicorn
|
||||
```
|
||||
|
||||
@ -4,14 +4,13 @@ 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: 1
|
||||
```{toctree}
|
||||
:maxdepth: 1
|
||||
|
||||
allianceauth
|
||||
nginx
|
||||
apache
|
||||
gunicorn
|
||||
upgrade_python
|
||||
switch_to_non_root
|
||||
allianceauth
|
||||
nginx
|
||||
apache
|
||||
gunicorn
|
||||
upgrade_python
|
||||
switch_to_non_root
|
||||
```
|
||||
|
||||
@ -14,7 +14,7 @@ If you're converting from Apache, here are some things to consider.
|
||||
|
||||
Nginx is lightweight for a reason. It doesn't try to do everything internally and instead concentrates on just being a good HTTP server. This means that, unlike Apache, it won't automatically run PHP scripts via mod_php and doesn't have an internal WSGI server like mod_wsgi. That doesn't mean that it can't, just that it relies on external processes to run these instead. This might be good or bad depending on your outlook. It's good because it allows you to segment your applications, restarting Alliance Auth wont impact your PHP applications. On the other hand it means more config and more management of services. For some people it will be worth it, for others losing the centralised nature of Apache may not be worth it.
|
||||
|
||||
```eval_rst
|
||||
```{eval-rst}
|
||||
+-----------+----------------------------------------+
|
||||
| Apache | Nginx Replacement |
|
||||
+===========+========================================+
|
||||
@ -33,7 +33,7 @@ Install Nginx via your preferred package manager or other method. If you need he
|
||||
|
||||
Nginx needs to be able to read the folder containing your auth project's static files. `chown -R nginx:nginx /var/www/myauth/static`.
|
||||
|
||||
```eval_rst
|
||||
```{eval-rst}
|
||||
.. tip::
|
||||
Some specific distros may use ``www-data:www-data`` instead of ``nginx:nginx``, causing static files (images, stylesheets etc) not to appear. You can confirm what user Nginx will run under by checking either its base config file ``/etc/nginx/nginx.conf`` for the "user" setting, or once Nginx has started ``ps aux | grep nginx``.
|
||||
Adjust your chown commands to the correct user if needed.
|
||||
@ -45,24 +45,24 @@ You will need to have [Gunicorn](gunicorn.md) or some other WSGI server setup fo
|
||||
## Install
|
||||
|
||||
Ubuntu 1804, 2004, 2204:
|
||||
```bash
|
||||
```shell
|
||||
sudo apt-get install nginx
|
||||
```
|
||||
|
||||
CentOS 7
|
||||
```bash
|
||||
```shell
|
||||
sudo yum install nginx
|
||||
```
|
||||
|
||||
CentOS Stream 8, Stream 9:
|
||||
```bash
|
||||
```shell
|
||||
sudo dnf install nginx
|
||||
```
|
||||
|
||||
Create a config file in `/etc/nginx/sites-available` (`/etc/nginx/conf.d` on CentOS) and call it `alliance-auth.conf` or whatever your preferred name is.
|
||||
|
||||
Create a symbolic link to enable the site (not needed on CentOS):
|
||||
```bash
|
||||
```shell
|
||||
ln -s /etc/nginx/sites-available/alliance-auth.conf /etc/nginx/sites-enabled/
|
||||
```
|
||||
|
||||
|
||||
@ -4,8 +4,7 @@ This guide describes how to upgrade an existing Alliance Auth (AA) installation
|
||||
|
||||
This guide shares many similarities with the Alliance Auth install guide, but it is targeted towards existing installs needing to update.
|
||||
|
||||
```eval_rst
|
||||
.. note::
|
||||
:::{note}
|
||||
This guide will upgrade the software components only but not change any data or configuration.
|
||||
```
|
||||
|
||||
@ -16,20 +15,19 @@ To run AA with a newer Python 3 version than your system's default you need to i
|
||||
To install other Python versions than those included with your distribution, you need to add a new installation repository. Then you can install the specific Python 3 to your system.
|
||||
|
||||
Ubuntu 1804, 2004:
|
||||
```eval_rst
|
||||
.. note::
|
||||
:::{note}
|
||||
Ubuntu 2204 ships with Python 3.10 already
|
||||
```
|
||||
|
||||
```bash
|
||||
```shell
|
||||
sudo add-apt-repository ppa:deadsnakes/ppa
|
||||
```
|
||||
|
||||
```bash
|
||||
```shell
|
||||
sudo apt-get update
|
||||
```
|
||||
|
||||
```bash
|
||||
```shell
|
||||
sudo apt-get install python3.10 python3.10-dev python3.10-venv
|
||||
```
|
||||
|
||||
@ -37,37 +35,36 @@ CentOS 7:
|
||||
We need to build Python from source
|
||||
|
||||
Centos Stream 8/9:
|
||||
```eval_rst
|
||||
.. note::
|
||||
:::{note}
|
||||
A Python 3.9 Package is available for Stream 8 and 9. You _may_ use this instead of building your own package. But our documentation will assume Python3.10 and you may need to substitute as neccessary
|
||||
sudo dnf install python39 python39-devel
|
||||
```
|
||||
|
||||
```bash
|
||||
```shell
|
||||
cd ~
|
||||
```
|
||||
|
||||
```bash
|
||||
```shell
|
||||
sudo yum install gcc openssl-devel bzip2-devel libffi-devel wget
|
||||
```
|
||||
|
||||
```bash
|
||||
```shell
|
||||
wget https://www.python.org/ftp/python/3.10.5/Python-3.10.5.tgz
|
||||
```
|
||||
|
||||
```bash
|
||||
```shell
|
||||
tar xvf Python-3.10.5.tgz
|
||||
```
|
||||
|
||||
```bash
|
||||
```shell
|
||||
cd Python-3.10.5/
|
||||
```
|
||||
|
||||
```bash
|
||||
```shell
|
||||
./configure --enable-optimizations --enable-shared
|
||||
```
|
||||
|
||||
```bash
|
||||
```shell
|
||||
sudo make altinstall
|
||||
```
|
||||
## Preparing your venv
|
||||
@ -76,8 +73,7 @@ Before updating your venv it is important to make sure that your current install
|
||||
|
||||
Start by navigating to your main project folder (the one that has `manage.py` in it). If you followed the default installation the path is: `/home/allianceserver/myauth`
|
||||
|
||||
```eval_rst
|
||||
.. note::
|
||||
:::{note}
|
||||
If you installed Alliance Auth under the allianceserver user, as reccommended. Remember to switch users for easier permission management::
|
||||
|
||||
sudo su allianceserver
|
||||
@ -85,7 +81,7 @@ Start by navigating to your main project folder (the one that has `manage.py` in
|
||||
|
||||
Activate your venv:
|
||||
|
||||
```bash
|
||||
```shell
|
||||
source /home/allianceserver/venv/auth/bin/activate
|
||||
```
|
||||
|
||||
@ -93,23 +89,23 @@ source /home/allianceserver/venv/auth/bin/activate
|
||||
|
||||
Make sure to upgrade AA to the newest version:
|
||||
|
||||
```bash
|
||||
```shell
|
||||
pip install -U allianceauth
|
||||
```
|
||||
|
||||
Run migrations and collectstatic.
|
||||
|
||||
```bash
|
||||
```shell
|
||||
python manage.py migrate
|
||||
```
|
||||
|
||||
```bash
|
||||
```shell
|
||||
python manage.py collectstatic
|
||||
```
|
||||
|
||||
Restart your AA supervisor:
|
||||
|
||||
```bash
|
||||
```shell
|
||||
supervisorctl restart myauth:
|
||||
```
|
||||
|
||||
@ -119,23 +115,23 @@ You also need to upgrade all additional apps to their newest version that you ha
|
||||
|
||||
If you unsure which apps you have installed from repos check `INSTALLED_APPS` in your settings. Alternatively run this command to get a list all apps in your venv.
|
||||
|
||||
```bash
|
||||
```shell
|
||||
pip list
|
||||
```
|
||||
|
||||
Repeat as needed for your apps
|
||||
|
||||
```bash
|
||||
```shell
|
||||
pip install -U APP_NAME
|
||||
```
|
||||
|
||||
Make sure to run migrations and collect static files for all upgraded apps.
|
||||
|
||||
```bash
|
||||
```shell
|
||||
python manage.py migrate
|
||||
```
|
||||
|
||||
```bash
|
||||
```shell
|
||||
python manage.py collectstatic
|
||||
```
|
||||
### Restart and final check
|
||||
@ -144,13 +140,13 @@ Do a final restart of your AA supervisors and make sure your installation is sti
|
||||
|
||||
For a final check that they are no issues - e.g. any outstanding migrations - run this command:
|
||||
|
||||
```bash
|
||||
```shell
|
||||
python manage.py check
|
||||
```
|
||||
|
||||
If you get the following result you are good to go. Otherwise make sure to fix any issues first before proceeding.
|
||||
|
||||
```bash
|
||||
```shell
|
||||
System check identified no issues (0 silenced).
|
||||
```
|
||||
|
||||
@ -160,7 +156,7 @@ Make sure you are in your venv!
|
||||
|
||||
First we create a list of all installed packages in your venv. You can use this list later as reference to see what packages should be installed.
|
||||
|
||||
```bash
|
||||
```shell
|
||||
pip freeze > requirements.txt
|
||||
```
|
||||
|
||||
@ -169,29 +165,28 @@ At this point we recommend creating a list of the additional packages that you n
|
||||
- Community AA apps (e.g. aa-structures)
|
||||
- Additional tools you are using (e.g. flower, django-extensions)
|
||||
|
||||
```eval_rst
|
||||
```{eval-rst}
|
||||
.. hint::
|
||||
While `requirements.txt` will contain a complete list of your packages, it will also contain many packages that are automatically installed as dependencies and don't need be manually reinstalled.
|
||||
```
|
||||
|
||||
```eval_rst
|
||||
.. note::
|
||||
:::{note}
|
||||
Some guide on the Internet will suggest to use use the requirements.txt file to recreate a venv. This is indeed possible, but only works if all packages can be installed from PyPI. Since most community apps are installed directly from repos this guide will not follow that approach.
|
||||
```
|
||||
|
||||
Leave the venv and shutdown all AA services:
|
||||
|
||||
```bash
|
||||
```shell
|
||||
deactivate
|
||||
```
|
||||
|
||||
```bash
|
||||
```shell
|
||||
supervisorctl stop myauth:
|
||||
```
|
||||
|
||||
Rename and keep your old venv so we have a fallback in case of some unforeseeable issues:
|
||||
|
||||
```bash
|
||||
```shell
|
||||
mv /home/allianceserver/venv/auth /home/allianceserver/venv/auth_old
|
||||
```
|
||||
|
||||
@ -199,11 +194,11 @@ mv /home/allianceserver/venv/auth /home/allianceserver/venv/auth_old
|
||||
|
||||
Now let's create our new venv with Python 3.10 and activate it:
|
||||
|
||||
```bash
|
||||
```shell
|
||||
python3.10 -m venv /home/allianceserver/venv/auth
|
||||
```
|
||||
|
||||
```bash
|
||||
```shell
|
||||
source /home/allianceserver/venv/auth/bin/activate
|
||||
```
|
||||
|
||||
@ -213,17 +208,17 @@ Now we need to reinstall all packages into your new venv.
|
||||
|
||||
### Install basic packages
|
||||
|
||||
```bash
|
||||
```shell
|
||||
pip install -U pip setuptools wheel
|
||||
```
|
||||
|
||||
### Installing AA & Gunicorn
|
||||
|
||||
```bash
|
||||
```shell
|
||||
pip install allianceauth
|
||||
```
|
||||
|
||||
```bash
|
||||
```shell
|
||||
pip install gunicorn
|
||||
```
|
||||
|
||||
@ -235,13 +230,13 @@ Use the list of packages you created earlier as a checklist. Alternatively you u
|
||||
|
||||
To check whether you are missing any apps you can also run the check command:
|
||||
|
||||
```bash
|
||||
```shell
|
||||
python manage.py check
|
||||
```
|
||||
|
||||
Note: In case you forget to install an app you will get this error
|
||||
|
||||
```bash
|
||||
```shell
|
||||
ModuleNotFoundError: No module named 'xyz'
|
||||
```
|
||||
|
||||
@ -251,7 +246,7 @@ Note that you should not need to run any migrations unless you forgot to upgrade
|
||||
|
||||
After you have completed installing all packages just start your AA supervisor again.
|
||||
|
||||
```bash
|
||||
```shell
|
||||
supervisorctl start myauth:
|
||||
```
|
||||
|
||||
@ -263,7 +258,7 @@ In case you run into any major issue you can always switch back to your initial
|
||||
|
||||
Before you start double-check that you still have your old venv for auth:
|
||||
|
||||
```bash
|
||||
```shell
|
||||
ls /home/allianceserver/venv/auth /home/allianceserver/venv
|
||||
```
|
||||
|
||||
@ -274,18 +269,18 @@ If the output shows these two folders you should be safe to proceed:
|
||||
|
||||
Run these commands to remove your current venv and switch back to the old venv for auth:
|
||||
|
||||
```bash
|
||||
```shell
|
||||
supervisorctl stop myauth:
|
||||
```
|
||||
|
||||
```bash
|
||||
```shell
|
||||
rm -rf /home/allianceserver/venv/auth
|
||||
```
|
||||
|
||||
```bash
|
||||
```shell
|
||||
mv /home/allianceserver/venv/auth_old /home/allianceserver/venv/auth
|
||||
```
|
||||
|
||||
```bash
|
||||
```shell
|
||||
supervisorctl start myauth:
|
||||
```
|
||||
|
||||
@ -13,8 +13,7 @@ Your auth project is just a regular Django project - you can add in [other Djang
|
||||
|
||||
The following instructions will explain how you can remove an app properly fom your Alliance Auth installation.
|
||||
|
||||
```eval_rst
|
||||
.. note::
|
||||
:::{note}
|
||||
We recommend following these instructions to avoid dangling foreign keys or orphaned Python packages on your system, which might cause conflicts with other apps down the road.
|
||||
|
||||
```
|
||||
@ -27,7 +26,7 @@ First, we want to remove the app related tables from the database.
|
||||
|
||||
Let's first try the automatic approach by running the following command:
|
||||
|
||||
```sh
|
||||
```shell
|
||||
python manage.py migrate appname zero
|
||||
```
|
||||
|
||||
@ -39,32 +38,32 @@ If that did not work and you got error messages, you will need to remove the tab
|
||||
|
||||
First, tell Django that these migrations are no longer in effect (note the additional `--fake`):
|
||||
|
||||
```sh
|
||||
```shell
|
||||
python manage.py migrate appname zero --fake
|
||||
```
|
||||
|
||||
Then, open the mysql tool and connect to your Alliance Auth database:
|
||||
|
||||
```sh
|
||||
```shell
|
||||
sudo mysql -u root
|
||||
use alliance_auth;
|
||||
```
|
||||
|
||||
Next disable foreign key check. This makes it much easier to drop tables in any order.
|
||||
|
||||
```sh
|
||||
```shell
|
||||
SET FOREIGN_KEY_CHECKS=0;
|
||||
```
|
||||
|
||||
Then get a list of all tables. All tables belonging to the app in question will start with `appname_`.
|
||||
|
||||
```sh
|
||||
```shell
|
||||
show tables;
|
||||
```
|
||||
|
||||
Now, drop the tables from the app one by one like so:
|
||||
|
||||
```sh
|
||||
```shell
|
||||
drop table appname_model_1;
|
||||
drop table appname_model_2;
|
||||
...
|
||||
@ -72,7 +71,7 @@ drop table appname_model_2;
|
||||
|
||||
And finally, but very importantly, re-enable foreign key checks again and then exit:
|
||||
|
||||
```sh
|
||||
```shell
|
||||
SET FOREIGN_KEY_CHECKS=1;
|
||||
exit;
|
||||
```
|
||||
@ -85,7 +84,7 @@ Once the tables have been removed, you you can remove the app from Alliance Auth
|
||||
|
||||
Finally, we want to remove the app's Python package. For that run the following command:
|
||||
|
||||
```sh
|
||||
```shell
|
||||
pip uninstall app-package-name
|
||||
```
|
||||
|
||||
|
||||
@ -2,12 +2,11 @@
|
||||
|
||||
In the maintenance chapter you find details about where important log files are found, how you can customize your AA installation and how to solve common issues.
|
||||
|
||||
```eval_rst
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
```{toctree}
|
||||
:maxdepth: 1
|
||||
|
||||
apps
|
||||
project
|
||||
troubleshooting
|
||||
tuning/index
|
||||
apps
|
||||
project
|
||||
troubleshooting
|
||||
tuning/index
|
||||
```
|
||||
|
||||
@ -24,7 +24,7 @@ Make sure the background processes are running: `supervisorctl status myauth:`.
|
||||
|
||||
Stop celery workers with `supervisorctl stop myauth:worker` then clear the queue:
|
||||
|
||||
```bash
|
||||
```shell
|
||||
redis-cli FLUSHALL
|
||||
celery -A myauth worker --purge
|
||||
```
|
||||
@ -49,7 +49,7 @@ Gunicorn needs to have context for its running location, `/home/alllianceserver/
|
||||
|
||||
Migrations may about with the following error message:
|
||||
|
||||
```bash
|
||||
```shell
|
||||
Specified key was too long; max key length is 767 bytes
|
||||
```
|
||||
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
# Celery
|
||||
|
||||
```eval_rst
|
||||
```{eval-rst}
|
||||
.. hint::
|
||||
Most tunings will require a change to your supervisor configuration in your `supervisor.conf` file. Note that you need to restart the supervisor daemon in order for any changes to take effect. And before restarting the daemon you may want to make sure your supervisors stop gracefully:(Ubuntu):
|
||||
|
||||
@ -14,13 +14,13 @@
|
||||
|
||||
By default task logging is deactivated. Enabling task logging allows you to monitor what tasks are doing in addition to getting all warnings and error messages. To enable info logging for tasks add the following to the command configuration of your worker in the `supervisor.conf` file:
|
||||
|
||||
```text
|
||||
```ini
|
||||
-l info
|
||||
```
|
||||
|
||||
Full example:
|
||||
|
||||
```text
|
||||
```ini
|
||||
command=/home/allianceserver/venv/auth/bin/celery -A myauth worker -l info
|
||||
```
|
||||
|
||||
@ -28,7 +28,7 @@ command=/home/allianceserver/venv/auth/bin/celery -A myauth worker -l info
|
||||
|
||||
Celery workers often have memory leaks and will therefore grow in size over time. While the Alliance Auth team is working hard to ensure Auth is free of memory leaks some may still be cause by bugs in different versions of libraries or community apps. It is therefore good practice to enable features that protect against potential memory leaks.
|
||||
|
||||
```eval_rst
|
||||
```{eval-rst}
|
||||
.. hint::
|
||||
The 256 MB limit is just an example and should be adjusted to your system configuration. We would suggest to not go below 128MB though, since new workers start with around 80 MB already. Also take into consideration that this value is per worker and that you may have more than one worker running in your system.
|
||||
```
|
||||
@ -42,13 +42,13 @@ This is not a built in feature and requires the 3rd party extension [superlance]
|
||||
|
||||
To setup install superlance into your venv with:
|
||||
|
||||
```bash
|
||||
```shell
|
||||
pip install superlance
|
||||
```
|
||||
|
||||
You can then add `memmon` to your `supervisor.conf`:
|
||||
|
||||
```text
|
||||
```ini
|
||||
[eventlistener:memmon]
|
||||
command=/home/allianceserver/venv/auth/bin/memmon -p worker=256MB
|
||||
directory=/home/allianceserver/myauth
|
||||
@ -67,7 +67,7 @@ Celery tasks are designed to run concurrently, so one obvious way to increase ta
|
||||
|
||||
The easiest way to increate throughput can be achieved by increasing the `numprocs` parameter of the suprvisor process. For example:
|
||||
|
||||
```text
|
||||
```ini
|
||||
[program:worker]
|
||||
...
|
||||
numprocs=2
|
||||
@ -83,14 +83,14 @@ numprocs * concurency = workers
|
||||
|
||||
increasing this number will require a modification to the memmon settings as each `numproc` worker will get a unique name for example with `numproc=3`
|
||||
|
||||
```text
|
||||
```ini
|
||||
[eventlistener:memmon]
|
||||
...
|
||||
command=... -p worker_00=256MB -p worker_01=256MB -p worker_02=256MB
|
||||
...
|
||||
```
|
||||
|
||||
```eval_rst
|
||||
```{eval-rst}
|
||||
.. hint::
|
||||
You will want to experiment with different settings to find the optimal. One way to generate task load and verify your configuration is to run a model update with the following command:
|
||||
|
||||
@ -104,11 +104,11 @@ command=... -p worker_00=256MB -p worker_01=256MB -p worker_02=256MB
|
||||
|
||||
This can be achieved by the setting the concurrency parameter of the celery worker to a higher number. For example:
|
||||
|
||||
```text
|
||||
```ini
|
||||
--concurrency=10
|
||||
```
|
||||
|
||||
```eval_rst
|
||||
```{eval-rst}
|
||||
.. hint::
|
||||
The optimal number will hugely depend on your individual system configuration and you may want to experiment with different settings to find the optimal. One way to generate task load and verify your configuration is to run a model update with the following command:
|
||||
|
||||
@ -118,7 +118,7 @@ This can be achieved by the setting the concurrency parameter of the celery work
|
||||
|
||||
```
|
||||
|
||||
```eval_rst
|
||||
```{eval-rst}
|
||||
.. hint::
|
||||
The optimal number of concurrent workers will be different for every system and we recommend experimenting with different figures to find the optimal for your system. Note, that the example of 10 threads is conservative and should work even with smaller systems.
|
||||
```
|
||||
|
||||
@ -8,6 +8,6 @@ The number you set this to will depend on your own server environment, how many
|
||||
|
||||
For example to get 5 workers change the setting `--workers=5` in your `supervisor.conf` file and then reload the supervisor with the following command to activate the change (Ubuntu):
|
||||
|
||||
```bash
|
||||
```shell
|
||||
systemctl restart supervisor
|
||||
```
|
||||
|
||||
@ -2,16 +2,15 @@
|
||||
|
||||
The official installation guide will install a stable version of Alliance Auth that will work fine for most cases. However, there are a lot of levels that can be used to optimize a system. For example some installations may we short on RAM and want to reduce the total memory footprint, even though that may reduce system performance. Others are fine with further increasing the memory footprint to get better system performance.
|
||||
|
||||
```eval_rst
|
||||
```{eval-rst}
|
||||
.. warning::
|
||||
Tuning usually has benefits and costs and should only be performed by experienced Linux administrators who understand the impact of tuning decisions on to their system.
|
||||
```
|
||||
|
||||
```eval_rst
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
```{toctree}
|
||||
:maxdepth: 1
|
||||
|
||||
gunicorn
|
||||
celery
|
||||
redis
|
||||
gunicorn
|
||||
celery
|
||||
redis
|
||||
```
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user