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

2026-02-05 06:36:19 +01:00 · 2025-10-26 11:40:21 +10:00
parent 6ab2af79eb bff20ddd5d
commit 05943576a0
94 changed files with 4915 additions and 2510 deletions
--- a/docs/development/dev_setup/aa-dev-setup-wsl-vsc-v2.md
+++ b/docs/development/dev_setup/aa-dev-setup-wsl-vsc-v2.md
@@ -1,6 +1,6 @@
-# Development on Windows 10 with WSL and Visual Studio Code
+# Development on Windows with WSL and Visual Studio Code

-This document describes step-by-step how to set up a complete development environment for Alliance Auth apps on Windows 10 with Windows Subsystem for Linux (WSL) and Visual Studio Code.
+This document describes step-by-step how to set up a complete development environment for Alliance Auth apps on Windows with Windows Subsystem for Linux (WSL) and Visual Studio Code.

 The main benefit of this setup is that it runs all services and code in the native Linux environment (WSL) and at the same time can be fully controlled from within a comfortable Windows IDE (Visual Studio Code) including code debugging.

@@ -15,9 +15,9 @@ This guide is meant for development purposes only and not for installing AA in a
 The development environment consists of the following components:

 - Visual Studio Code with the Remote WSL and Python extension
- WSL with Ubuntu (18.04. LTS or higher)
- Python environment on WSL (3.8 or higher)
- MySQL server on WSL
+- WSL with Ubuntu (24.04. LTS or higher)
+- Python environment on WSL (3.12 or higher)
+- MySQL/MariaDB server on WSL
 - Redis on WSL
 - Alliance Auth on WSL
 - Celery on WSL
@@ -30,14 +30,14 @@ This setup works with both WSL 1 and WSL 2. However, due to the significantly be

 ## Requirement

-The only requirement is a PC with Windows 10 and Internet connection to download the additional software components.
+The only requirement is a PC with Windows + WSL and Internet connection to download the additional software components.

 ## Installing Windows apps

 ### Windows Subsystem for Linux

- Install from here: [Microsoft docs](https://docs.microsoft.com/en-us/windows/wsl/install-win10)
- Choose Ubuntu 18.04. LTS or higher
+- Install from here: [Microsoft docs](https://learn.microsoft.com/en-us/windows/wsl/install)
+- Choose Ubuntu 24.04 LTS or higher

 ### Visual Studio Code

@@ -81,7 +81,7 @@ sudo apt-get install python3.10 python3.10-dev python3.10-venv python3-setuptool
 Use the following command to install Python 3 with all required libraries with the default version:

 ```shell
-sudo apt-get install python3 python3-dev python3-venv python3-setuptools python3-pip python-pip
+sudo apt-get install python3 python3-dev python3-venv python3-setuptools python3-pip
 ```

 ### Install redis and other tools
@@ -101,17 +101,7 @@ sudo redis-server --daemonize yes
 Install MySQL and required libraries with the following command:

 ```shell
-sudo apt-get install mysql-server mysql-client libmysqlclient-dev
-```
-
-:::{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:
-
-```shell
-sudo usermod -d /var/lib/mysql/ mysql
+sudo apt-get install mariadb-server mariadb-client libmariadb-dev-compat libmariadb-dev
 ```

 Start the mysql server
@@ -162,12 +152,14 @@ A good location for setting up this folder structure is your home folder or a su
 ~/aa-dev
 |- venv
 |- myauth
-|- my_app_1
-|- my_app_2
+|- working
+|  - allianceauth
+|  - my_app_1
+|  - my_app_2
 |- ...
 ```

-Following this approach, you can also set up additional AA projects, e.g. aa-dev-2, aa-dev-3 if needed.
+Following this approach, you can also set up additional AA projects, e.g. aa-dev-2, aa-dev-3 if needed. this also lets you group all the working applications into a folder so you can still find the parts that are important.

 Create the root folder `aa-dev`.

@@ -175,6 +167,14 @@ Create the root folder `aa-dev`.
 The folders `venv` and `myauth` will be created automatically in later steps. Please do not create them manually as this would lead to errors.
 :::

+eg
+
+```shell
+mkdir aa-dev
+cd aa-dev
+mkdir working
+```
+
 ### Setup virtual Python environment for aa-dev

 Create the virtual environment. Run this in your aa-dev folder:
@@ -199,8 +199,19 @@ pip install -U pip setuptools wheel

 ### Install and create AA instance

+if you are not already int he `aa-dev/working` folder `cd` there
+
 ```shell
-pip install allianceauth
+cd aa-dev/working
+```
+
+now we are going to install allianceauth from a locally cloned repo
+
+```shell
+git clone https://gitlab.com/allianceauth/allianceauth.git
+cd allianceauth
+pip install -e .
+cd ..
 ```

 Now we are ready to set up our AA instance. Make sure to run this command in your aa-dev folder:
@@ -237,6 +248,7 @@ There are two Django settings files: ``base.py`` and ``local.py``. The base sett

 ```python
 DEBUG = True
+DISPLAY_DEBUG = False
 ```

 Define URL and name of your site:
@@ -343,7 +355,7 @@ The result should look something like this:

 ```json
 {
-    "name": "Python: Django",
+    "name": "Python: Django-Webserver",
    "type": "python",
    "request": "launch",
    "program": "${workspaceFolder}/myauth/manage.py",
@@ -385,6 +397,31 @@ Here is an example debug config for Celery:
 },
 ```

+Sometimes you may just need to do a lot of tasks to get data in from ESI.
+
+```json
+{
+    "name": "Python: Celery - No debug 10 Threads",
+    "type": "python",
+    "request": "launch",
+    "module": "celery",
+    "cwd": "${workspaceFolder}/myauth",
+    "console": "integratedTerminal",
+    "args": [
+        "-A",
+        "myauth",
+        "worker",
+        "-l",
+        "info",
+        "-P",
+        "threads",
+        "--concurrency=10"
+    ],
+    "django": true,
+    "justMyCode": true,
+},
+```
+
 ### Debug config for unit tests

 Finally, it makes sense to have a dedicated debug config for running unit tests. Here is an example config for running all tests of the app `example`.
@@ -473,7 +510,7 @@ Install from here. [DBeaver](https://dbeaver.io/)

 ## Adding apps for development

-The idea behind the particular folder structure of aa-dev is to have each and every app in its own folder and git repo. To integrate them with the AA instance, they need to be installed once using the -e option that enabled editing of the package. And then added to the INSTALLED_APPS settings.
+The idea behind the particular folder structure of aa-dev is to have each and every app in its own folder under the `working` folder as a git repo. To integrate them with the AA instance, they need to be installed once using the -e option that enabled editing of the package. And then added to the INSTALLED_APPS settings.

 To demonstrate, let's add the example plugin to our environment.

@@ -482,8 +519,10 @@ Open a WSL bash and navigate to the aa-dev folder. Make sure you have activated
 Run these commands:

 ```shell
-git clone https://gitlab.com/ErikKalkoken/allianceauth-example-plugin.git
-pip install -e allianceauth-example-plugin
+cd working
+git clone https://github.com/ppfeufer/aa-example-plugin.git
+cd aa-example-plugin
+pip install -e .
 ```

 Add `'example'` to INSTALLED_APPS in your `local.py` settings.