Merge branch 'master' of gitlab.com:allianceauth/allianceauth into v4.x

docs/customizing/index.md

@@ -71,3 +71,51 @@ urlpatterns = [
     re_path(r'', include(allianceauth.urls)),
 ]
 ```
+
+## Example: Adding an external link to the sidebar
+
+As an example we are adding an external links to the Alliance Auth sidebar using the template overrides feature. For our example let's add a link to Google's start page.
+
+### Step 1 - Create the template override folder
+
+First you need to create the folder for the template on your server. For AA to pick it up it has to match a specific structure.
+
+If you have a default installation you can create the folder like this:
+
+```sh
+mkdir -p /home/allianceserver/myauth/myauth/templates/allianceauth
+```
+
+### Step 2 - Download the original template
+
+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
+cd /home/allianceserver/myauth/myauth/templates/allianceauth
+wget <https://gitlab.com/allianceauth/allianceauth/-/raw/master/allianceauth/templates/allianceauth/side-menu.html>
+```
+
+### Step 3 - Modify the template
+
+Now you can modify the template to add your custom link. To create the google link we can add this snippet *between* the `{% menu_items %}` and the `</ul>` tag:
+
+```sh
+nano /home/allianceserver/myauth/myauth/templates/allianceauth/side-menu.html
+```
+
+```jinja
+    <li>
+        <a href="https://www.google.com/" target="_blank">
+            <i class="fab fa-google fa-fw"></i>Google
+        </a>
+    </li>
+```
+
+```eval_rst
+.. hint::
+    You can find other icons with a matching style on the `Font Awesome site <https://fontawesome.com/v5/search?m=free>`_ . AA currently uses Font Awesome version 5. You also want to keep the ``fa-fw`` tag to ensure all icons have the same width.
+```
+
+### Step 4 - Restart your AA services
+
+Finally, restart your AA services and your custom link should appear in the sidebar.

docs/development/custom/url-hooks.md

@@ -1,54 +1,65 @@
 # URL Hooks
 
-```eval_rst
-.. note::
-    URLs added through URL Hooks are protected by a decorator which ensures the requesting user is logged in and has a main character set.
-```
+## Base functionality
 
 The URL hooks allow you to dynamically specify URL patterns from your plugin app or service. To achieve this you should subclass or instantiate the `services.hooks.UrlHook` class and then register the URL patterns with the hook.
 
 To register a UrlHook class you would do the following:
 
-    @hooks.register('url_hook')
-    def register_urls():
-        return UrlHook(app_name.urls, 'app_name', r^'app_name/')
+```python
+@hooks.register('url_hook')
+def register_urls():
+    return UrlHook(app_name.urls, 'app_name', r^'app_name/')
+```
 
+### Public views
 
-The `UrlHook` class specifies some parameters/instance variables required for URL pattern inclusion.
+In addition is it possible to make views public. Normally, all views are automatically decorated with the `main_character_required` decorator. That decorator ensures a user needs to be logged in and have a main before he can access that view. This feature protects against a community app sneaking in a public view without the administrator knowing about it.
 
-`UrlHook(urls, app_name, base_url)`
+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.
 
-#### urls
-The urls module to include. See [the Django docs](https://docs.djangoproject.com/en/dev/topics/http/urls/#example) for designing urlpatterns.
-#### namespace
-The URL namespace to apply. This is usually just the app name.
-#### base_url
-The URL prefix to match against in regex form. Example `r'^app_name/'`. This prefix will be applied in front of all URL patterns included. It is possible to use the same prefix as existing apps (or no prefix at all) but [standard URL resolution](https://docs.djangoproject.com/en/dev/topics/http/urls/#how-django-processes-a-request) ordering applies (hook URLs are the last ones registered).
+```eval_rst
+.. 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.
+```
 
-### Example
+## Examples
 
 An app called `plugin` provides a single view:
 
-    def index(request):
-        return render(request, 'plugin/index.html')
+```python
+def index(request):
+    return render(request, 'plugin/index.html')
+```
 
 The app's `urls.py` would look like so:
 
-    from django.urls import path
-    import plugin.views
+```python
+from django.urls import path
+import plugin.views
 
-    urlpatterns = [
-        path('index/', plugins.views.index, name='index'),
-    ]
+urlpatterns = [
+    path('index/', plugins.views.index, name='index'),
+]
+```
 
 Subsequently it would implement the UrlHook in a dedicated `auth_hooks.py` file like so:
 
-    from alliance_auth import hooks
-    from services.hooks import UrlHook
-    import plugin.urls
+```python
+from alliance_auth import hooks
+from services.hooks import UrlHook
+import plugin.urls
 
