Installation

Vor der Installation#

Stelle sicher, dass:

• der Server die Systemanforderungen erfüllt,
• die Systemzeit automatisch synchronisiert wird (sudo timedatectl set-ntp true),
• du deinen Lizenzschlüssel zur Hand hast,
• du weisst, unter welcher Domain die Plattform erreichbar sein soll, zum Beispiel ki.firma.ch,
• du dich für eine Zertifikatsart entschieden hast: automatisch über deinen DNS-Anbieter oder ein eigenes Firmenzertifikat (siehe Domain und Zertifikate).

Die Domain ist optional. Ohne Domain ist die Plattform nur direkt auf dem Server erreichbar, und der Firmen-Login bleibt ausgeschaltet. Für einen ersten Test genügt das.

Das Werkzeug installieren#

curl -fsSL https://swaiz.ch/install | sh

Das Installationsskript ermittelt die aktuelle Version, erkennt Betriebssystem und Prozessorarchitektur, lädt das passende Archiv, prüft dessen Echtheit und legt aictl unter /usr/local/bin/aictl ab. Dort finden es alle Benutzer und auch sudo. Bist du nicht als root angemeldet, ruft das Skript selbst sudo auf und fragt nach deinem Passwort.

Für die Echtheitsprüfung braucht das Skript openssl, das auf Ubuntu-Servern vorinstalliert ist. Lässt sich die Echtheit nicht bestätigen, bricht es ab und installiert nichts.

Eine bestimmte Version installierst du so:

curl -fsSL https://swaiz.ch/install | sh -s -- v1.2.3
# oder
curl -fsSL https://swaiz.ch/install | AICTL_VERSION=v1.2.3 sh

Hinweis: Die Variable muss vor sh stehen, nicht vor curl, sonst kommt sie beim Skript nicht an.

Das Werkzeug selbst ist frei herunterladbar. Die Lizenz wird erst bei der Installation der Plattform geprüft.

Die Plattform installieren#

sudo aictl install --license LIC-XXXX-XXXX-XXXX-XXXX

Ohne --license fragt die Installation nach dem Schlüssel. Ist der Server bereits aktiviert, verwendet sie automatisch den gespeicherten Schlüssel. Eine erneute Installation klappt dann auch, wenn der Lizenzserver gerade nicht erreichbar ist, solange die bestehende Aktivierung gilt. Mehr dazu unter Lizenz.

Die Installation stellt alle Fragen zu Beginn. Danach läuft sie ohne weitere Eingaben durch. Nur ganz am Schluss kann noch eine Frage zu DNS-Einträgen kommen.

Die Fragen der Installation#

Jede Frage lässt sich auch mit einer Option beantworten. Ist eine Option gesetzt, entfällt die Frage. Mit Esc oder Ctrl-C brichst du eine Frage und damit die Installation ab.

1. Lizenzschlüssel#

Nur auf einem Server, der noch nie aktiviert wurde, und nur ohne --license. Die Eingabe wird automatisch in Grossbuchstaben umgewandelt und muss dem Format LIC-XXXX-XXXX-XXXX-XXXX entsprechen.

2. Name dieses Servers#

Unter diesem Namen erscheint die Modell-Engine des Hauptservers in der Rechnerliste (aictl node ls). Vorschlag ist local, mit Enter übernimmst du ihn. Erlaubt sind 1 bis 63 Zeichen aus Kleinbuchstaben, Ziffern und Bindestrichen, beginnend mit einem Buchstaben oder einer Ziffer. Der Name darf nicht bereits von einem angehängten Modell-Rechner verwendet werden.

3. Domain und Zertifikat#

Zuerst fragt die Installation nach der Domain, unter der die Plattform laufen soll, zum Beispiel ki.firma.ch. Darunter entstehen Adressen wie chat.ki.firma.ch. Gib nur den Domainnamen ein, ohne https://, Port oder Pfad. Lässt du das Feld leer, läuft die Plattform ohne Domain, nur über die lokalen Ports und ohne Verschlüsselung.

