mirror of
https://gitlab.com/allianceauth/allianceauth.git
synced 2025-12-19 23:35:04 +01:00
MyST conversion
This commit is contained in:
Ariel Rin
@@ -7,7 +7,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.
|
||||
|
||||
:::{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**.
|
||||
This guide is meant for development purposes only and not for installing AA in a production environment. For production installation please see chapter **Installation**.
|
||||
:::
|
||||
|
||||
## Overview
|
||||
@@ -25,8 +25,8 @@ 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.
|
||||
|
||||
:::{note}
|
||||
This setup works with both WSL 1 and WSL 2. However, due to the significantly better performance we recommend WSL 2.
|
||||
```
|
||||
This setup works with both WSL 1 and WSL 2. However, due to the significantly better performance we recommend WSL 2.
|
||||
:::
|
||||
|
||||
## Requirement
|
||||
|
||||
@@ -37,19 +37,14 @@ The only requirement is a PC with Windows 10 and Internet connection in order to
|
||||
### 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
|
||||
|
||||
### Visual Studio Code
|
||||
|
||||
- Install from here: [VSC Download](https://code.visualstudio.com/Download)
|
||||
|
||||
- Open the app and install the following VSC extensions:
|
||||
|
||||
- Remote WSL
|
||||
|
||||
- Connect to WSL. This will automatically install the VSC server on the VSC server for WSL
|
||||
|
||||
- Once connected to WSL install the Python extension on the WSL side
|
||||
|
||||
## Setting up WSL / Linux
|
||||
@@ -71,18 +66,18 @@ sudo apt-get install gettext
|
||||
|
||||
Next we need to install Python and related development tools.
|
||||
|
||||
:::{hint}
|
||||
:::
|
||||
|
||||
:::{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.
|
||||
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:
|
||||
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`
|
||||
```shell
|
||||
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:
|
||||
|
||||
```shell
|
||||
@@ -110,8 +105,8 @@ 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 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:
|
||||
|
||||
@@ -146,17 +141,17 @@ sudo mysql_tzinfo_to_sql /usr/share/zoneinfo | sudo mysql -u root mysql
|
||||
```
|
||||
|
||||
:::{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:
|
||||
|
||||
::
|
||||
|
||||
#/bin/bash
|
||||
# start services for AA dev
|
||||
sudo service mysql start
|
||||
sudo redis-server --daemonize yes
|
||||
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:
|
||||
|
||||
```shell
|
||||
#/bin/bash
|
||||
# start services for AA dev
|
||||
sudo service mysql start
|
||||
sudo redis-server --daemonize yes
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
### Setup dev folder on WSL
|
||||
|
||||
Setup your folders on WSL bash for your dev project. Our approach will setup one AA project with one venv and multiple apps running under the same AA project, but each in their own folder and git.
|
||||
@@ -177,7 +172,7 @@ Following this approach you can also setup additional AA projects, e.g. aa-dev-2
|
||||
Create the root folder `aa-dev`.
|
||||
|
||||
:::{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.
|
||||
The folders `venv` and `myauth` will be created automatically in later steps. Please do not create them manually as this would lead to errors.
|
||||
:::
|
||||
|
||||
### Setup virtual Python environment for aa-dev
|
||||
@@ -237,7 +232,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`
|
||||
|
||||
:::{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.
|
||||
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.
|
||||
:::
|
||||
|
||||
```python
|
||||
@@ -308,15 +303,15 @@ 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`
|
||||
|
||||
:::{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).
|
||||
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).
|
||||
:::
|
||||
|
||||
:::{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.
|
||||
**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.
|
||||
|
||||
When you turn off debug mode you will see a problem though: Your pages will not render correctly. The reason is that Django will stop serving your static files in production mode and expect you to serve them from a real web server. Luckily, there is an option that forces Django to continue serving your static files directly even when not in debug mode. Just start your server with the following option: ``python manage.py runserver --insecure``
|
||||
```
|
||||
When you turn off debug mode you will see a problem though: Your pages will not render correctly. The reason is that Django will stop serving your static files in production mode and expect you to serve them from a real web server. Luckily, there is an option that forces Django to continue serving your static files directly even when not in debug mode. Just start your server with the following option: ``python manage.py runserver --insecure``
|
||||
:::
|
||||
|
||||
### Celery
|
||||
|
||||
|
||||
Reference in New Issue
Block a user