Expand Tuning Doccs

.pre-commit-config.yaml

@@ -74,10 +74,15 @@ repos:
             \.mo|
             swagger\.json
           )
-
+  - repo: https://github.com/igorshubovych/markdownlint-cli
+    rev: v0.41.0
+    hooks:
+      - id: markdownlint
+        args:
+          - --disable=MD013
   # Infrastructure
   - repo: https://github.com/tox-dev/pyproject-fmt
-    rev: 2.0.3
+    rev: 2.1.3
     hooks:
       - id: pyproject-fmt
         name: pyproject.toml formatter
@@ -87,7 +92,7 @@ repos:
         additional_dependencies:
           - tox==4.15.0 # https://github.com/tox-dev/tox/releases/latest
   - repo: https://github.com/abravalheri/validate-pyproject
-    rev: v0.17
+    rev: v0.18
     hooks:
       - id: validate-pyproject
         name: Validate pyproject.toml

docker/conf/nginx.conf

@@ -1,20 +1,28 @@
-server {
+events {}
-    listen 80;
+http {
-    location = /favicon.ico { access_log off; log_not_found off; }
+    include       mime.types;
-    location /static {
+    default_type  application/octet-stream;
-        alias /var/www/myauth/static;
-        autoindex off;
-    }
 
-    location /robots.txt {
+    sendfile        on;
-        alias /var/www/myauth/static/robots.txt;
-    }
 
-    location / {
+    server {
-        proxy_pass http://allianceauth_gunicorn:8000;
+        listen 80;
-        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        location = /favicon.ico { access_log off; log_not_found off; }
-        proxy_set_header Host $host;
+        location /static {
-        proxy_set_header  X-Real-IP   $remote_addr;
+            alias /var/www/myauth/static;
-        proxy_redirect off;
+            autoindex off;
+        }
+
+        location /robots.txt {
+            alias /var/www/myauth/static/robots.txt;
+        }
+
+        location / {
+            proxy_pass http://allianceauth_gunicorn:8000;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header Host $host;
+            proxy_set_header  X-Real-IP   $remote_addr;
+            proxy_redirect off;
+        }
     }
 }

docker/docker-compose.yml

@@ -62,10 +62,10 @@ services:
         max-file: "5"
 
   nginx:
-    image: nginx:1.25
+    image: nginx:stable
     restart: always
     volumes:
-      - ./conf/nginx.conf:/etc/nginx/conf.d/default.conf
+      - ./conf/nginx.conf:/etc/nginx/nginx.conf
       - static-volume:/var/www/myauth/static
     depends_on:
       - allianceauth_gunicorn

docs/development/custom/framework/api.md

@@ -36,7 +36,7 @@ from allianceauth.framework.api.evecharacter import get_user_from_evecharacter
 user = get_user_from_evecharacter(character=my_evecharacter)
 ```
 
-Now, `user` is a `User` object, or the sentinel username (see [get_sentinel_user](#get-sentinel-user))
+Now, `user` is a `User` object, or the sentinel username (see [get_sentinel_user](#get_sentinel_user))
 if the `EveCharacter` has no user.
 
 ## User API
@@ -88,7 +88,7 @@ main_character = get_main_character_name_from_user(user=my_user)
 
 Now, `main_character` is a `string` containing the user's main character name.
 If the user has no main character, the username will be returned. If the user is `None`,
-the sentinel username (see [get_sentinel_user](#get-sentinel-user)) will be returned.
+the sentinel username (see [get_sentinel_user](#get_sentinel_user)) will be returned.
 
 ### get_sentinel_user
 

docs/development/custom/framework/templates.md

@@ -8,7 +8,7 @@ have to load specific CSS or JavaScript yourself.
 
 These bundles include DataTables CSS and JS, jQuery Datepicker CSS and JS, jQueryUI CSS and JS, and more.
 
-A full list of bundles we provide can be found here: https://gitlab.com/allianceauth/allianceauth/-/tree/master/allianceauth/templates/bundles
+A full list of bundles we provide can be found here: <https://gitlab.com/allianceauth/allianceauth/-/tree/master/allianceauth/templates/bundles>
 
 To use a bundle, you can use the following code in your template (Example for jQueryUI):
 

docs/development/custom/integrating-services.md

@@ -122,10 +122,6 @@ class MyService(ServiceHook):
 
 All of your apps defined urlpatterns will then be included in the `URLconf` when the core application starts.
 
-#### self.service_ctrl_template
-
-This is provided as a courtesy and defines the default template to be used with [render_service_ctrl](#render_service_ctrl). You are free to redefine or not use this variable at all.
-
 #### title
 
 This is a property which provides a user-friendly display of your service's name. It will usually do a reasonably good job unless your service name has punctuation or odd capitalization. If this is the case, you should override this method and return a string.
@@ -134,7 +130,7 @@ This is a property which provides a user-friendly display of your service's name
 
 #### self.service_ctrl_template
 
-This is provided as a courtesy and defines the default template to be used with [render_service_ctrl](#render-service-ctrl). You are free to redefine or not use this variable at all.
+This is provided as a courtesy and defines the default template to be used with [render_service_ctrl](#render_service_ctrl). You are free to redefine or not use this variable at all.
 
 #### delete_user
 

docs/development/custom/menu-hooks.md

@@ -18,6 +18,8 @@ The `MenuItemHook` class specifies some parameters/instance variables required f
     :undoc-members:
 ```
 
+## Parameters
+
 ### text
 
 The text shown as menu item, e.g., usually the name of the app.

docs/development/custom/url-hooks.md

@@ -12,6 +12,8 @@ def register_urls():
     return UrlHook(app_name.urls, 'app_name', r^'app_name/')
 ```
 
+### Parameters
+
 #### urls
 
 The urls module to include. See [the Django docs](https://docs.djangoproject.com/en/dev/topics/http/urls/#example) for designing urlpatterns.

docs/features/services/discord.md

@@ -50,6 +50,7 @@ Update your auth project's settings file, inputting the server ID as `DISCORD_GU
 :::{note}
 If you already have a Discord server, skip the creation step, but be sure to retrieve the server ID
 :::
+
 ### Registering an Application
 
 Navigate to the [Discord Developers site.](https://discord.com/developers/applications/me) Press the plus sign to create a new application.
@@ -112,6 +113,7 @@ Role names on Discord are case-sensitive, while reserved group names on Auth are
 .. seealso::
     For more information see :ref:`ref-reserved-group-names`.
 ```
+
 ## Tasks
 
 The Discord service contains a number of tasks that can be run to manually perform updates to all users.
@@ -132,6 +134,7 @@ Name                     Description
 `update_all`             Update groups, nicknames, usernames of all users
 ======================== ====================================================
 ```
+
 :::{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.
 :::
@@ -156,6 +159,7 @@ Name                                Description
 `DISCORD_TASKS_MAX_RETRIES`         max retries of tasks after an error occurred                                                  `3`
 =================================== ============================================================================================= =======
 ```
+
 ## Permissions
 
 To use this service, users will require some of the following.
@@ -167,6 +171,7 @@ To use this service, users will require some of the following.
 | discord.access_discord                | None             | Can Access the Discord Service                                           |
 +---------------------------------------+------------------+--------------------------------------------------------------------------+
 ```
+
 ## Troubleshooting
 
 ### "Unknown Error" on Discord site when activating service

docs/features/services/nameformats.md

@@ -29,6 +29,7 @@ Currently, the following services support custom name formats:
 | Xenforo     | Username  | ``{character_name}``                |
 +-------------+-----------+-------------------------------------+
 ```
+
 :::{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.
 :::

docs/installation/apache.md

@@ -11,21 +11,28 @@ If you're using a small VPS to host services with very limited memory, consider
 ::::{tabs}
 
 :::{group-tab} Ubuntu 2004, 2204
+
 ```shell
 apt-get install apache2
 ```
+
 :::
 :::{group-tab} CentOS 7
+
 ```shell
 yum install httpd
 ```
+
 :::
 :::{group-tab} CentOS Stream 8
+
 ```shell
 dnf install httpd
 ```
+
 :::
 :::{group-tab} CentOS Stream 9
+
 ```shell
 systemctl enable httpd
 systemctl start httpd
@@ -36,7 +43,6 @@ systemctl start httpd
 
 CentOS 7, Stream 8, Stream 9
 
-
 ## Configuration
 
 ### Permissions

docs/maintenance/tuning/gunicorn.md

@@ -1,13 +0,0 @@
-# Gunicorn
-
-## Number of workers
-
-The default installation will have 3 workers configured for Gunicorn. This will be fine on most systems, but if your system as more than one core than you might want to increase the number of workers to get better response times. Note that more workers will also need more RAM though.
-
-The number you set this to will depend on your own server environment, how many visitors you have etc. Gunicorn suggests `(2 x $num_cores) + 1` for the number of workers. So for example, if you have 2 cores, you want 2 x 2 + 1 = 5 workers. See [here](https://docs.gunicorn.org/en/stable/design.html#how-many-workers) for the official discussion on this topic.
-
-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):
-
-```shell
-systemctl restart supervisor
-```

docs/maintenance/tuning/web.md

@@ -0,0 +1,156 @@
+# Web Tuning
+
+## Gunicorn
+
+### Number of workers
+
+The default installation will have 3 workers configured for Gunicorn. This will be fine on most systems, but if your system as more than one core than you might want to increase the number of workers to get better response times. Note that more workers will also need more RAM though.
+
+The number you set this to will depend on your own server environment, how many visitors you have etc. Gunicorn suggests `(2 x $num_cores) + 1` for the number of workers. So for example, if you have 2 cores, you want 2 x 2 + 1 = 5 workers. See [here](https://docs.gunicorn.org/en/stable/design.html#how-many-workers) for the official discussion on this topic.
+
+::::{tabs}
+:::{group-tab} Ubuntu 2204, 2404
+To have 5 workers change the setting `--workers=x` to `--workers=5` in your `supervisor.conf` file and then reload the supervisor with the following command to activate the change
+
+```shell
+systemctl restart supervisor
+```
+
+:::
+:::{group-tab} CentOS / RHEL
+To have 5 workers change the setting `--workers=x` to `--workers=5` in your `supervisor.conf` file and then reload the supervisor with the following command to activate the change
+
+```shell
+systemctl restart supervisor
+```
+
+:::
+:::{group-tab} Docker Compose
+To have 5 workers change the setting `--workers=3` to `--workers=5` in your `docker-compose.yml` file and then restart the container as follows
+
+```shell
+docker compose up -d
+```
+
+:::
+::::
+
+## nginx
+
+### nginx repo
+
+We can use the Nginx repositories for a slightly more cutting edge version of Nginx, with more features. Install it to enable the below features
+
+::::{tabs}
+:::{group-tab} Ubuntu 2204, 2404
+<https://nginx.org/en/linux_packages.html#Ubuntu>
+:::
+:::{group-tab} CentOS / RHEL
+<https://nginx.org/en/linux_packages.html#RHEL>
+:::
+:::{group-tab} Docker
+No package necessary, simply increase `docker compose pull` and `docker compose up -d` to update.
+:::
+::::
+
+### Brotli Compression
+
+Brotli is a modern compression algorithm designed for the web. Use this with Pre-Compression and E2E Cloudflare compression for best results.
+
+::::{tabs}
+:::{group-tab} Ubuntu 2204, 2404
+sudo apt update
+sudo apt install libnginx-mod-http-brotli-filter libnginx-mod-http-brotli-static
+:::
+:::{group-tab} CentOS
+WIP
+:::
+:::{group-tab} Docker
+Pull a custom dockerfile
+
+```bash
+mkdir nginx
+curl -o my-nginx/Dockerfile https://raw.githubusercontent.com/nginxinc/docker-nginx/master/modules/Dockerfile
+```
+
+Replace the nginx service in your docker-compose as follows
+
+```dockerfile
+  nginx:
+    build:
+      context: ./nginx/
+      args:
+        ENABLED_MODULES: brotli
+    restart: always
+    volumes:
+      - ./conf/nginx.conf:/etc/nginx/nginx.conf
+      - static-volume:/var/www/myauth/static
+    depends_on:
+      - allianceauth_gunicorn
+    logging:
+      driver: "json-file"
+      options:
+        max-size: "10Mb"
+        max-file: "5"
+```
+
+:::
+::::
+
+Modify your nginx.conf as follows
+
+```conf
+load_module modules/ngx_http_brotli_static_module.so;
+load_module modules/ngx_http_brotli_filter_module.so;
+...
+http {
+  ...
+    server {
+        ...
+        location /static {
+            ...
+            brotli_static on;
+            brotli_types application/javascript text/css font/woff2 image/png image/svg+xml font/woff image/gif;
+            brotli_comp_level 11;
+        }
+        ...
+        location / {
+            ...
+            brotli on;
+            brotli_comp_level 4;
+        }
+    }
+}
+```
+
+### Staticfile Pre-Compression
+
+We can use a small library to pre-compress staticfiles for Nginx to deliver.
+
+```shell
+pip install django-static-compress
+```
+
+Add the following lines to local.py
+
+```python
+# Tuning / Compression
+STORAGES = {
+    "staticfiles": {
+        "BACKEND": "static_compress.CompressedStaticFilesStorage",
+    },
+}
+
+STATIC_COMPRESS_FILE_EXTS = ['js', 'css', 'woff2', 'png', 'svg', 'woff', 'gif']
+STATIC_COMPRESS_METHODS = ['gz', 'br']
+STATIC_COMPRESS_KEEP_ORIGINAL = True
+STATIC_COMPRESS_MIN_SIZE_KB = 1
+```
+
+## Cloudflare
+
+### Brotli E2E Compression
+
+Soon to be turned on by default. Refer to <https://developers.cloudflare.com/speed/optimization/content/brotli/enable/>
+
+In order for cloudflare to seamlessly pass on your brotli compressed pages (End to End), ensure minification, rocket loader and other features are _off_ <https://developers.cloudflare.com/speed/optimization/content/brotli/enable/#notes-about-end-to-end-compression>. Else cloudflare will need to uncompress, modify, then recompress your pages.