From 1cc2a50df86d59a6b06e345a34e491735cbb9b9d Mon Sep 17 00:00:00 2001
From: Masin  Al-Dujaili <masin.wiedner@wikimedia.de>
Date: Mon, 11 Nov 2024 10:58:00 +0000
Subject: [PATCH] documentation on how to use systemctl (or service)

Puppet deploys a service unit file so EVA can be started at boot time and logs go the journal instead of some logfile at some opaque location
---
 README.md | 140 ++++++++++++++++++++++++++++++------------------------
 1 file changed, 79 insertions(+), 61 deletions(-)

diff --git a/README.md b/README.md
index 39d9970..377739b 100644
--- a/README.md
+++ b/README.md
@@ -1,61 +1,79 @@
-# eva
-
-A simple tool for on- and offboarding people in a mid sized organisation.
-
-"EVA" is an german acronym for "Eintritt, Veränderung, Austritt",
-meaning "Onboarding, Change, Offboarding"
-
-# development
-
-- install gettext for instance via "apt install gettext" for translations
-
-- set up a virtual environment with virtualenvwrapper or some other
-environment managing tool
-
-- use this environment and do
-
-    pip install django django-multiselectfield django-formtools django-allauth
-
-- clone this repository
-
-- ln -sr eva/settings_development.py eva/settings.py
-
-- initialise your database with
-
-    python manage.py migrate
-
-- start your development server with
-
-    python manage.py runserver
-
-# oauth
-
-- You need to add oauth information in the django backend via .../admin in "Social Accounts"
-
-# production
-
-- you can use gunicorn as server for example instead of the django development server.
-
-- we use whitenoise for serving static files
-
-- we still use the development SQLITE database from django
-
-do the following in the project main directory:
-
-  ln -sr eva/settings_production.py eva/settings.py
-
-edit /secrets.json to contain something similar to
-
-  {
-    "SECRET_KEY": "THIS IS ANOTHER SECRET!"
-  }
-
-run the following commands:
-
-  python3 manage.py migrate
-  python3 manage.py collectstatic
-  django-admin compilemessages
-
-server starts with
-
-  export PYTHONUNBUFFERED=TRUE; nohup gunicorn --forwarded-allow-ips="*" -b '0:8000' eva.wsgi &> logfile &
+# eva
+
+A simple tool for on- and offboarding people in a mid sized organisation.
+
+"EVA" is an german acronym for "Eintritt, Veränderung, Austritt",
+meaning "Onboarding, Change, Offboarding"
+
+# development
+
+- install gettext for instance via `apt install gettext` for translations
+- set up a virtual environment with virtualenvwrapper or some other environment managing tool
+- use this environment and do
+```
+pip install django django-multiselectfield django-formtools django-allauth
+```
+- clone this repository
+- `ln -sr eva/settings_development.py eva/settings.py`
+- initialise your database with `python manage.py migrate`
+- start your development server with `python manage.py runserver`
+
+# oauth
+
+- You need to add oauth information in the django backend via .../admin in "Social Accounts"
+
+# production
+
+- you can use gunicorn as server for example instead of the django development server.
+- we use whitenoise for serving static files
+- we still use the development SQLITE database from django
+
+do the following in the project main directory:
+```
+  ln -sr eva/settings_production.py eva/settings.py
+```
+edit /secrets.json to contain something similar to
+```
+  {
+    "SECRET_KEY": "THIS IS ANOTHER SECRET!"
+  }
+```
+run the following commands:
+```
+  python3 manage.py migrate
+  python3 manage.py collectstatic
+  django-admin compilemessages
+```
+
+As root create a file `/etc/systemd/system` (it's already deployed by puppet when the corresponding manifest is applied):
+
+```
+# /etc/systemd/system/eva.service
+#
+
+[Unit]
+Description=gunicorn EVA daemon
+After=network.target
+
+[Service]
+Type=simple
+User=eva
+Group=eva
+RuntimeDirectory=eva
+WorkingDirectory=/home/eva/eva
+Environment=PYTHONUNBUFFERED=TRUE
+ExecStart=/usr/bin/gunicorn  --forwarded-allow-ips='*' -b '0:8000' eva.wsgi
+ExecReload=/bin/kill -s HUP $MAINPID
+KillMode=mixed
+TimeoutStopSec=5
+PrivateTmp=true
+
+[Install]
+WantedBy=multi-user.target
+```
+
+Adapt the paths in the file accordingly. Then, still as root, run:
+```
+systemctl enable --now eva.service
+```
+This enables the service to start at boot time and starts it immediately now. The daemon logs to the journal. You can see the last 10 lines by running `systemctl status eva.service` or the whole log by running `journalctl -u eva.service`. The usual switches to manipulate that output are available.
\ No newline at end of file