TATAMI Dokumentation

TATAMI installieren

Vorbereitung

Diese Anleitung geht davon aus, dass Sie ein Computersystem haben, das die folgenden Anforderungen erfüllt:

  • Betriebssystem: Ubuntu 22.04 LTS, 24.04 LTS oder vergleichbar

    Beachte: Ubuntu 25.04 unterstützt zurzeit noch nicht die notwendige wkhtmltopdf-Version

  • Installiert sind: APT und Git

Beachten Sie, dass diese Anforderungen nur für den Server, auf dem TATAMI installiert werden soll, gelten. Für die Clients, die mit dem TATAMI-Server verbunden werden sollen, genügt grundsätzlich ein hinreichend moderner Webbrowser.

Verbinden Sie sich mit einem Benutzerkonto, das Root-Rechte hat, auf dieses Computersystem.

Systembenutzer erstellen

Zunächst muss ein TATAMI-Systembenutzer erstellt werden, über den die TATAMI-Anwendung später laufen wird.

Es wird empfohlen, den TATAMI-Systembenutzer tatami zu nennen und als Installationspfad /var/tatami zu verwenden.

Führen Sie die folgenden Kommandozeilenbefehle aus, um diese empfohlene Konfiguration herzustellen:

sudo adduser tatami
sudo usermod -G www-data tatami
sudo mkdir /var/tatami
sudo chown tatami /var/tatami -R
sudo chgrp www-data /var/tatami -R

Abhängigkeiten installieren

Anschließend müssen die Abhängigkeiten installiert werden.

Aktualisieren Sie zunächst die Paketquellen:

sudo apt update

Installieren Sie dann die notwendigen Abhängigkeiten:

sudo apt install python3 python3-pip python3-venv nginx wkhtmltopdf

MariaDB einrichten

TATAMI benötigt zudem eine Datenbank. Es wird empfohlen, hierfür MariaDB zu verwenden.

Wenn Sie dies noch nicht getan haben, müssen Sie als erstes MariaDB installieren:

sudo apt install mariadb-server libmariadb3 libmariadb-dev
sudo mysql_secure_installation

Notieren Sie sich dabei das Passwort, das sie setzen, da dieses später in die TATAMI-Konfiguration eingetragen werden muss.

Wenn alles funktioniert hat, sollten Sie mit dem folgenden Befehl sehen, dass MariaDB läuft:

sudo systemctl status mariadb

Anschließend müssen Sie eine Datenbank für TATAMI aufsetzen.

Wählen Sie sich zunächst in die MariaDB-Konsole ein:

sudo mariadb

Dort erstellen Sie dann eine Datenbank namens tatami:

CREATE DATABASE tatami;

Anschließend beenden Sie die Konsole mit exit.

TATAMI herunterladen

Als nächstes kann TATAMI heruntergeladen werden.

Dazu melden Sie sich erst mit dem TATAMI-Systembenutzer an und navigieren zu dem Verzeichnis, in dem TATAMI installiert werden soll:

sudo su tatami
cd /var/tatami

Dort können Sie dann TATAMI klonen:

git clone https://github.com/tatami-jtm/tatami.git .

Wenn Sie die jeweils neueste stabile TATAMI-Version verwenden wollen, was für Produktivsysteme empfohlen wird, verwenden Sie die folgenden Befehle:

git checkout release
git pull

Wenn Sie stattdessen eine bestimmte TATAMI-Version verwenden wollen, müssen Sie diese Version auswählen. Ersetzen Sie dabei <version> durch den auf GitHub angezeigten Namen des Versionstags:

git checkout tags/<version>

Python-Abhängigkeiten installieren

Es ist generell empfehlenswert, TATAMI in einer Python Virtual Environment zu installieren.

Verwenden Sie die folgenden beiden Befehle, um eine solche einzurichten:

python3 -m venv venv
source venv/bin/activate

Gehen Sie dann in den Ordner Webapp und installieren dort die benötigten Abhängigkeiten:

cd webapp
pip install -r requirements.txt
pip install gunicorn mariadb

TATAMI konfigurieren

Anschließend können Sie die TATAMI-Konfigurationsdatei erstellen. Diese muss unter webapp/config.py abgelegt werden.

Verwenden Sie folgende Vorlage für die Konfigurationsdatei, aber passsen Sie alle Werte an Ihr System an:

SETTINGS = {
    "INSTANCE_PATH": "/var/tatami/webapp",
    "ALLOW_SETUP": True,
    "SECRET_KEY": "<some secret key>",
    "SQL_URL": "mariadb+mariadbconnector://<dbuser>:<dbpassword>@127.0.0.1:3306/tatami"
    "WKHTMLTOPDF_PATH": "/usr/bin/wkhtmltopdf"
}

Um den wkhtmltopdf-Pfad herauszufinden, können Sie den Befehl which wkhtmltopdf ausführen.

