diff --git a/docs/admin/01_install.rst b/docs/admin/01_install.rst
index 437c161d2dea34d4886119de075f89749ddf73dd..bf39c4072f660b75a26613dfbe2ecfc515e66ae9 100644
--- a/docs/admin/01_install.rst
+++ b/docs/admin/01_install.rst
@@ -1,150 +1,249 @@
Install AlekSIS
===============
-From source
------------
+From PyPI
+---------
-In this section we will install AlekSIS with `uWSGI` and `nGINX` on debian
+In this section we will install AlekSIS with `uWSGI` and `nGINX` on Debian
bullseye.
-AlekSIS will store its data in two directories; media and static. The
-`media` directory contains everything uploaded by users, e.g. photos of
-persons. The `static` folder contains static files from AlekSIS such as
-scripts an stylesheets.
+Filesystem locations
+~~~~~~~~~~~~~~~~~~~~
+
+AlekSIS will need and use the following paths:
+
+ * `/etc/aleksis` for configuration files
+ * `/var/lib/aleksis/media` for file storage (Django media)
+ * `/var/backups/aleksis` for backups of database and media files
+ * `/usr/local/share/aleksis/static` for static files
+ * `/usr/local/share/aleksis/node_modules` for frontend dependencies
+
+You can change any of the paths as you like.
-1. Prerequisites::
+Prerequisites
+~~~~~~~~~~~~~
+
+For an installation on a dedicated server, the following prerequisites are needed:
* Debian 11
+ * PostgreSQL
+ * Redis
+ * uWSGI
+ * nginx
+ * Python 3.9
+ * Some system dependencies to build Python modules and manage frontend files
+ * The aforementioned paths
+
+Install system packages
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Install some packages from the Debian package system.
+
+.. code-block:: shell
+
+ apt install uwsgi \
+ uwsgi-plugin-python3 \
+ nginx-full \
+ python3 \
+ python3-dev \
+ libldap2-dev \
+ libsasl2-dev \
+ yarnpkg \
+ python3-virtualenv \
+ chromium \
+ redis-server \
+ postgresql
+
+Create PostgreSQL user and database
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Generate a secure password for the database, then create the user and database.
+
+.. code-block:: shell
+
+ sudo -u postgres createuser -l aleksis -
+ sudo -u postgres createdb -O aleksis aleksis
+
+When asked, use the password generated above.
+
+Create the directories for storage
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: shell
-1. Prepare system
+ mkdir -p /etc/aleksis \
+ /usr/share/aleksis/{static,node_modules} \
+ /var/lib/aleksis/media \
+ /var/backups/aleksis
- * Install system dependencies::
+Create AlekSIS configuration file
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- $ apt install uwsgi uwsgi-plugin-python3 nginx-full python3.9 python3.9-dev libldap2-dev libsasl2-dev yarnpkg python3-virtualenv chromium redis-server
+AlekSIS is configured in files in `/etc/aleksis`. Create a basic configuration file
+for the environment defined above by opening `/etc/aleksis/aleksis.toml` with your
+favourite text editor and adding the following configuration.
- * Create and activate virtual environment::
+.. code-block:: toml
- $ mkdir -p /srv/www/aleksis
- $ mkdir -p /srv/www/aleksis/data/{static,media}
- $ cd /srv/www/aleksis
- $ python3 -m venv
- $ source /srv/www/aleksis/venv/bin/activate
- $ pip install poetry
+ static = { root = "/usr/local/share/aleksis/static", url = "/static/" }
+ media = { root = "/var/lib/aleksis/media", url = "/media/" }
+ node_modules = { root = "/usr/local/share/aleksis/node_modules" }
+ secret_key = "SomeRandomValue"
- * Install and configure PostgreSQL::
+ [http]
+ allowed_hosts = ["aleksis.example.com"]
- $ apt install postgresql-13
- $ sudo -u postgres createuser -l aleksis -
- $ sudo -u postgres createdb -O aleksis aleksis
+ [database]
+ host = "localhost"
+ name = "aleksis"
+ username = "aleksis"
+ password = "password_generated_above"
- * Configure uWSGI::
+ [backup]
+ location = "/var/backups/aleksis"
- $ editor /etc/uwsgi/apps-available/aleksis.ini
+ [auth.superuser]
+ username = "admin"
+ password = "admin"
+ email = "root@localhost"
- [uwsgi]
- vhost = true
- plugins = python3
- master = true
- enable-threads = true
- processes = 20
- wsgi-file = /usr/src/AlekSIS/aleksis/core/wsgi.py
- virtualenv = /srv/www/aleksis/venv
- chdir = /usr/src/AlekSIS
- lazy = true
- lazy-apps = true
- attach-daemon = celery -A aleksis.core worker --concurrency=4
- attach-daemon = celery -A aleksis.core beat
+Install AlekSIS itself
+~~~~~~~~~~~~~~~~~~~~~~
- $ ln -s /etc/uwsgi/apps-available/aleksis.ini /etc/uwsgi/apps-enabled/aleksis.ini
- $ service uwsgi restart
+To install AlekSIS now, and run all post-install tasks, run the following commands.
+They will pull the AlekSIS standard distribution from `PyPI`_ and install it to the
+system-wide `dist-packages` of Python. Afterwards, it will download frontend dependencies
+from `yarnpkg`, collect static files, and migrate the database to the final schema.
- * Get SSL ssl certificate
+.. code-block:: shell
- * https://certbot.eff.org/instructions
+ pip3 install aleksis
+ aleksis-admin yarn install
+ aleksis-admin collectstatic
+ aleksis-admin migrate
+ aleksis-admin createinitialrevisions
- * Configure nGINX::
- $ editor /etc/nginx/sites-available/aleksis.example.com
- server {
- listen 80;
- listen [::]:80;
+Configure uWSGI
+~~~~~~~~~~~~~~~
- server_name aleksis.example.com;
+uWSGI is an application server that will manage the server processes and requests.
+It will also run the Celery broker and scheduler for you.
- return 301 https://$server_name$request_uri;
- }
+Configure a uWSGI app by opening `/etc/uwsgi/apps-available/aleksis.ini` in an
+editor and inserting:
- server {
- listen 443 ssl http2;
- listen [::]:443 ssl http2;
+.. code-block:: toml
- ssl_certificate /etc/letsencrypt/certs/aleksis.example.com/fullchain.pem;
- ssl_certificate_key /etc/letsencrypt/certs/aleksis.example.com/privkey.pem;
- ssl_trusted_certificate /etc/letsencrypt/certs/aleksis.example.com/chain.pem;
+ [uwsgi]
+ vhost = true
+ plugins = python3
+ master = true
+ enable-threads = true
+ processes = 20
+ wsgi-file = /usr/local/lib/python3/dist-packages/aleksis/core/wsgi.py
+ chdir = /var/lib/aleksis
+ lazy = true
+ lazy-apps = true
+ attach-daemon = celery -A aleksis.core worker --concurrency=4
+ attach-daemon = celery -A aleksis.core beat
- server_name aleksis.example.com;
+Afterwards, enable the app using:
- access_log /var/log/nginx/access.log;
+.. code-block:: shell
- location /static {
- alias /srv/www/aleksis/data/static;
- }
+ ln -s /etc/uwsgi/apps-available/aleksis.ini /etc/uwsgi/apps-enabled/aleksis.ini
+ service uwsgi restart
- location / {
- uwsgi_pass aleksis;
- include uwsgi_params;
+Configure the nginx webserver
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- proxy_redirect off;
- proxy_pass_header Authorization;
- }
- }
+First, you should get a TLS certificate, e.g. by using `Let's Encrypt`_.
- $ ln -s /etc/nginx/sites-available/aleksis.example.com /etc/nginx/sites-enabled/aleksis.example.com
- $ service nginx restart
+Then, create a virtual host in nginx, by editing `/etc/nginx/sites-available/aleksis.example.com`.
- * Configure AlekSIS::
- $ mkdir /etc/aleksis
- $ editor /etc/aleksis/aleksis.toml
- static = { root = "/srv/www/aleksis/data/static", url = "/static/" }
- media = { root = "/srv/www/aleksis/data/media", url = "/media/" }
- secret_key = "SomeRandomValue"
+.. code-block:: nginx
+
+ server {
+ listen 80;
+ listen [::]:80;
+
+ server_name aleksis.example.com;
+
+ return 301 https://$server_name$request_uri;
+ }
+
+ server {
+ listen 443 ssl http2;
+ listen [::]:443 ssl http2;
+
+ ssl_certificate /etc/letsencrypt/certs/aleksis.example.com/fullchain.pem;
+ ssl_certificate_key /etc/letsencrypt/certs/aleksis.example.com/privkey.pem;
+ ssl_trusted_certificate /etc/letsencrypt/certs/aleksis.example.com/chain.pem;
+
+ server_name aleksis.example.com;
+
+ access_log /var/log/nginx/access.log;
+
+ location /static {
+ alias /usr/local/share/aleksis/static;
+ }
+
+ location / {
+ uwsgi_pass aleksis;
+ include uwsgi_params;
+ proxy_redirect off;
+ proxy_pass_header Authorization;
+ }
+ }
+
+Enable the virtual host:
+
+.. code-block:: shell
+
+ ln -s /etc/nginx/sites-available/aleksis.example.com /etc/nginx/sites-enabled/aleksis.example.com
+ service nginx restart
+
+Finalisation
+~~~~~~~~~~~~
+
+Your AlekSIS installation should now be reachable and you can login with the administration
+account configured above.
+
+With Docker
+-----------
- [http]
- allowed_hosts = ["aleksis.example.com"]
+AlekSIS can also be installed using Docker, either only AlekSIS itself, or the
+full stack, including Redis, using docker-compose
- [database]
- host = "localhost"
- name = "aleksis"
- username = "aleksis"
- password = "SomeSecretPassword!1"
+Full stack using docker-compose
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-1. Clone git repository and checkout version::
+First, install Docker and docker-compose on your system. Also install git
+to get the docker-compose file and image definition.
- $ cd /usr/src
- $ git clone https://edugit.org/AlekSIS/official/AlekSIS-Core
- $ cd AlekSIS-Core
- $ git checkout 2.0b
+.. code-block:: shell
-1. Install dependencies and setup initially::
+ apt install docker.io docker-compose git
- $ poetry install
- $ aleksis-admin yarn install
- $ aleksis-admin collectstatic
- $ aleksis-admin migrate
+Now, clone the distribution repository, which contains the docker-compose
+file.
-1. Restart uWSGI::
+.. code-block:: shell
- $ service uwsgi restart
+ git clone https://edugit.org/AlekSIS/official/AlekSIS
-Docker with `docker-compose`
----------------------------
+You should review the file `docker-compose.yaml` for any environment variables
+you want to change.
-1. Prerequisites::
+Finally, bring the stack up using:
- * System with docker and docker-compose installed
+.. code-block:: shell
-1. Run docker image::
+ docker-compose up -d
- $ git clone https://edugit.org/AlekSIS/Official/AlekSIS
- $ docker-compose up -d
+AlekSIS will be reachable on port 8000. You are responsible for adding a
+reverse proxy like nginx providing TLS, etc.
.. _Dynaconf: https://dynaconf.readthedocs.io/en/latest/
+.. _Let's Encrypt: https://certbot.eff.org/instructions
+.. _PyPI: https://pypi.org