Add documentation, manual and screenshots preview

2026-07-23 21:24:48 +02:00
commit d6cda77aaf
40 changed files with 1571 additions and 0 deletions
@@ -0,0 +1,159 @@
+# Installation på Debian 13 amd64
+
+All rights reserved - Thomas / TuxiNet
+
+## Platform
+
+- Debian 13 amd64
+- `systemd`
+- OLA / `olad`
+- Node.js 20
+- `pnpm` 10.28.2
+- Standardport for TuxDMX: `8000/tcp`
+
+## 1. Forbered serveren
+
+```bash
+sudo apt-get update
+sudo apt-get install -y git curl
+git clone <privat-repo-url> tuxdmx
+cd tuxdmx
+```
+
+Hvis du deployer fra et ZIP-arkiv, saa udpak arkivet og skift til den mappe, foer du fortsaetter.
+
+## 2. Kildeplacering
+
+- Installeren finder repositoryet ud fra scriptets egen placering.
+- Det virker baade ved Git-clone og ved SFTP-kopieret projektmappe.
+- `sudo` maa ikke flytte source root til `/root`, fordi scriptet ikke bruger `$HOME` som kilde.
+
+## 3. Installer TuxDMX
+
+Interaktiv installation:
+
+```bash
+sudo ./scripts/install-linux.sh
+```
+
+Ikke-interaktiv installation:
+
+```bash
+sudo ./scripts/install-linux.sh --non-interactive --force
+```
+
+Hvis du allerede har en gyldig `frontend/dist`, kan du eksplicit springe frontend-build over:
+
+```bash
+sudo ./scripts/install-linux.sh --non-interactive --force --skip-frontend-build
+```
+
+Dette flag virker kun, hvis `frontend/dist/index.html` allerede findes.
+
+Scriptet:
+
+- validerer Debian 13 amd64,
+- installerer Python 3, `python3-venv`, SQLite, OLA, OLA Python-binding, Node.js 20-værktøjskæde og `olad`,
+- laaser frontend-tooling til `pnpm` 10.28.2,
+- bygger frontenden selv med `pnpm install --frozen-lockfile` og `pnpm build`,
+- opretter systembrugeren `tuxdmx`,
+- opretter `/opt/tuxdmx`, `/var/lib/tuxdmx`, `/var/log/tuxdmx` og `/etc/tuxdmx`,
+- bruger staging i `/opt/tuxdmx.new`,
+- normaliserer filrettigheder efter kopiering, ogsaa efter SFTP-upload,
+- opretter virtualenv med `--system-site-packages`,
+- installerer `requirements.lock`, koerer `pip check` og kontrollerer `greenlet`, `sqlalchemy` og `ola`,
+- koerer alle Alembic migrations som brugeren `tuxdmx`,
+- installerer og aktiverer `tuxdmx.service`,
+- health-checker `http://127.0.0.1:8000/api/v1/health`,
+- viser automatisk `systemctl status` og `journalctl`, hvis service-start fejler.
+
+Eksisterende database og konfiguration bevares, fordi de ligger i `/var/lib/tuxdmx` og `/etc/tuxdmx`.
+
+## 4. Permanente stier
+
+- Appkode: `/opt/tuxdmx`
+- Frontend build: `/opt/tuxdmx/frontend/dist`
+- Database og runtime-data: `/var/lib/tuxdmx`
+- Backups: `/var/lib/tuxdmx/backups`
+- Diagnostics: `/var/lib/tuxdmx/diagnostics`
+- Uploads: `/var/lib/tuxdmx/uploads`
+- Fixture-cache: `/var/lib/tuxdmx/fixtures`
+- Logs: `/var/log/tuxdmx`
+- Environment: `/etc/tuxdmx/tuxdmx.env`
+
+## 5. Kontroller drift
+
+```bash
+systemctl status tuxdmx.service
+systemctl status olad
+curl -fsS http://127.0.0.1:8000/api/v1/health
+curl -fsS http://127.0.0.1:8000/
+```
+
+Web UI:
+
+```text
+http://<server-ip>:8000/
+```
+
+## 6. Update
+
+```bash
+sudo ./scripts/update-linux.sh
+```
+
+Med eksisterende `frontend/dist`:
+
+```bash
+sudo ./scripts/update-linux.sh --skip-frontend-build
+```
+
+Update-scriptet:
+
+- tager backup af app, data og konfiguration,
+- bygger ny frontend eller genbruger eksisterende `dist`,
+- kopierer ny kode og `frontend/dist`,
+- geninstallerer Python-afhaengigheder,
+- koerer migrationer,
+- geninstallerer `tuxdmx.service`,
+- genstarter `olad` og `tuxdmx.service`,
+- ruller tilbage ved fejl.
+
+## 7. Uninstall
+
+```bash
+sudo ./scripts/uninstall-linux.sh
+sudo ./scripts/uninstall-linux.sh --purge-app
+sudo ./scripts/uninstall-linux.sh --purge-app --purge-data
+```
+
+## 8. Logs og health checks
+
+```bash
+journalctl -u tuxdmx.service -f
+journalctl -u olad -f
+systemctl status tuxdmx.service --no-pager --full
+curl -fsS http://127.0.0.1:8000/api/v1/health
+```
+
+- Health fejler: `journalctl -u tuxdmx.service -n 200 --no-pager`
+- OLA-binding mangler: kontroller at `python3-ola` eller `ola-python` findes i Debian-repositoriet
+- OLA-runtime fejler: `journalctl -u olad -n 200`
+- DB-fejl: `sqlite3 /var/lib/tuxdmx/tuxdmx.db "PRAGMA integrity_check;"`
+- Frontend-build fejler: kontroller `node --version`, `pnpm --version` og `package.json` packageManager-feltet
+- Importfejl `No module named 'app'`: kontrollér at `/opt/tuxdmx/backend/app/main.py` findes
+- Permission-fejl efter SFTP: installeren normaliserer rettigheder til `root:tuxdmx`, 0755 paa mapper og 0644 paa kode/dist-filer
+
+## 9. Root causes rettet i denne leverance
+
+- `greenlet` manglede i Python-lockfile, selv om SQLAlchemy async-laget kraever det
+- frontend-build var manuel i stedet for en del af installeren
+- pnpm-version var ikke fastlaast og kunne glide til en inkompatibel udgave
+- backend-layoutet i `/opt/tuxdmx` blev ikke verificeret eksplicit
+- relative runtime-stier gav `PermissionError` og uforudsigelig working directory-adfaerd
+- SFTP-overfoerte rettigheder blev kopieret ukritisk
+- systemd health-check viste ikke automatisk de egentlige servicefejl
+
+## 10. Hardwarestatus
+
+Installationsscriptet er lavet til Debian 13 amd64. USB-DMX og OLA-output er verificeret af systemejeren på den fysiske target-host, men Codex har ikke selv udført fysisk hardwaretest i denne workspace-session. Brug [HARDWARE-VALIDATION.md](HARDWARE-VALIDATION.md) til gentest, ændringsvalidering og nye installationer.