Gehen Sie anschließend wieder in das Installationsverzeichnis von TATAMI und richten dort einen Verweis auf die Konfigurationsdatei ein sowie einen Ordner, in den temporäre Dateien abgelegt werden können:

cd ..
ln -s webapp/config.py config.py
mkdir temp

Datenbank aufsetzen

Wenn alles richtig funktioniert hat, können Sie jetzt die Datenbank aufsetzen lassen. Führen Sie dazu folgenden Befehl aus:

python3 setup.py

Sie sollten keine Fehlermeldung erhalten.

Systemd-Dienst erstellen

Hat die Einrichtung der Datenbank funktioniert, müssen Sie als nächstes einen Systemd-Dienst für TATAMI einrichten. Dieser wird später von Nginx verwendet werden, um TATAMI auszuführen.

Melden Sie sich zunächst wieder mit einem Benutzerkonto, das Root-Rechte hat, an.

Erstellen Sie dann eine Datei namens /etc/systemd/system/tatami.service mit folgendem Inhalt:

[Unit]
Description=TATAMI Gunicorn Service
After=network.target

[Service]
User=tatami
Group=www-data
WorkingDirectory=/var/tatami          
Environment="PATH=/var/tatami/venv/bin"
ExecStart=/var/tatami/venv/bin/gunicorn --workers 3 --bind unix:tatami.sock -m 007 wsgi:app

[Install]
WantedBy=multi-user.target

Starten und aktivieren sie diesen Dienst:

sudo systemctl start tatami
sudo systemctl enable tatami

Sie können mit dem folgenden Befehl den Status des Dienstes überprüfen:

sudo systemctl status tatami

Nginx-Konfiguration erstellen

Zuletzt müssen Sie eine Nginx-Konfiguration erstellen.

Schreiben Sie in eine Datei unter /etc/nginx/sites-available/tatami folgenden Inhalt:

server {
    listen 80;
    server_name <yourdomain>;

    location / {
        include proxy_params;
        proxy_pass http://unix:/var/tatami/tatami.sock;
    }
}

Dabei müssen Sie die Angabe <yourdomain> durch den Domainnamen, unter dem TATAMI laufen soll ersetzen. Wenn ein Zugriff nur über eine IP-Adresse ausreicht, können Sie die Zeile auch weglassen.

Aktivieren Sie die Nginx-Konfiguration durch den folgenden Befehl:

sudo ln -s /etc/nginx/sites-available/tatami /etc/nginx/sites-enabled

Sie können prüfen, ob Sie alles richtig geschrieben haben, indem Sie diesen Befehl ausführen:

sudo nginx -t

Ergibt diese Prüfung keinen Fehler, können Sie Nginx neustarten:

sudo systemctl restart nginx

Ggf. müssen Sie noch in Ihrer Firewall den HTTP-Zugriff erlauben, bspw. durch den folgenden Befehl:

sudo ufw allow 'Nginx Full'

Optional: HTTPS

Wenn Ihre TATAMI-Installation aus dem öffentlichen Internet über einen Domainnamen erreichbar ist, ist es empfohlen, HTTPS zu verwenden. Am einfachsten geht das über den Let's Encrypt Certbot.

Hierzu müssen Sie nur die beiden folgenden Befehle ausführen, wobei <yourdomain> wiederum durch Ihren Domainnamen ersetzt wird, und den Anweisungen dort folgen:

sudo apt install python3-certbot-nginx
sudo certbot --nginx -d <yourdomain>

Einrichtung der Installation

Ihre TATAMI-Installation sollte jetzt über einen Webbrowser zugänglich sein. Verwenden Sie die IP-Adresse bzw. den Domainnamen, um TATAMI zu öffnen.

Als erstes müssen Sie einen Administrationsaccount anlegen. Drücken Sie dazu auf Zum Administrationsbereich. Wählen Sie Register und folgen Sie den Anweisungen.

Anschließend gehen Sie auf http://<yourdomain>/setup. Folgen Sie dort den Anweisungen, um Ihrem Benutzerkonto Administratorenrechte zu geben und ggf. weitere Daten einzurichten.

Abschluss der Installation

Abschließend sollten Sie noch aus Sicherheitsgründen den Zugriff auf das Setup-Tool sperren.

Gehen Sie wieder zur Konfigurationsdatei, z. B. mit den folgenden Befehlen:

sudo su tatami
cd /var/tatami/webapp
nano config.py

Ersetzen Sie sodann in der Zeile mit ALLOW_SETUP den Wert False durch den Wert True.

Schließen Sie den Editor und melden Sie sich wieder mit einem Konto an, das Root-Zugang hat.

Führen Sie dann den folgenden Befehl aus, um die Änderungen anzuwenden:

sudo systemctl restart tatami

Damit haben Sie TATAMI erfolgreich installiert.