docs: add detailed production deployment instructions

deploy/config/settings.toml

@@ -0,0 +1,66 @@
+[section]
+name = "Town"
+street = "Street 12"
+town = "12345 Town"
+telephone = "123456789"
+telefax = "987654321"
+contact_mail = "contact@jdav-town.de"
+board_mail = "board@jdav-town.de"
+crisis_intervention_mail = "crisis@jdav-town.de"
+iban = "DE42 4242 4242 4242 4242 42"
+account_holder = "DAV Town"
+responsible_mail = "responsible@jdav-town.de"
+digital_mail = "digital@jdav-town.de"
+admins = [['Admin', 'admin@jdav-town.de']]
+
+[LJP]
+v32_head_organisation = """
+LJP application recipient header
+"""
+
+[misc]
+allowed_email_domains_for_invite_as_user = ['alpenverein-town.de']
+send_from_association_email = true
+domain = 'jdav-town.de'
+
+[finance]
+allowance_per_day = 22
+max_night_cost = 11
+
+[links]
+cloud = "https://nextcloud.com"
+dav_360 = "https://dav360.de"
+wiki = "https://wikipedia.org"
+docs = "https://jdav-hd.de/static/docs"
+registration_form = "download-me"
+
+[startpage]
+redirect_url = ''
+root_section = 'wir'
+recent_section = 'aktuelles'
+reports_section = 'berichte'
+
+[django]
+deployed = true
+debug = false
+secret_key = 'secret key'
+allowed_hosts = ['jdav-town.de']
+host = 'jdav-town.de'
+media_root = '/var/www/jdav_web/media'
+static_root = '/var/www/jdav_web/static'
+broker_url = 'redis://redis:6379/0'
+memcached_url = 'cache:11211'
+
+[mail]
+host = 'host'
+user = 'kompass-mailagent'
+password = 'password'
+default_sending_address = 'info@jdav-town.de'
+default_sending_name = 'JDAV Town'
+
+[database]
+host = 'host'
+port = 3306
+database = 'kompass'
+user = 'kompass'
+password = 'kompass-db-user-password'

deploy/docker-compose.yaml

@@ -0,0 +1,86 @@
+x-kompass:
+    &kompass
+    image: kompass:production
+    environment:
+      - DJANGO_SETTINGS_MODULE=jdav_web.settings
+      - KOMPASS_CONFIG_DIR_PATH=/app/config/
+    restart: always
+    depends_on:
+      - redis
+      - cache
+
+services:
+    master:
+        <<: *kompass
+        build:
+            context: git@git.jdav-hd.merten.dev:digitales/kompass#main
+            dockerfile: docker/production/Dockerfile
+        entrypoint: /app/docker/production/entrypoint-master.sh
+        volumes:
+          - uwsgi_data:/tmp/uwsgi/
+          - web_static:/app/static/
+          - web_static:/var/www/jdav_web/static/
+          - ./media:/var/www/jdav_web/media/
+          - ./config:/app/config:ro
+        networks:
+          - main
+        extra_hosts:
+          - "host:10.26.42.1"
+
+    nginx:
+        build: git@git.jdav-hd.merten.dev:digitales/kompass#main:docker/production/nginx
+        restart: always
+        volumes:
+          - uwsgi_data:/tmp/uwsgi/
+          - web_static:/var/www/jdav_web/static/:ro
+          - ./media:/var/www/jdav_web/media/:ro
+        ports:
+          - "3000:80"
+        depends_on:
+          - master
+        networks:
+          - main
+
+    cache:
+        restart: always
+        image: memcached:alpine
+        networks:
+          - main
+
+    redis:
+        restart: always
+        image: redis:6-alpine
+        networks:
+          - main
+
+    celery_worker:
+        <<: *kompass
+        entrypoint: /app/docker/production/entrypoint-celery-worker.sh
+        volumes:
+          - ./config:/app/config:ro
+        networks:
+          - main
+        extra_hosts:
+          - "host:10.26.42.1"
+
+    celery_beat:
+        <<: *kompass
+        entrypoint: /app/docker/production/entrypoint-celery-beat.sh
+        volumes:
+          - ./config:/app/config:ro
+        networks:
+          - main
+        extra_hosts:
+          - "host:10.26.42.1"
+
+volumes:
+  uwsgi_data:
+  web_static:
+
+networks:
+  main:
+    driver: bridge
+    ipam:
+      config:
+        - subnet: 10.26.42.0/24
+          gateway: 10.26.42.1

docs/source/development_manual/deployment.rst

@@ -4,4 +4,287 @@
 Production Deployment
 =====================
 
