From dc9d5a750e28823b1f3d9e385a4e8634d5d929db Mon Sep 17 00:00:00 2001
From: Mateusz <mateusz.piecuch@yahoo.com>
Date: Sun, 1 Nov 2026 16:58:32 +0100
Subject: [PATCH] readme update

---
 server/README.md         | 63 ++++++++++++++++++++++++++++++++++++++++
 server/vps_ssh_tunnel.sh |  2 +-
 2 files changed, 64 insertions(+), 1 deletion(-)

diff --git a/server/README.md b/server/README.md
index 67136fe..fb8d596 100644
--- a/server/README.md
+++ b/server/README.md
@@ -135,6 +135,32 @@ flask --app app create-admin
 Running `create-admin` for an existing username resets its password and grants
 `is_admin=True`. Log in at `/login`; you land on `/home`.
 
+When the main app runs as a systemd service, run the command as the same user
+and from the same directory as the service (see `yggdrasil.service`):
+
+```bash
+cd /home/mateusz/prog/yggdrasil/server
+sudo -u mateusz .venv/bin/flask --app app create-admin
+```
+
+To pass credentials without an interactive prompt:
+
+```bash
+sudo -u mateusz env ADMIN_USERNAME=admin ADMIN_PASSWORD='secret' \
+    .venv/bin/flask --app app create-admin
+```
+
+If the unit sets `USERS_DB_PATH` or `USERS_DATABASE_URL`, add the same variable
+to the command, for example:
+
+```bash
+sudo -u mateusz env USERS_DB_PATH=/data/main_app.db \
+    .venv/bin/flask --app app create-admin
+```
+
+The service does not need to be restarted; the new account is used on the next
+login.
+
 ## Running
 
 The first argument selects the app (`main` or `sensors`), the second the port.
@@ -199,12 +225,49 @@ SENSORS_API_URL=http://localhost:5432 ./run-prod.sh main 8000
 
 ### systemd services
 
+Main app only:
+
+```bash
+sudo cp yggdrasil.service /etc/systemd/system/
+sudo systemctl daemon-reload
+sudo systemctl enable --now yggdrasil
+```
+
+Main app and sensors API:
+
 ```bash
 sudo cp yggdrasil.service yggdrasil-sensors.service /etc/systemd/system/
 sudo systemctl daemon-reload
 sudo systemctl enable --now yggdrasil yggdrasil-sensors
 ```
 
+Check whether the main service is active:
+
+```bash
+systemctl status yggdrasil
+systemctl is-active yggdrasil      # prints: active / inactive / failed
+systemctl is-enabled yggdrasil     # prints: enabled / disabled
+```
+
+Quick HTTP check:
+
+```bash
+curl -I http://localhost:8000/login
+ss -ltnp | grep ':8000'
+```
+
+Logs:
+
+```bash
+journalctl -u yggdrasil -f
+journalctl -u yggdrasil -n 50 --no-pager
+journalctl -u yggdrasil-sensors -f   # if the sensors service is installed
+```
+
+The unit files currently use `User=mateusz` and
+`WorkingDirectory=/home/mateusz/prog/yggdrasil/server`; adjust them if the
+deployment path or user is different.
+
 | Service | Port | Routes |
 |---|---|---|
 | main | 8000 | `/`, `/login`, `/home`, `/sensors`, `/api/docs`, `/api/*` (proxy) |
diff --git a/server/vps_ssh_tunnel.sh b/server/vps_ssh_tunnel.sh
index 0ca32e9..e3faa13 100755
--- a/server/vps_ssh_tunnel.sh
+++ b/server/vps_ssh_tunnel.sh
@@ -1 +1 @@
-ssh -R 5432:localhost:8001 vps
+ssh -R 8001:localhost:8000 vps