-    @hooks.register('url_hook')
-    def register_urls():
-        return UrlHook(plugin.urls, 'plugin', r^'plugin/')
+@hooks.register('url_hook')
+def register_urls():
+    return UrlHook(plugin.urls, 'plugin', r^'plugin/')
+```
 
 When this app is included in the project's `settings.INSTALLED_APPS` users would access the index view by navigating to `https://example.com/plugin/index`.
+
+## API
+
+```eval_rst
+.. autoclass:: allianceauth.services.hooks.UrlHook
+    :members:
+```

docs/development/dev_setup/aa-dev-setup-wsl-vsc-v2.md

@@ -82,6 +82,10 @@ Next we need to install Python and related development tools.
 .. note::
     Should your Ubuntu come with a newer version of Python we recommend to still setup your dev environment with the oldest Python 3 version currently supported by AA (e.g Python 3.8 at this time of writing) to ensure your apps are compatible with all current AA installations
     You an check out this `page <https://askubuntu.com/questions/682869/how-do-i-install-a-different-python-version-using-apt-get/1195153>`_ on how to install additional Python versions on Ubuntu.
+
+    If you install a different python version from the default you need to adjust some of the commands below to install appopriate versions of those packages for example using Python 3.8 you might need to run the following after using the setup steps for the repository mentioned in the AskUbuntu post above:
+
+    `sudo apt-get install python3.8 python3.8-dev python3.8-venv python3-setuptools python3-pip python-pip`
 ```
 
 Use the following command to install Python 3 with all required libraries with the default version:
@@ -93,7 +97,7 @@ sudo apt-get install python3 python3-dev python3-venv python3-setuptools python3
 ### Install redis and other tools
 
 ```bash
-sudo apt-get install unzip git redis-server curl libssl-dev libbz2-dev libffi-dev
+sudo apt-get install unzip git redis-server curl libssl-dev libbz2-dev libffi-dev pkg-config
 ```
 
 Start redis

docs/features/apps/corpstats.md

@@ -113,7 +113,7 @@ By default Corp Stats are only updated on demand. If you want to automatically r
 ```python
 CELERYBEAT_SCHEDULE['update_all_corpstats'] = {
     'task': 'allianceauth.corputils.tasks.update_all_corpstats',
-    'schedule': crontab(minute=0, hour="*/6"),
+    'schedule': crontab(minute="0", hour="*/6"),
 }
 ```
 

docs/features/services/discord.md

@@ -29,7 +29,7 @@ DISCORD_SYNC_NAMES = False
 
 CELERYBEAT_SCHEDULE['discord.update_all_usernames'] = {
     'task': 'discord.update_all_usernames',
-    'schedule': crontab(minute=0, hour='*/12'),
+    'schedule': crontab(minute='0', hour='*/12'),
 }
 ```
 

docs/installation/allianceauth.md

@@ -220,13 +220,13 @@ A few extra utilities are also required for installation of packages.
 Ubuntu 1804, 2004, 2204:
 
 ```bash
-sudo apt-get install unzip git redis-server curl libssl-dev libbz2-dev libffi-dev build-essential
+sudo apt-get install unzip git redis-server curl libssl-dev libbz2-dev libffi-dev build-essential pkg-config
 ```
 
 CentOS 7:
 
 ```bash
-sudo yum install gcc gcc-c++ unzip git redis curl bzip2-devel openssl-devel libffi-devel wget
+sudo yum install gcc gcc-c++ unzip git redis curl bzip2-devel openssl-devel libffi-devel wget pkg-config
 ```
 
 ```bash

docs/installation/apache.md

@@ -75,6 +75,7 @@ Place your virtual host configuration in the appropriate section within `/etc/ht
 
         ProxyPassMatch ^/static !
         ProxyPassMatch ^/robots.txt !
+        ProxyPassMatch ^/favicon.ico !
 
         ProxyPass / http://127.0.0.1:8000/
         ProxyPassReverse / http://127.0.0.1:8000/