Mit einer Domain folgt die Wahl des Zertifikats:

• Let's Encrypt (auto): Die Plattform holt sich ein Zertifikat für alle Adressen unter deiner Domain und erneuert es selbstständig. Dafür wählst du deinen DNS-Anbieter aus einer durchsuchbaren Liste, gibst optional eine Kontakt-E-Mail an und hinterlegst den API-Schlüssel deines Anbieters. Bei Cloudflare ist das der Schlüssel CF_DNS_API_TOKEN. Drückst du beim Schlüssel nur Enter, kannst du ihn später mit sudo aictl secret set und sudo aictl apply nachreichen.
• Eigenes Zertifikat: Du gibst den Pfad zum Zertifikat an, den Pfad zum privaten Schlüssel (leer lassen bei PFX/PKCS#12) und, falls nötig, das Passwort. Das Zertifikat wird sofort geprüft. Fehlt das Stammzertifikat einer eigenen Zertifizierungsstelle, fragt die Installation nach dessen Pfad. Klappt das nicht, kannst du es erneut versuchen.

Eine Variante «ohne Zertifikat» gibt es in dieser Frage nicht. Details zu beiden Wegen stehen unter Domain und Zertifikate.

4. Erster Administrator#

Die E-Mail-Adresse des ersten Administrators, mit dem du dich in der Benutzerverwaltung anmeldest und alle weiteren Konten anlegst. Vorschlag ist [email protected].

Wichtig: Diese Adresse wird nur beim allerersten Start des Firmen-Logins übernommen. Willst du sie später ändern, tust du das direkt in der Benutzerverwaltung.

5. Branding#

Firmenname, Adresse des Logos und Adresse des Favicons. Logo und Favicon müssen öffentlich erreichbare Bilder im Format PNG oder JPEG sein. Ein leeres Feld lässt die Angabe weg. Diese Frage erscheint nur, wenn noch gar nichts zum Branding eingestellt ist. Mehr dazu unter Branding.

6. DNS-Einträge (am Schluss)#

Nutzt du automatische Zertifikate mit Cloudflare und ist der Schlüssel hinterlegt, prüft die Installation am Ende, ob alle Adressen bereits auflösen. Fehlen Einträge, schlägt sie vor, diese direkt bei Cloudflare anzulegen. Du kannst einzelne Einträge abwählen oder mit Esc alle überspringen. Bei anderen DNS-Anbietern zeigt die Installation nur an, welche Einträge fehlen.

Ohne Terminal#

Läuft die Installation ohne Terminal, zum Beispiel aus einem Automatisierungswerkzeug, gilt:

Hinweis: Die Fragen lesen direkt vom Terminal, nicht von der Standardeingabe. In einer SSH-Sitzung unterdrückt < /dev/null sie deshalb nicht. Nur wenn gar kein Terminal vorhanden ist, gelten die Standardwerte.

Was bei der Installation passiert#

1. aictl kopiert sich nach /usr/local/bin/aictl, falls es nicht schon von dort läuft.
2. Der Server wird erkannt: Betriebssystem, Prozessorarchitektur, Grafikkarte und eine Hardware-Kennung.
3. Die bisherigen Einstellungen werden geladen. Bei einer Erstinstallation beginnt aictl mit leeren Einstellungen.
4. Die Lizenz wird online aktiviert und fest an diesen Server gebunden.
5. Die Fragen von oben werden gestellt.
6. Fehlende Systembestandteile werden installiert, darunter die Laufzeitumgebung der Plattform.
7. Die Modell-Engine wird eingerichtet. Fehlt sie, wird sie installiert. Eine bereits vorhandene Modell-Engine wird nicht aktualisiert, aber bei jeder Installation neu gestartet.
8. Logo und Favicon werden auf den Server geladen.
9. Die Konfiguration wird erzeugt, alle Bestandteile werden heruntergeladen und gestartet. Vorher prüft aictl, ob die benötigten Ports frei sind.
10. aictl wartet, bis alle Dienste bereit sind. Beim ersten Mal dauert das einige Minuten, standardmässig wartet die Installation bis zu 10 Minuten.
11. Firmen-Login, KI-Zentrale, Automationen und Websuche werden miteinander verbunden, und bereits gekaufte Erweiterungen in den Einstellungen werden eingerichtet.
12. Fehlende DNS-Einträge werden angelegt oder angezeigt.
13. Der Hintergrunddienst wird eingerichtet, damit die Plattform nach einem Neustart automatisch wieder läuft.
14. Der Benutzer, der sudo aufgerufen hat, erhält Lesezugriff (siehe unten).
15. Eine abschliessende Gesundheitsprüfung läuft, danach folgt die Zusammenfassung.

Erscheint während der Installation eine Warnung, dass Verwaltungsbereiche oder Erweiterungen ohne Anmeldung erreichbar sind, nimm sie ernst. Sie zeigt eine Einstellung, die Daten ungeschützt ins Netz stellt.

Die Zusammenfassung#

Am Ende zeigt die Installation alle wichtigen Adressen, zum Beispiel:

swaiz is installed and running.
  Chat UI:      https://chat.ki.firma.ch
  Chat (local): http://localhost:3000
  Router (API): http://localhost:4000/v1
  Users & SSO:  https://auth.ki.firma.ch/if/admin/
                sign in as akadmin / <passwort>  (change it after the first login)
                create users there and put them in "aictl-users" — they can then use the Chat UI
  Inspect:      sudo aictl status
  Add a node:   sudo aictl node join-command <name>  (prints the command to run on the new node)
  Add a model:  sudo aictl model install <model> [--node <name>]

Wichtig: Die Zusammenfassung enthält das Startpasswort des Administrationskontos im Klartext. Achte darauf, wo die Ausgabe landet, zum Beispiel in Protokollen oder Bildschirmfotos, und ändere das Passwort nach der ersten Anmeldung.

Ohne Domain fehlt die Zeile «Chat (local)», und die Adressen zeigen auf die lokalen Ports, etwa http://localhost:3000 für den Chat. Den Schlüssel zum Anhängen weiterer Rechner zeigt die Installation bewusst nicht an. Den vollständigen Befehl dafür gibt sudo aictl node join-command aus.

Alle Optionen#

Für Spezialfälle gibt es weitere Optionen, etwa für die Netzwerkadresse der Modell-Engine oder um den Lesezugriff ohne sudo abzuschalten. sudo aictl install --help listet sie auf, die Entwicklerdokumentation im Kundenportal erklärt sie im Kapitel «Stack anpassen».

Sobald du eine der Optionen --base-domain, --tls-mode, --dns-provider, --acme-email, --internal oder --external angibst, stellt die Installation keine Frage zu Domain und Zertifikat mehr. Gib in diesem Fall alle nötigen Angaben als Optionen mit.

Achtung: --bind-address 0.0.0.0 macht die internen Verwaltungsports aus dem ganzen Netz erreichbar, und zwar ohne Anmeldung, auch am Firmen-Login vorbei. Verwende das nur auf Test-Servern in einem vertrauenswürdigen Netz. Mit einer einzelnen Adresse wie 10.0.0.5 sind die Ports nur auf dieser Netzwerkschnittstelle erreichbar, ebenfalls ohne Anmeldung.

Ohne Rückfragen installieren#

Für automatisierte Installationen gibst du alle Antworten als Optionen mit.

Mit automatischem Zertifikat über Cloudflare. Hinterlege den API-Schlüssel schon vor der Installation, dann wird das Zertifikat beim ersten Start geholt:

printf %s "$CF_TOKEN" | sudo aictl secret set CF_DNS_API_TOKEN --stdin
sudo aictl install \
  --license LIC-XXXX-XXXX-XXXX-XXXX \
  --base-domain ki.firma.ch --tls-mode auto --dns-provider cloudflare \
  --acme-email [email protected] \
  --auth-admin-email [email protected] \
  --brand-name "Muster AG" --brand-logo-url https://firma.ch/logo.png \
  --node-name server1

Hast du den Schlüssel nicht vorher hinterlegt, setzt du ihn nach der Installation mit sudo aictl secret set CF_DNS_API_TOKEN --stdin und übernimmst ihn mit sudo aictl apply.

Mit eigenem Firmenzertifikat. Das Zertifikat muss vor der Installation importiert sein, sonst bricht sie ab, nachdem die Systembestandteile bereits eingerichtet sind:

sudo aictl proxy set-cert --cert /root/ki.pfx --password-file /root/ki-passwort.txt
sudo aictl install \
  --license LIC-XXXX-XXXX-XXXX-XXXX \
  --base-domain ki.firma.intern --tls-mode provided --internal \
  --auth-admin-email [email protected]

Nur im internen Netz, ohne Domain:

sudo aictl install --license LIC-XXXX-XXXX-XXXX-XXXX --internal

Da --internal eine Option zu Domain und Zertifikat ist, fragt die Installation in diesem Fall nicht nach einer Domain.

Mit einer vorbereiteten Einstellungsdatei: sudo aictl install --spec meine-einstellungen.yaml. Den Aufbau dieser Datei beschreibt die Entwicklerdokumentation im Kapitel «Stack anpassen».

Installation erneut ausführen#

Die Installation kann beliebig oft wiederholt werden. Sie setzt auf den gespeicherten Einstellungen auf und bringt in Ordnung, was fehlt oder falsch ist. Das ist auch der einfachste Weg, wenn nach einer Störung etwas nicht mehr stimmt.

Dabei gilt:

• Gespeicherte Einstellungen wie Domain, Administrator, Servername und Erweiterungen bleiben erhalten. Jede Option, die du mitgibst, ändert genau diesen einen Wert.
• Der Lizenzschlüssel wird wiederverwendet. Die Lizenz wird aber bei jeder Installation erneut online aktiviert, der Lizenzserver muss also erreichbar sein. Für Reparaturen ohne Internet nutzt du sudo aictl apply.
• Passwörter und Schlüssel der Plattform werden nie neu erzeugt. Deine Daten bleiben unangetastet.
• Eine erneute Installation ist kein reiner Leerlauf: Sie lädt die Bestandteile erneut herunter, startet die Modell-Engine neu und fragt auf einem Terminal nach Angaben, die bisher leer sind, zum Beispiel nach der Domain oder dem Branding.
• Mit - als Wert entfernst du eine Einstellung wieder, zum Beispiel --base-domain - oder --dns-provider -. --external nimmt --internal zurück. Ein leerer Wert wie --base-domain "" ändert nichts.
• Mit sudo aictl install --base-domain ki.firma.ch ergänzt du eine bestehende Installation um eine Domain. Gib dabei auch die Zertifikatsoptionen an. Ohne --tls-mode und --dns-provider läuft die Domain sonst unverschlüsselt.
• Die Netzwerkadresse der Modell-Engine lässt sich nur über eine erneute Installation ändern, nicht über apply.

Wichtig: Deine Einstellungen werden in /etc/aictl/spec.yaml gespeichert, eine Kopie liegt in /var/lib/aictl/spec.yaml. Nimm Änderungen bevorzugt über die Befehle von aictl vor. Wie das Zusammenspiel funktioniert, steht unter So funktioniert aictl.

Lesezugriff ohne sudo#

Rufst du die Installation als normaler Benutzer mit sudo auf, nimmt aictl diesen Benutzer in eine Systemgruppe auf und macht die Lizenz und die Plattform-Schlüssel für diese Gruppe lesbar. Die Installation nennt die Gruppe in ihrer Ausgabe. Danach funktionieren aictl status, aictl license info und aictl license check auch ohne sudo, sobald du dich neu am Server angemeldet hast.

Achtung: Die Mitgliedschaft in dieser Gruppe entspricht auf dem Server praktisch Administratorrechten und läuft nie ab. Rückgängig machst du sie jederzeit mit sudo gpasswd -d <benutzer> <gruppe>. Wie du die Aufnahme schon bei der Installation verhinderst, beschreibt die Entwicklerdokumentation im Kapitel «Stack anpassen». Lehnst du sie einmal ab, gilt das auch für spätere Installationen.

Alle anderen Befehle brauchen weiterhin sudo.

Sonderfälle#

Lizenzschlüssel in Kleinbuchstaben. Über --license wird der Schlüssel nicht umgewandelt. lic-… scheitert an der Formatprüfung. Gib ihn in Grossbuchstaben an. Bei der Eingabe in der Frage geschieht die Umwandlung automatisch.

Falsche Systemzeit. Weicht die Uhr zu stark von der Zeit des Lizenzservers ab, lehnt die Installation die Lizenz ab und nennt die Abweichung. Schalte die Zeitsynchronisation ein (sudo timedatectl set-ntp true) und starte die Installation erneut.

Kein Terminal und kein Schlüssel. Ohne Terminal kann die Installation nicht nach dem Schlüssel fragen und bricht mit dem Hinweis ab, --license anzugeben.

Abbruch mit Esc oder Ctrl-C. Was bis dahin erledigt wurde, bleibt bestehen, zum Beispiel eine bereits aktivierte Lizenz oder ein schon gespeicherter DNS-Schlüssel. Starte die Installation einfach erneut.

Zu wenig Speicherplatz. Bevor die Installation etwas herunterlädt, prüft sie den freien Platz am Ablageort der Bestandteile, meist /var/lib/docker. Für eine erste Installation braucht es dort mindestens 20 GiB, fehlen nur einzelne Bestandteile 6 GiB, und für eine Reparatur mit allen Bestandteilen vor Ort 1 GiB. Reicht der Platz nicht, bricht sie ab und nennt Ort und Bedarf. Schaffe Platz oder vergrössere das Laufwerk und starte die Installation erneut.

Belegter Port. Belegt ein anderes Programm einen Port der Plattform, bricht die Installation ab, bevor sie etwas startet. Sie nennt den Port, das Programm samt Prozessnummer und schlägt den passenden systemctl disable --now …-Befehl vor. Beende das Programm oder deaktiviere es dauerhaft und starte die Installation erneut. Alternativ verlegst du den Port der Plattform in der Einstellungsdatei.

Einstellungsdatei fehlt. Fehlt /etc/aictl/spec.yaml, stellt jeder Befehl von aictl sie automatisch aus der Kopie in /var/lib/aictl wieder her. Fehlen beide, obwohl auf dem Server noch Daten der Plattform liegen, verweigert die Installation den Start. Sie würde sonst mit leeren Einstellungen neu beginnen: ohne Domain, ohne Erweiterungen und mit zurückgesetzter Administratoradresse. Hole die Datei aus einem Backup (configs/spec.yaml) zurück oder stelle das ganze Backup wieder her (siehe Backup und Wiederherstellung). Willst du wirklich neu beginnen, deinstalliere zuerst.

Eigenes Zertifikat fehlt. Steht die Zertifikatsart auf «eigenes Zertifikat», ist aber noch keines importiert, bricht die Installation ab. Importiere es mit sudo aictl proxy set-cert und starte die Installation erneut.

Dienste werden nicht rechtzeitig bereit. Meldet die Installation services did not become healthy within 10m0s, bricht sie an dieser Stelle ab. Hintergrunddienst und Lesezugriff ohne sudo werden trotzdem eingerichtet. Es fehlen noch die Verbindung zum Firmen-Login, die Erweiterungen und die DNS-Einträge. Behebe die Ursache (siehe sudo aictl status und Fehlerbehebung) und führe die Installation erneut aus, bei langsamen Servern mit mehr Zeit: sudo aictl install --health-wait 20m.

Eine Erweiterung schlägt fehl. Die Plattform läuft trotzdem, die Installation endet aber mit einem Fehler und nennt die betroffene Erweiterung. sudo aictl apply versucht es erneut, sobald die Ursache behoben ist.