TuxDMX-WebUI/INSTALL-LINUX.md

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

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:

sudo ./scripts/install-linux.sh

Ikke-interaktiv installation:

sudo ./scripts/install-linux.sh --non-interactive --force

Hvis du allerede har en gyldig frontend/dist, kan du eksplicit springe frontend-build over:

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

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:

http://<server-ip>:8000/

6. Update

sudo ./scripts/update-linux.sh

Med eksisterende frontend/dist:

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

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

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 til gentest, ændringsvalidering og nye installationer.