-tbd
+The production setup is based on the docker configuration in the ``production/`` folder of the repository. In
+contrast to the development setup, there is no database service configured in the ``docker-compose.yaml``. This
+is to allow for a more flexible setup with a database service installed on the host, for which it is easier
+to ensure data safety.
+
+.. _user_manual/initial_installation:
+
+Initial installation
+====================
+
+We give here step-by-step instructions how to set up an initial Kompass installation starting from a fresh
+Debian Bookworm installation. Of course these steps can be easily adapted to a different Linux distribution,
+the steps will mostly differ in the way the system dependencies are installed.
+
+The instructions describe the recommended setup with a docker-independent MySQL database server on the host system.
+
+We assume that all instructions are executed as ``root`` or with ``sudo``.
+
+1. Install the dependencies: To install ``docker``, please follow the `official instructions`_. For the MySQL
+   server, run the following command:
+
+   .. code-block:: console
+
+      apt install mariadb-server
+
+2. Setup the database: We need to create the database and create a user with a strong password. To generate
+   a strong password, run
+
+   .. code-block:: console
+
+      PASSWORD=$(tr -dc 'A-Za-z0-9' < /dev/urandom | head -c 24)
+
+   Now create a MySQL user with the generated password, by executing:
+
+   .. code-block:: console
+
+      mysql <<EOF
+      CREATE USER 'kompass'@'10.26.42.0/255.255.255.0' IDENTIFIED BY '$PASSWORD';
+      GRANT ALL PRIVILEGES ON kompass.* to 'kompass'@'10.26.42.0/255.255.255.0';
+      FLUSH PRIVILEGES;
+      EOF
+
+   To make the MySQL server available from the docker container, edit ``/etc/mysql/mariadb.cnf`` and
+   uncomment the ``port`` line in the ``[client-server]`` code block. It could then look like this:
+
+   .. code-block:: console
+
+      [client-server]
+      port = 3306
+      socket = /run/mysqld/mysqld.sock
+
+   Finally, edit ``/etc/mysql/mariadb.conf.d/50-server.cnf`` and add ``10.26.42.1`` [#ip-address]_ to the
+   ``bind-address`` line. It could then look like this:
+
+   .. code-block:: console
+
+      bind-address  = 127.0.0.1,10.26.42.1
+
+   Now restart the MySQL database by running:
+
+   .. code-block:: console
+
+      systemctl restart mariadb.service
+
+   .. note::
+      If you are running a firewall service, you will need to allow connections to the ``3306`` port
+      from the ``10.26.42.0/24`` subnet. If you use ``ufw``, you can do:
+
+      .. code-block:: console
+
+         ufw allow from 10.26.42.0/24 to 10.26.42.1 port 3306
+
+3. Install Kompass:
+
+   .. code-block:: console
+
+      mkdir /opt/kompass
+      cd /opt/kompass
+
+   Copy the contents of the ``deploy/`` directory of the Kompass repository into this folder. Afterwards,
+   the folder structure should look like this:
+
+   .. code-block::
+
+      .
+      ├── config
+      │   └── settings.toml
+      └── docker-compose.yaml
+
+   .. note::
+      As long as the Kompass repository is private, you need to ask the maintainers to add a read-only deploy
+      key for your installation to the `Gitea`_. Then you can add a ``.ssh`` config file on your server with a
+      section
+
+      .. code-block:: console
+
+         Host git.jdav-hd.merten.dev
+             HostName git.jdav-hd.merten.dev
+             User git
+             IdentityFile ~/.ssh/your_deploy_key
+
+   Now set the password of the MySQL user in the ``settings.toml`` by running
+
+   .. code-block:: console
+
+      sed -i "s/kompass-db-user-password/$PASSWORD/g" config/settings.toml
+
+   Finally, we can start the docker containers for the first time by running:
+
+   .. code-block:: console
+
+      docker compose up --build
+
+   This will start building the docker images and then launch the application. If everything
+   works as expected, there should be no error messages. In this case open a second terminal,
+   navigate to ``/opt/kompass/`` and run
+
+   .. code-block:: console
+
+      docker compose exec master bash
+      cd jdav_web
+      python3 manage.py createsuperuser
+
+   This will prompt you for a username and a password for the initial admin user. Use a strong password
+   and don't use the same password as the one for the MySQL user above!
+
+   The webserver will be available on ``localhost`` on port ``3000``. To expose it to the
+   outer world, we need to setup a web server, such as ``apache2``.
+
+4. Install a webserver: This is standard and not Kompass specific, but we still include the
+   steps here for completeness. First, we need to install ``apache2``:
+
+   .. code-block:: console
+
+      apt install apache2
+      a2enmod md ssl proxy proxy_http headers
+
+   To allow the ``md`` module to automatically request a Let's Encrypt certificate for our domain,
+   you need to accept the `certificate agreement`_. If you do, add the following line
+
+   .. code-block::
+
+      MDCertificateAgreement accepted
+
+   to ``/etc/apache2/apache2.conf``.
+
+   Then create a new file ``/etc/apache2/sites-available/kompass.conf`` with
+
+   .. code-block::
+
+      MDomain jdav-town.de
+
+      <VirtualHost *:443>
+          ServerName jdav-town.de
+          ServerAdmin digital@jdav-town.de
+
+          SSLEngine on
+          SSLOptions      StrictRequire
+
+          ErrorLog   /var/log/apache2/error.log
+          LogLevel warn
+
+          CustomLog /var/log/apache2/access.log vhost_combined
+          SSLProxyEngine on
+
+          ProxyPass / http://localhost:3000/
+          ProxyPassReverse / http://localhost:3000/
+          RequestHeader set X-Forwarded-Proto "https"
+          RequestHeader set X-Forwarded-Ssl on
+          RequestHeader set X-Forwarded-Port 443
+
+      </VirtualHost>
+
+   Replace the ``jdav-town.de`` domain by a domain pointing to your server. Now activate the site
+   and restart apache:
+
+   .. code-block:: console
+
+      a2ensite kompass.conf
+      systemctl restart apache2
+
+   The ``md`` module should now request an SSL certificate from Let's Encrypt, while this is still
+   pending you will receive a *connection not secure* error when visiting your domain. Check
+   ``/var/log/apache2/error.log`` for any possible errors. If everything worked, you will find there a
+   message similar to:
+
+   .. code-block::
+
+      [Mon Feb 10 ...] ... : The Managed Domain ... has been setup and changes will be activated on next (graceful) server restart.
+
+   In this case run
+
+   .. code-block:: console
+
+      systemctl restart apache2
+
+   again. You should now see the Kompass application at your domain!
+
+5. Update settings: Adapt ``/opt/kompass/config/settings.toml`` to your needs. If you followed the guide
+   as above, there should be no need to change anything in the ``[database]`` section.
+
+   .. note::
+      We recommend to initialize a ``git`` repository in the ``config`` folder to version control any changes
+      to the local configuration.
+
+6. Run the container in background mode: If everything is working, you can cancel the
+   ``docker compose up --build`` command from above and run
+
+   .. code-block:: console
+
+     docker compose up -d --build
+
+   Whenever you change your configuration or want to update to the latest version,
+   run this command again.
+
+7. Setup mail configuration: The Kompass application needs a working mailserver for forwarding incoming
+   mails on personal mail accounts and on configured forward mail addresses. You can either setup
+   a mailserver on your own or use the docker-based `Kompass-tailored mailserver`_.
+
+   For receiving mails, no further changes to the ``settings.toml`` are needed. For sending mails,
+   the ``[mail]`` sections needs to be updated with authentication details for an SMTP server.
+
+   If you are using (and have already installed) the docker-based mailserver, proceed as follows:
+   In the Kompass administrative interface create a new user account (i.e. login data) with
+   a strong password and without staff access. Then update the ``[mail]`` section
+   in the ``settings.toml`` accordingly with the created user name and password.
+   The ``host = 'host'`` setting is correct in this case and points to the underlying host.
+
+
+Local configuration
+===================
+
+If you followed the steps outlined in :ref:`user_manual/initial_installation`, you have a folder
+``/opt/kompass/config`` currently containing only a ``settings.toml``.
+
+While the ``settings.toml`` configures the most important options,
+in practice you might want to have more control over texts on the website, used logos
+or texts used in automatically generated emails. Here we will explain how to configure these.
+
+- Mail texts: To modify the standard email texts, create a file ``texts.toml`` in your config
+  directory. This could then for example look like this:
+
+  .. code-block::
+
+     confirm_mail = """
+     Hello {name},
+
+     please confirm your email address! For this use the cool link at {link}.
+
+     ..."""
+
+     new_unconfirmed_registration = """
+     Hi {name},
+
+     your group {group} has a new registration! ..."""
+
+- Templates: To override ``.html`` of the Kompass application, create a directory ``templates`` inside
+  your config directory. This is loaded as a regular templates directory by ``django``, hence
+  you can override anything that lives in one of the many ``templates`` directories in the main repository.
+
+  For example, to fill the impressum page with content, you need to create a file
+  ``templates/startpage/impressum_content.html``. In this file you can put any ``.html`` document and this
+  will be placed in the impressum page.
+
+  Typical templates to override here are (with their respective paths):
+
+  - ``templates/startpage/impressum_content``: impressum page
+  - ``templates/startpage/faq_content``: group registration FAQ
+  - ``templates/startpage/group_introduction``: introductory text placed above the group listing
+
+.. rubric:: Footnotes
+
+.. [#ip-address] The choice of the subnet ``10.26.42.0/24`` is arbitrarily chosen
+   from the `list of private IPv4 addresses`_. If by coincidence this specific subnet
+   is already used on your system, you can replace this by any other subnet from the linked
+   list. Note that in this case you need to replace all references to ``10.26.42.0/24``
+   and ``10.26.42.1`` by your choice, including in the ``networks`` section
+   of the ``docker-compose.yaml``.
+
+.. _official instructions: https://docs.docker.com/engine/install/debian/
+.. _Gitea: https://git.jdav-hd.merten.dev/digitales/kompass
+.. _list of private IPv4 addresses: https://en.wikipedia.org/wiki/Private_network#Private_IPv4_addresses
+.. _certificate agreement: https://letsencrypt.org/documents/LE-SA-v1.4-April-3-2024.pdf
+.. _Kompass-tailored mailserver: https://git.jdav-hd.merten.dev/digitales/kompass-mailserver