@@ -82,6 +83,7 @@ Place your virtual host configuration in the appropriate section within `/etc/ht
 
         Alias "/static" "/var/www/myauth/static"
         Alias "/robots.txt" "/var/www/myauth/static/robots.txt"
+        Alias "/favicon.ico" "/var/www/myauth/static/allianceauth/icons/favicon.ico"
 
         <Directory "/var/www/myauth/static">
             Require all granted
@@ -91,6 +93,11 @@ Place your virtual host configuration in the appropriate section within `/etc/ht
             SetHandler None
             Require all granted
         </Location>
+
+        <Location "/favicon.ico">
+            SetHandler None
+            Require all granted
+        </Location>
 </VirtualHost>
 ```
 

docs/installation/nginx.md

@@ -79,9 +79,9 @@ Copy this basic config into your config file. Make whatever changes you feel are
 ```
 server {
     listen 80;
-    server_name example.com;
+    listen [::]:80;
 
-    location = /favicon.ico { access_log off; log_not_found off; }
+    server_name example.com;
 
     location /static {
         alias /var/www/myauth/static;
@@ -92,6 +92,10 @@ server {
         alias /var/www/myauth/static/robots.txt;
     }
 
+    location /favicon.ico {
+        alias /var/www/myauth/static/allianceauth/icons/favicon.ico;
+    }
+
     # Gunicorn config goes below
     location / {
         include proxy_params;
@@ -110,6 +114,7 @@ Your config will need a few additions once you've got your certificate.
 
 ```
     listen 443 ssl http2; # Replace listen 80; with this
+    listen [::]:443 ssl http2; # Replace listen [::]:80; with this
 
     ssl_certificate           /path/to/your/cert.crt;
     ssl_certificate_key       /path/to/your/cert.key;
@@ -126,6 +131,8 @@ If you want to redirect all your non-SSL visitors to your secure site, below you
 ```
 server {
     listen 80;
+    listen [::]:80;
+
     server_name example.com;
 
     # Redirect all HTTP requests to HTTPS with a 301 Moved Permanently response.

docs/maintenance/apps.md

@@ -1,15 +1,95 @@
 # App Maintenance
 
-## Adding and Removing Apps
+## Adding Apps
 
 Your auth project is just a regular Django project - you can add in [other Django apps](https://djangopackages.org/) as desired. Most come with dedicated setup guides, but here is the general procedure:
 
 1. add `'appname',` to your `INSTALLED_APPS` setting in `local.py`
 2. run `python manage.py migrate`
-3. run `python manage.py collectstatic`
+3. run `python manage.py collectstatic --noinput`
 4. restart AA with `supervisorctl restart myauth:`
 
-If you ever want to remove an app, you should first clear it from the database to avoid dangling foreign keys: `python manage.py migrate appname zero`. Then you can remove it from your auth project's `INSTALLED_APPS` list.
+## Removing Apps
+
+The following instructions will explain how you can remove an app properly fom your Alliance Auth installation.
+
+```eval_rst
+.. 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.
+
+```
+
+### Step 1 - Removing database tables
+
+First, we want to remove the app related tables from the database.
+
+#### Automatic table removal
+
+Let's first try the automatic approach by running the following command:
+
+```sh
+python manage.py migrate appname zero
+```
+
+If that worked you'll get a confirmation message.
+
+If that did not work and you got error messages, you will need to remove the tables manually. This is pretty common btw, because many apps use sophisticated table setups, which can not be removed automatically by Django.
+
+#### Manual table removal
+
+First, tell Django that these migrations are no longer in effect (note the additional `--fake`):
+
+```sh
+python manage.py migrate appname zero --fake
+```
+
+Then, open the mysql tool and connect to your Alliance Auth database:
+
+```sh
+sudo mysql -u root
+use alliance_auth;
+```
+
+Next disable foreign key check. This makes it much easier to drop tables in any order.
+
+```sh
+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
+show tables;
+```
+
+Now, drop the tables from the app one by one like so:
+
+```sh
+drop table appname_model_1;
+drop table appname_model_2;
+...
+```
+
+And finally, but very importantly, re-enable foreign key checks again and then exit:
+
+```sh
+SET FOREIGN_KEY_CHECKS=1;
+exit;
+```
+
+### Step 2 - Remove the app from Alliance Auth
+
+Once the tables have been removed, you you can remove the app from Alliance Auth. This is done by removing the applabel from the `INSTALLED_APPS` list in your local settings file.
+
+### Step 3 - Remove the Python package
+
+Finally, we want to remove the app's Python package. For that run the following command:
+
+```sh
+pip uninstall app-package-name
+```
+
+Congrats, you have now removed this app from your Alliance Auth installation.
 
 ## Permission Cleanup