# 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.