From ffb526ab0c6c1e60f30227e726e649ddc99e39a3 Mon Sep 17 00:00:00 2001 From: Ariel Rin Date: Fri, 27 Oct 2023 16:37:53 +1000 Subject: [PATCH] find and replace fixes, will introduce errors --- docs/customizing/index.md | 12 +- docs/development/aa_core/documentation.md | 15 +- docs/development/aa_core/index.md | 9 +- docs/development/custom/index.md | 13 +- .../custom/integrating-services.md | 2 +- docs/development/custom/menu-hooks.md | 2 +- docs/development/custom/url-hooks.md | 5 +- .../dev_setup/aa-dev-setup-wsl-vsc-v2.md | 69 ++- docs/development/dev_setup/index.md | 7 +- docs/development/index.md | 13 +- docs/development/tech_docu/api/index.md | 21 +- docs/development/tech_docu/celery.md | 13 +- docs/development/tech_docu/index.md | 13 +- docs/features/apps/autogroups.md | 7 +- docs/features/apps/corpstats.md | 2 +- docs/features/apps/fleetactivitytracking.md | 2 +- docs/features/apps/hrapplications.md | 2 +- docs/features/apps/index.md | 21 +- docs/features/apps/optimer.md | 2 +- docs/features/apps/permissions_tool.md | 2 +- docs/features/apps/srp.md | 2 +- docs/features/apps/timerboard.md | 2 +- docs/features/core/admin_site.md | 7 +- docs/features/core/analytics.md | 2 +- docs/features/core/dashboard.md | 2 +- docs/features/core/groups.md | 15 +- docs/features/core/index.md | 17 +- docs/features/index.md | 15 +- docs/features/services/discord.md | 22 +- docs/features/services/discourse.md | 16 +- docs/features/services/index.md | 30 +- docs/features/services/mumble.md | 47 +- docs/features/services/nameformats.md | 11 +- docs/features/services/openfire.md | 16 +- docs/features/services/permissions.md | 4 +- docs/features/services/phpbb3.md | 16 +- docs/features/services/smf.md | 10 +- docs/features/services/teamspeak3.md | 18 +- docs/features/services/xenforo.md | 2 +- docs/index.md | 21 +- docs/installation/allianceauth.md | 474 ++++++++++-------- docs/installation/apache.md | 14 +- docs/installation/gunicorn.md | 12 +- docs/installation/index.md | 17 +- docs/installation/nginx.md | 12 +- docs/installation/upgrade_python.md | 93 ++-- docs/maintenance/apps.md | 19 +- docs/maintenance/index.md | 13 +- docs/maintenance/troubleshooting.md | 4 +- docs/maintenance/tuning/celery.md | 24 +- docs/maintenance/tuning/gunicorn.md | 2 +- docs/maintenance/tuning/index.md | 13 +- 52 files changed, 615 insertions(+), 589 deletions(-) diff --git a/docs/customizing/index.md b/docs/customizing/index.md index 3ff85913..2fb9de6e 100644 --- a/docs/customizing/index.md +++ b/docs/customizing/index.md @@ -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 ``` @@ -99,11 +99,11 @@ wget ` tag: -```sh +```shell nano /home/allianceserver/myauth/myauth/templates/allianceauth/side-menu.html ``` -```jinja +```django
  • Google @@ -111,7 +111,7 @@ nano /home/allianceserver/myauth/myauth/templates/allianceauth/side-menu.html
    • ``` -```eval_rst +```{eval-rst} .. hint:: You can find other icons with a matching style on the `Font Awesome site `_ . AA currently uses Font Awesome version 5. You also want to keep the ``fa-fw`` tag to ensure all icons have the same width. ``` diff --git a/docs/development/aa_core/documentation.md b/docs/development/aa_core/documentation.md index 0d443213..a72f6055 100644 --- a/docs/development/aa_core/documentation.md +++ b/docs/development/aa_core/documentation.md @@ -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. diff --git a/docs/development/aa_core/index.md b/docs/development/aa_core/index.md index 836a5a15..1c3a2883 100644 --- a/docs/development/aa_core/index.md +++ b/docs/development/aa_core/index.md @@ -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 ``` diff --git a/docs/development/custom/index.md b/docs/development/custom/index.md index 72882345..46841730 100644 --- a/docs/development/custom/index.md +++ b/docs/development/custom/index.md @@ -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 ``` diff --git a/docs/development/custom/integrating-services.md b/docs/development/custom/integrating-services.md index 3c28d8e4..f829626f 100644 --- a/docs/development/custom/integrating-services.md +++ b/docs/development/custom/integrating-services.md @@ -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. ``` diff --git a/docs/development/custom/menu-hooks.md b/docs/development/custom/menu-hooks.md index 04efc38a..2284a2ff 100644 --- a/docs/development/custom/menu-hooks.md +++ b/docs/development/custom/menu-hooks.md @@ -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. diff --git a/docs/development/custom/url-hooks.md b/docs/development/custom/url-hooks.md index 1c43544a..ffe8fdf3 100644 --- a/docs/development/custom/url-hooks.md +++ b/docs/development/custom/url-hooks.md @@ -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: ``` diff --git a/docs/development/dev_setup/aa-dev-setup-wsl-vsc-v2.md b/docs/development/dev_setup/aa-dev-setup-wsl-vsc-v2.md index ab3b8217..14429e9f 100644 --- a/docs/development/dev_setup/aa-dev-setup-wsl-vsc-v2.md +++ b/docs/development/dev_setup/aa-dev-setup-wsl-vsc-v2.md @@ -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 `_ 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 ``` diff --git a/docs/development/dev_setup/index.md b/docs/development/dev_setup/index.md index 0b9be3be..cda0fb7c 100644 --- a/docs/development/dev_setup/index.md +++ b/docs/development/dev_setup/index.md @@ -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 ``` diff --git a/docs/development/index.md b/docs/development/index.md index 05636730..40ce9551 100644 --- a/docs/development/index.md +++ b/docs/development/index.md @@ -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 ``` diff --git a/docs/development/tech_docu/api/index.md b/docs/development/tech_docu/api/index.md index 23e3018c..87c6994a 100644 --- a/docs/development/tech_docu/api/index.md +++ b/docs/development/tech_docu/api/index.md @@ -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 ``` diff --git a/docs/development/tech_docu/celery.md b/docs/development/tech_docu/celery.md index e406c867..53c4b781 100644 --- a/docs/development/tech_docu/celery.md +++ b/docs/development/tech_docu/celery.md @@ -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 `_ for details. ``` diff --git a/docs/development/tech_docu/index.md b/docs/development/tech_docu/index.md index 578df28d..e544eead 100644 --- a/docs/development/tech_docu/index.md +++ b/docs/development/tech_docu/index.md @@ -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 ``` diff --git a/docs/features/apps/autogroups.md b/docs/features/apps/autogroups.md index 4dd4ce5a..b6db021b 100644 --- a/docs/features/apps/autogroups.md +++ b/docs/features/apps/autogroups.md @@ -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: ![Create Autogroup page](/_static/images/features/apps/autogroups/group-creation.png) -```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 | +===========================================+==================+================+ diff --git a/docs/features/apps/corpstats.md b/docs/features/apps/corpstats.md index b25f1f3c..215abaeb 100644 --- a/docs/features/apps/corpstats.md +++ b/docs/features/apps/corpstats.md @@ -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 | +=======================================+==================+====================================================+ diff --git a/docs/features/apps/fleetactivitytracking.md b/docs/features/apps/fleetactivitytracking.md index f0556105..c7e69810 100644 --- a/docs/features/apps/fleetactivitytracking.md +++ b/docs/features/apps/fleetactivitytracking.md @@ -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 | +=======================================+==================+==========================================================================+ diff --git a/docs/features/apps/hrapplications.md b/docs/features/apps/hrapplications.md index 517803d3..6f01c6ff 100644 --- a/docs/features/apps/hrapplications.md +++ b/docs/features/apps/hrapplications.md @@ -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 | +=======================================+==================+====================================================+ diff --git a/docs/features/apps/index.md b/docs/features/apps/index.md index 21f77d4c..084b4efb 100644 --- a/docs/features/apps/index.md +++ b/docs/features/apps/index.md @@ -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 ``` diff --git a/docs/features/apps/optimer.md b/docs/features/apps/optimer.md index d2c7020e..91bbb3e2 100644 --- a/docs/features/apps/optimer.md +++ b/docs/features/apps/optimer.md @@ -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 | +=======================================+==================+==========================================================================+ diff --git a/docs/features/apps/permissions_tool.md b/docs/features/apps/permissions_tool.md index b262a5eb..e25a914f 100644 --- a/docs/features/apps/permissions_tool.md +++ b/docs/features/apps/permissions_tool.md @@ -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 | +=======================================+==================+==========================================================================+ diff --git a/docs/features/apps/srp.md b/docs/features/apps/srp.md index cf2a8ce7..7663bb04 100644 --- a/docs/features/apps/srp.md +++ b/docs/features/apps/srp.md @@ -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 | +======================+==================+============================================================+ diff --git a/docs/features/apps/timerboard.md b/docs/features/apps/timerboard.md index 24cc1df1..6a134b2c 100644 --- a/docs/features/apps/timerboard.md +++ b/docs/features/apps/timerboard.md @@ -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 | +=======================================+==================+==========================================================================+ diff --git a/docs/features/core/admin_site.md b/docs/features/core/admin_site.md index 2ab8d1ff..d7adce80 100644 --- a/docs/features/core/admin_site.md +++ b/docs/features/core/admin_site.md @@ -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. ``` diff --git a/docs/features/core/analytics.md b/docs/features/core/analytics.md index 0ee03f8a..78761cdd 100644 --- a/docs/features/core/analytics.md +++ b/docs/features/core/analytics.md @@ -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: diff --git a/docs/features/core/dashboard.md b/docs/features/core/dashboard.md index 57a6d536..037fc547 100644 --- a/docs/features/core/dashboard.md +++ b/docs/features/core/dashboard.md @@ -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 | +=====================================================+=========================================================================+===========+ diff --git a/docs/features/core/groups.md b/docs/features/core/groups.md index 2868ca4d..2de54a61 100644 --- a/docs/features/core/groups.md +++ b/docs/features/core/groups.md @@ -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 | +================================+===================+====================================================================================+ diff --git a/docs/features/core/index.md b/docs/features/core/index.md index 02007bd6..06428136 100644 --- a/docs/features/core/index.md +++ b/docs/features/core/index.md @@ -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 ``` diff --git a/docs/features/index.md b/docs/features/index.md index b2eee634..2fd59d78 100644 --- a/docs/features/index.md +++ b/docs/features/index.md @@ -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 ``` diff --git a/docs/features/services/discord.md b/docs/features/services/discord.md index 72159c56..0ffed134 100644 --- a/docs/features/services/discord.md +++ b/docs/features/services/discord.md @@ -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 | +=======================================+==================+==========================================================================+ diff --git a/docs/features/services/discourse.md b/docs/features/services/discourse.md index f451282b..e66a112f 100644 --- a/docs/features/services/discourse.md +++ b/docs/features/services/discourse.md @@ -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 | +=======================================+==================+==========================================================================+ diff --git a/docs/features/services/index.md b/docs/features/services/index.md index 3c64f848..af29780d 100644 --- a/docs/features/services/index.md +++ b/docs/features/services/index.md @@ -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 ``` diff --git a/docs/features/services/mumble.md b/docs/features/services/mumble.md index d0c754b7..ffc4c8f7 100644 --- a/docs/features/services/mumble.md +++ b/docs/features/services/mumble.md @@ -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 ``` diff --git a/docs/features/services/nameformats.md b/docs/features/services/nameformats.md index 82f3c95f..549939ae 100644 --- a/docs/features/services/nameformats.md +++ b/docs/features/services/nameformats.md @@ -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. ``` diff --git a/docs/features/services/openfire.md b/docs/features/services/openfire.md index 27f10a28..6fb345cd 100644 --- a/docs/features/services/openfire.md +++ b/docs/features/services/openfire.md @@ -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 | +=======================================+==================+==========================================================================+ diff --git a/docs/features/services/permissions.md b/docs/features/services/permissions.md index 847bc364..ff4b702c 100644 --- a/docs/features/services/permissions.md +++ b/docs/features/services/permissions.md @@ -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. ``` diff --git a/docs/features/services/phpbb3.md b/docs/features/services/phpbb3.md index e244949e..aea7e2f5 100644 --- a/docs/features/services/phpbb3.md +++ b/docs/features/services/phpbb3.md @@ -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 | +=======================================+==================+==========================================================================+ diff --git a/docs/features/services/smf.md b/docs/features/services/smf.md index b0d3dffd..f55a3b19 100644 --- a/docs/features/services/smf.md +++ b/docs/features/services/smf.md @@ -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 | +=======================================+==================+==========================================================================+ diff --git a/docs/features/services/teamspeak3.md b/docs/features/services/teamspeak3.md index 3394d284..fed2b60e 100644 --- a/docs/features/services/teamspeak3.md +++ b/docs/features/services/teamspeak3.md @@ -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 | +=======================================+==================+==========================================================================+ diff --git a/docs/features/services/xenforo.md b/docs/features/services/xenforo.md index b17f38db..0412e2c2 100644 --- a/docs/features/services/xenforo.md +++ b/docs/features/services/xenforo.md @@ -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 | +=======================================+==================+==========================================================================+ diff --git a/docs/index.md b/docs/index.md index 2ddb046b..f3e9d490 100644 --- a/docs/index.md +++ b/docs/index.md @@ -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 ``` diff --git a/docs/installation/allianceauth.md b/docs/installation/allianceauth.md index 018650a9..81d65b28 100644 --- a/docs/installation/allianceauth.md +++ b/docs/installation/allianceauth.md @@ -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 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 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 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 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. +::: 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: ``` diff --git a/docs/installation/apache.md b/docs/installation/apache.md index 79f8c615..36ee6953 100644 --- a/docs/installation/apache.md +++ b/docs/installation/apache.md @@ -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 diff --git a/docs/installation/gunicorn.md b/docs/installation/gunicorn.md index 2267945f..a2697164 100644 --- a/docs/installation/gunicorn.md +++ b/docs/installation/gunicorn.md @@ -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 ``` diff --git a/docs/installation/index.md b/docs/installation/index.md index f9b43ecb..41e25b2e 100644 --- a/docs/installation/index.md +++ b/docs/installation/index.md @@ -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 ``` diff --git a/docs/installation/nginx.md b/docs/installation/nginx.md index c47af9d1..3c8f5b2a 100644 --- a/docs/installation/nginx.md +++ b/docs/installation/nginx.md @@ -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/ ``` diff --git a/docs/installation/upgrade_python.md b/docs/installation/upgrade_python.md index 2853f736..ac0f4f0c 100644 --- a/docs/installation/upgrade_python.md +++ b/docs/installation/upgrade_python.md @@ -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: ``` diff --git a/docs/maintenance/apps.md b/docs/maintenance/apps.md index 59fafcf1..a9ce6101 100644 --- a/docs/maintenance/apps.md +++ b/docs/maintenance/apps.md @@ -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 ``` diff --git a/docs/maintenance/index.md b/docs/maintenance/index.md index 7b99b061..8d8b6cf5 100644 --- a/docs/maintenance/index.md +++ b/docs/maintenance/index.md @@ -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 ``` diff --git a/docs/maintenance/troubleshooting.md b/docs/maintenance/troubleshooting.md index c64b10bf..c81ae285 100644 --- a/docs/maintenance/troubleshooting.md +++ b/docs/maintenance/troubleshooting.md @@ -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 ``` diff --git a/docs/maintenance/tuning/celery.md b/docs/maintenance/tuning/celery.md index 8735c177..83159c76 100644 --- a/docs/maintenance/tuning/celery.md +++ b/docs/maintenance/tuning/celery.md @@ -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. ``` diff --git a/docs/maintenance/tuning/gunicorn.md b/docs/maintenance/tuning/gunicorn.md index 8cdef965..5c856c34 100644 --- a/docs/maintenance/tuning/gunicorn.md +++ b/docs/maintenance/tuning/gunicorn.md @@ -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 ``` diff --git a/docs/maintenance/tuning/index.md b/docs/maintenance/tuning/index.md index 9acf1909..f2a53b53 100644 --- a/docs/maintenance/tuning/index.md +++ b/docs/maintenance/tuning/index.md @@ -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 ```