Zum Inhalt springen
Oleaflyv0.4.12

Server betreiben

Jede Einstellung von Oleafly Server, das Speichern von Dateien auf der Festplatte oder in einem S3-Bucket, kompilierte PDFs, der Betrieb hinter einem Proxy, Limits für Klassen in einem Netzwerk und für jedes Konto, Protokolle, Backups, Wiederherstellungen und Updates.

Diese Seite beschreibt den laufenden Betrieb von Oleafly Server. Zur Installation beginnen Sie mit Einen Kollaborationsserver betreiben.

Der Server liest seine Einstellungen aus Umgebungsvariablen. Eine Variable, die gesetzt, aber leer ist, gilt als nicht gesetzt. Fehlt eine Einstellung oder ist sie fehlerhaft, startet der Server nicht, und sein Protokoll sagt, welche.

VariableFunktionStandard
OLEAFLY_PUBLIC_URLDie HTTPS-Adresse, die Personen in Oleafly eingeben. Sie kann einen Pfad enthalten, etwa https://www.cs.example.edu/oleafly. Erforderlich. Die Compose- und Coolify-Dateien setzen sie für Sie.Keine
OLEAFLY_BINDDie Adresse und der Port, an denen der Server lauscht.0.0.0.0:8080
OLEAFLY_DATA_DIRDer Ordner für die Datenbank und die gespeicherten Dateien./data
OLEAFLY_SERVER_NAMEDer Name, den Personen in Oleafly sehen, etwa Smith Lab.Oleafly Server
OLEAFLY_SERVER_ICON_URLDie HTTPS-Adresse eines quadratischen Bildes, das neben dem Namen angezeigt wird.Keine
OLEAFLY_SETUP_CODEIhr eigener einmaliger Einrichtungscode: mindestens 12 Buchstaben oder Ziffern, bei Bedarf mit Bindestrichen oder Leerzeichen. Ohne ihn erzeugt der Server einen.Generiert
OLEAFLY_GITHUB_CLIENT_ID, OLEAFLY_GITHUB_CLIENT_SECRETAktiviert die Anmeldung mit GitHub.Aus
OLEAFLY_GITHUB_URLDie Adresse eines GitHub Enterprise Server.https://github.com
OLEAFLY_GITHUB_API_URLDie Adresse der GitHub-API, falls Ihre ungewöhnlich ist.https://api.github.com, oder /api/v3 unter OLEAFLY_GITHUB_URL
OLEAFLY_GITHUB_LABELDer Text auf der GitHub-Anmeldeschaltfläche.GitHub
OLEAFLY_OIDC_<NAME>_ISSUER, OLEAFLY_OIDC_<NAME>_CLIENT_ID, OLEAFLY_OIDC_<NAME>_CLIENT_SECRETAktiviert einen OpenID-Connect-Anbieter namens <NAME>.Aus
OLEAFLY_OIDC_<NAME>_LABELDer Text auf seiner Anmeldeschaltfläche, etwa University login.<NAME>
OLEAFLY_OIDC_<NAME>_TRUST_EMAILBehandelt jede E-Mail-Adresse dieses Anbieters als bestätigt. Lesen Sie zuerst Bestätigte E-Mail-Adressen.false
OLEAFLY_SMTP_URL, OLEAFLY_MAIL_FROME-Mail. Lesen Sie E-Mail.Aus
OLEAFLY_OPEN_SIGNUPGibt jedem, der sich über einen Ihrer Anbieter anmeldet, ein Konto als Mitglied. Lesen Sie Offene Registrierung.false
OLEAFLY_WEBSchaltet den Browserzugriff ein. Lesen Sie Browserzugriff.false
OLEAFLY_BLOB_STOREWo Dateien wie Abbildungen und PDFs gespeichert werden. fs hält sie in OLEAFLY_DATA_DIR. Eine Adresse wie s3://lab-bucket oder s3://lab-bucket/oleafly hält sie in einem Bucket.fs
OLEAFLY_S3_ENDPOINTDie Adresse eines S3-kompatiblen Speichers außer Amazon S3, etwa MinIO oder Cloudflare R2. Lassen Sie sie für Amazon S3 leer.Amazon S3
OLEAFLY_S3_REGIONDie Region des Buckets.us-east-1
OLEAFLY_S3_ACCESS_KEY_ID, OLEAFLY_S3_SECRET_ACCESS_KEYDer Schlüssel, den der Server für den Bucket verwendet. Mit einer s3://-Adresse erforderlich.Keiner
OLEAFLY_MAX_PROJECT_MBDas größte Projekt, das der Server annimmt, in Megabyte.200
OLEAFLY_MAX_FILE_MBDie größte einzelne Datei, in Megabyte.50
OLEAFLY_MAX_MEMBERS_PER_PROJECTDie meisten Personen in einem Projekt.20
OLEAFLY_ACCOUNT_STORAGE_MBWie viel die Projekte, die einem Konto gehören, höchstens speichern dürfen, in Megabyte. Lesen Sie Limits pro Konto.Kein Limit oder 100 bei offener Registrierung
OLEAFLY_MAX_PROJECTS_PER_ACCOUNTWie viele geteilte Projekte einem Konto höchstens gehören dürfen.Kein Limit oder 50 bei offener Registrierung
OLEAFLY_UPLOADS_PER_HOURWie viele Datei- und Snapshot-Uploads ein Konto in einer Stunde machen darf.Kein Limit oder 300 bei offener Registrierung
OLEAFLY_SIGN_IN_BURSTWie viele Anmeldeanfragen eine Netzwerkadresse in einem Burst stellen kann. Eine Anmeldung braucht etwa sechs, der Standard deckt also 50 Personen an einer Adresse ab, die sich gleichzeitig anmelden.300
OLEAFLY_SIGN_IN_PER_MINUTEWie viele Anmeldeanfragen eine Netzwerkadresse nach dem Burst pro Minute zurückerhält.120
OLEAFLY_EMAIL_LINKS_PER_IPWie viele Anmelde-E-Mails der Server in 15 Minuten an Personen an einer Netzwerkadresse sendet.100
OLEAFLY_EMAIL_LINKS_PER_ADDRESSWie viele Anmelde-E-Mails eine E-Mail-Adresse in 15 Minuten erhalten kann. Es kann nicht mehr sein als OLEAFLY_EMAIL_LINKS_PER_IP.3
OLEAFLY_DEVICE_CODES_PER_IPWie viele Anmeldecodes Personen an einer Netzwerkadresse in 10 Minuten anfordern können.100
OLEAFLY_SNAPSHOT_MEMORY_MBWie viel Speicher in Megabyte der Server für den Aufbau von Projekt-Snapshots verwenden darf.Die Hälfte des Speicherlimits des Containers, oder 1024 ohne Limit
OLEAFLY_BEHIND_PROXYNimmt die Adresse jeder Person aus dem X-Forwarded-For-Header, den Ihr Proxy hinzufügt. Die Compose-, Coolify- und Render-Dateien schalten es ein.false
OLEAFLY_PROXY_HOPSWie viele Proxys jede Anfrage durchläuft, bevor sie den Server erreicht. Benötigt OLEAFLY_BEHIND_PROXY=true.1
OLEAFLY_LOG_LEVELWie viel der Server protokolliert: error, warn, info, debug oder trace. Bibliotheken, die der Server verwendet, protokollieren nur Warnungen, außer Sie wählen debug oder trace.info
OLEAFLY_SECURITY_LOG_DAYSWie viele Tage Einträge im Sicherheitsprotokoll, Einträge in Projektzugriffsprotokollen sowie beantwortete oder abgelaufene Gasteinladungen aufbewahrt werden.365
OLEAFLY_ARCHIVE_DAYSWie viele Tage ein Projekt aufbewahrt wird, nachdem sein Eigentümer die Freigabe beendet.30
OLEAFLY_POLL_HOLD_SECONDSWie lange der Server eine Long-Polling-Anfrage offen hält, wenn keine Bearbeitungen warten, von 1 bis 40 Sekunden. Halten Sie den Wert einige Sekunden unter dem Idle-Timeout jedes Proxys vor dem Server.25

Setzen Sie in der Compose-.env-Datei einen Wert in einfache Anführungszeichen, wenn er $ oder # enthält. Einstellungen mit Geheimnissen können auch aus Dateien gelesen werden. Lesen Sie Geheimnisse aus .env heraushalten.

Standardmäßig hält der Server alles in OLEAFLY_DATA_DIR: die Datenbank, die Dateien, die Personen teilen, und Projekt-Snapshots. Snapshots sind gespeicherte Kopien jedes Projekts, mit denen Personen schnell beitreten und auf den Stand kommen können.

Der Server kann Dateien und Snapshots stattdessen in Amazon S3 halten, oder in einem anderen Speicher mit S3-kompatibler API, etwa MinIO oder Cloudflare R2. Die Datenbank bleibt in jedem Fall in OLEAFLY_DATA_DIR, der Server braucht also weiterhin seinen Datenordner.

  1. Erstellen Sie einen Bucket und blockieren Sie den öffentlichen Zugriff darauf.

  2. Erstellen Sie einen Schlüssel, der Objekte in diesem Bucket lesen, schreiben und löschen kann, und sonst nichts. Auf Amazon S3 heißt das s3:GetObject, s3:PutObject und s3:DeleteObject auf arn:aws:s3:::lab-bucket/*, oder auf arn:aws:s3:::lab-bucket/oleafly/*, wenn Sie einen Ordner verwenden.

  3. Setzen Sie die Variablen, zum Beispiel in .env:

    Terminalfenster
    OLEAFLY_BLOB_STORE=s3://lab-bucket/oleafly
    OLEAFLY_S3_REGION=eu-west-1
    OLEAFLY_S3_ACCESS_KEY_ID=your-access-key-id
    OLEAFLY_S3_SECRET_ACCESS_KEY=your-secret-access-key

Für einen Speicher außer Amazon S3 setzen Sie außerdem OLEAFLY_S3_ENDPOINT auf seine Adresse, etwa https://minio.example.org:9000 oder https://<account-id>.r2.cloudflarestorage.com, und OLEAFLY_S3_REGION auf die Region, die er erwartet (auto für R2). Plain http:// funktioniert auch, verwenden Sie es aber nur, wenn der Speicher im selben privaten Netz wie der Server liegt.

Der Teil nach dem Bucket-Namen ist ein optionaler Ordner. Jede Datei ist nach ihrem SHA-256-Hash benannt und liegt unter den ersten beiden Zeichen dieses Hash; eine Datei, deren Hash mit 3f9a beginnt, wird also als oleafly/3f/3f9a... gespeichert. Snapshots haben einen eigenen snapshots-Ordner mit einem Ordner pro Projekt. Wenn der Server eine Datei oder einen Snapshot zurückliest, prüft er die Bytes gegen den Hash und lehnt eine ab, die nicht passt. Ohne Bucket liegt dasselbe Layout im Ordner blobs in OLEAFLY_DATA_DIR.

Lehnt der Bucket eine Anfrage ab, schlägt dieses Hoch- oder Herunterladen fehl, und das Serverprotokoll zeigt, was der Bucket geantwortet hat, etwa 403 Forbidden (AccessDenied). Ein Serverfehler, ein Timeout oder eine abgebrochene Verbindung ist etwas anderes: Der Server versucht es bis zu dreimal, mit einer kurzen zufälligen Pause dazwischen. Kann er ein Objekt nicht löschen, vermerkt er das und versucht es bei jedem Wartungsdurchlauf erneut, alle 6 Stunden, damit ein Ausfall keine Objekte zurücklässt.

Wird ein Projekt freigegeben, lädt die App des Eigentümers den ersten Snapshot hoch und signiert ihn mit dem Schlüssel dieses Geräts. Von da an baut der Server jeden Snapshot selbst, aus dem vorherigen Snapshot und den Änderungen, die Personen seither geschickt haben. Ein neuer Snapshot wird gebaut, sobald ein Projekt 1.000 Änderungen über den letzten hinaus hat. Der Server behält immer mindestens die letzten 2.000 Änderungen, sodass ein Gerät, das kurz weg war, daraus aufholt und nicht das ganze Projekt erneut lädt.

Der Aufbau eines Snapshots braucht etwa das Zehnfache der Größe des vorherigen Snapshots plus der Änderungen seither. Der Server beginnt nur einen Aufbau, der in OLEAFLY_SNAPSHOT_MEMORY_MB passt, und gleichzeitig laufende Aufbauten teilen sich diesen Betrag. Passt ein Aufbau nicht, überspringt der Server ihn, protokolliert, wie viel Speicher er braucht, und behält alle Änderungen des Projekts. Geräte holen diese Änderungen dann in Schritten von einigen Megabyte nach. Erhöhen Sie die Einstellung, und der nächste Snapshot wird gebaut. Einen Snapshot, der größer als OLEAFLY_MAX_PROJECT_MB ist, speichert der Server nicht.

Kompiliert ein Inhaber oder Bearbeiter ein geteiltes Projekt erfolgreich, sendet seine App das PDF an den Server, mit seiner SyncTeX-Datei, wenn es eine gibt. Sie sendet höchstens eins pro Minute und Projekt. Der Server behält ein PDF und eine SyncTeX-Datei pro Projekt, mit dem Namen der Hauptdatei und der Angabe, wer es wann kompiliert hat. Der Browserzugriff zeigt dieses PDF den Personen im Projekt.

Jeder Upload ersetzt den vorherigen, und die alte Datei wird gelöscht, sobald nichts sie mehr verwendet. Kompilierte Dateien werden bei den anderen Dateien gespeichert, auf der Festplatte oder im Bucket, und mit ihrem Projekt gelöscht. Eine kompilierte Datei darf so groß sein wie OLEAFLY_MAX_FILE_MB. Sie zählt zum Kontospeicher des Inhabers, aber nicht zu den Uploads pro Stunde.

Jedes Mitglied eines Projekts kann seine kompilierten Dateien lesen. Nur Inhaber und Bearbeiter können sie ersetzen.

Der Server spricht normales HTTP, etwas davor übernimmt also HTTPS: Caddy im Compose-Setup, der Proxy von Coolify oder ein Webserver, den Sie bereits betreiben, etwa der Ihrer Universität. Was auch immer davor liegt, muss Folgendes erfüllen:

  • Anfragen so groß wie OLEAFLY_MAX_PROJECT_MB akzeptieren
  • die Adresse des Clients zu X-Forwarded-For hinzufügen

Außerdem sollte es WebSocket-Upgrades an /ws durchreichen und diese Verbindungen mindestens eine Stunde offen halten. Die Live-Bearbeitung nutzt sie, wann immer es geht. Mit eingeschaltetem Browserzugriff muss es sie auch an /web/ws durchreichen, weil die Browser-App keinen langsameren Ausweichweg hat.

Betreiben Sie den Server dort, wo nur der Proxy ihn erreichen kann. Auf derselben Maschine setzen Sie OLEAFLY_BIND=127.0.0.1:8080. Setzen Sie dann OLEAFLY_BEHIND_PROXY=true.

Manche Netzwerke blockieren WebSocket-Verbindungen, oft ein Uni- oder Firmennetzwerk mit filterndem Proxy. Live-Bearbeitung funktioniert dort trotzdem, nur langsamer. Wenn zwei WebSocket-Versuche hintereinander fehlschlagen, der Server aber weiterhin über HTTPS antwortet, wechselt Oleafly zu HTTP-Long-Polling. Es sendet Bearbeitungen an /api/v1/projects/<project>/frames und wartet auf /api/v1/projects/<project>/poll auf die Bearbeitungen der anderen Personen, wobei es jede Anfrage bis zu OLEAFLY_POLL_HOLD_SECONDS offen hält. Jede Bearbeitung kommt trotzdem an. Oleafly versucht jede Minute wieder einen WebSocket und kehrt dazu zurück, sobald einer verbindet.

Verbindung testen in Oleafly und Verbindungstests in der Admin-Konsole sagen, wann das passiert: „Live-Bearbeitungen nehmen einen langsameren Weg, weil dieses Netzwerk den üblichen blockiert. Sie kommen trotzdem durch.“

Betreiben Sie den Proxy vor dem Server, reichen Sie WebSocket-Upgrades trotzdem durch. Long-Polling funktioniert, aber jede Gruppe von Bearbeitungen kostet eine zusätzliche Anfrage und etwas mehr Verzögerung.

Manche Proxys schließen eine Anfrage, die weniger als 30 Sekunden still bleibt, nginx mit kurzem proxy_read_timeout zum Beispiel. Sie beantworten Long-Polling-Anfragen mit einem 502- oder 504-Fehler, und Bearbeitungen kommen spät an. Setzen Sie OLEAFLY_POLL_HOLD_SECONDS einige Sekunden unter dieses Timeout, etwa 8 für ein Timeout von 10 Sekunden.

Der Server notiert eine Client-Adresse an zwei Stellen: im Sicherheitsprotokoll und in den Limits dafür, wie oft eine Adresse eine Anmeldung beginnen oder eine Live-Verbindung öffnen kann.

Ohne die Einstellung verwendet der Server die Adresse dessen, was sich mit ihm verbunden hat. Hinter einem Proxy ist das immer der Proxy, alle teilen sich also ein Limit, und das Sicherheitsprotokoll zeigt nur die Adresse des Proxys.

Mit OLEAFLY_BEHIND_PROXY=true liest der Server den X-Forwarded-For-Header und verwendet die letzte Adresse darin, also die, die Ihr Proxy hinzugefügt hat. Fehlt der Header oder enthält er keine gültige Adresse, fällt der Server auf die Verbindungsadresse zurück. Sonst ändert sich nichts. Der Server ignoriert X-Forwarded-Proto, X-Forwarded-Host und Forwarded und baut jede Adresse, die er ausgibt, aus OLEAFLY_PUBLIC_URL.

Schalten Sie es nur ein, wenn jede Anfrage durch Ihren Proxy kommt. Können Personen den Server auch direkt erreichen, kann jemand einen erfundenen X-Forwarded-For senden, eine beliebige Adresse ins Sicherheitsprotokoll schreiben und das Anmeldelimit umgehen.

Bei zwei Proxys hintereinander, etwa Cloudflare vor dem Proxy von Coolify, setzen Sie OLEAFLY_PROXY_HOPS=2. Der Server nimmt dann die zweitletzte Adresse. Zählen Sie nur die Proxys, die jede Anfrage durchläuft. Ein Cloudflare-Tunnel, der direkt zum Server führt, zählt als einer.

Um die Zahl zu prüfen, melden Sie sich von Ihrem eigenen Computer aus an und öffnen Sie Sicherheitsprotokoll in der Admin-Konsole. Der neueste Eintrag sollte Ihre öffentliche Adresse zeigen, also die, die eine Seite wie ifconfig.me meldet. Zeigt er stattdessen eine private oder Cloudflare-Adresse, erhöhen Sie OLEAFLY_PROXY_HOPS um eins.

Caddy reicht WebSocket-Verbindungen und X-Forwarded-For ohne zusätzliche Einstellungen durch und besorgt das Zertifikat selbst. HTTPS vorschalten enthält die ganze Caddyfile.

Holen Sie zuerst ein Zertifikat für die Domäne, etwa mit certbot. Speichern Sie dann dies als /etc/nginx/conf.d/oleafly.conf und führen Sie sudo nginx -t && sudo systemctl reload nginx aus:

map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}
server {
listen 443 ssl;
server_name collab.example.org;
ssl_certificate /etc/letsencrypt/live/collab.example.org/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/collab.example.org/privkey.pem;
location / {
proxy_pass http://127.0.0.1:8080;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
proxy_set_header X-Forwarded-For $remote_addr;
proxy_read_timeout 1h;
proxy_send_timeout 1h;
client_max_body_size 200m;
}
}

client_max_body_size passt zum Standard OLEAFLY_MAX_PROJECT_MB von 200. Erhöhen Sie das eine, erhöhen Sie auch das andere.

Sie brauchen Apache 2.4.47 oder neuer, das Debian 12 sowie Ubuntu 22.04 und später haben. Aktivieren Sie die Module:

Terminalfenster
sudo a2enmod proxy proxy_http ssl

Speichern Sie dies als /etc/apache2/sites-available/oleafly.conf und führen Sie dann sudo a2ensite oleafly && sudo systemctl reload apache2 aus:

<VirtualHost *:443>
ServerName collab.example.org
SSLEngine on
SSLCertificateFile /etc/letsencrypt/live/collab.example.org/fullchain.pem
SSLCertificateKeyFile /etc/letsencrypt/live/collab.example.org/privkey.pem
ProxyPreserveHost On
ProxyPass / http://127.0.0.1:8080/ upgrade=websocket timeout=3600
ProxyPassReverse / http://127.0.0.1:8080/
</VirtualHost>

upgrade=websocket reicht WebSocket-Verbindungen durch, und timeout=3600 hält sie eine Stunde offen. Apache fügt die Adresse des Clients von selbst zu X-Forwarded-For hinzu.

Liegt der Server unter einem Pfad, nehmen Sie den Pfad in OLEAFLY_PUBLIC_URL auf, zum Beispiel https://www.cs.example.edu/oleafly, und in die Callback-Adressen, die Sie bei Anmeldeanbietern registrieren. Der Server antwortet mit und ohne diesen Pfad, Ihr Proxy kann ihn also weiterreichen oder entfernen. Verwenden Sie bei nginx location /oleafly/ { mit denselben Zeilen darin und lassen Sie proxy_pass http://127.0.0.1:8080; ohne Pfad, damit nginx den Pfad weiterreicht.

Eine ganze Klasse meldet sich oft von einer Netzwerkadresse aus an, etwa vom NAT einer Universität. Die Standardwerte sind darauf eingestellt:

  • Anmeldungen: Eine Adresse bekommt einen Burst von 300 Anmeldeanfragen, danach zwei pro Sekunde. Eine Anmeldung braucht etwa sechs, 50 Personen können sich also gleichzeitig anmelden. Ändern Sie das mit OLEAFLY_SIGN_IN_BURST und OLEAFLY_SIGN_IN_PER_MINUTE.
  • E-Mail-Links: 100 an eine Adresse in 15 Minuten und 3 an eine E-Mail-Adresse. Ändern Sie das mit OLEAFLY_EMAIL_LINKS_PER_IP und OLEAFLY_EMAIL_LINKS_PER_ADDRESS.
  • Anmeldecodes: 100 Codes und 10 falsche Codes von einer Adresse in 10 Minuten. Ändern Sie das mit OLEAFLY_DEVICE_CODES_PER_IP.
  • Live-Verbindungen haben ein eigenes, größeres Limit, sodass sich eine ganze Klasse hinter einer Adresse nach einem Neustart sofort wieder verbinden kann. Nur Verbindungen, die ihre Sitzung nicht nachweisen können, verbrauchen es: ein Burst von 300, danach zehn pro Sekunde. Eine Verbindung, die ihre Sitzung nachweist, wird stattdessen auf ihr eigenes Gerät angerechnet, das sich in einem Burst 60-mal wiederverbinden kann, danach einmal pro Sekunde.

Alle IPv6-Adressen in einem /64-Netzwerk gelten als eine Adresse. Diese Limits wirken nur pro Person, wenn der Server die echte Adresse jeder Person sieht. Richten Sie Ihren Proxy also richtig ein.

Der Server pingt jede Live-Verbindung alle 30 Sekunden an. Er schließt eine Verbindung, die diese Pings 90 Sekunden lang unbeantwortet lässt, und eine, die aufhört zu lesen, was der Server sendet.

Projekt-Limits gelten für alle: OLEAFLY_MAX_PROJECT_MB für ein ganzes Projekt (standardmäßig 200 MB), OLEAFLY_MAX_FILE_MB für eine Datei (50 MB) und OLEAFLY_MAX_MEMBERS_PER_PROJECT für Personen in einem Projekt (20). Der Überblick der Admin-Konsole zeigt die aktuellen Limits.

Für jedes Konto gelten drei Limits. Sie sind aus, bis Sie sie setzen, außer die offene Registrierung ist eingeschaltet. Dann gelten sie mit diesen Standardwerten:

LimitEinstellungBei offener Registrierung
Speicher für die Projekte, die einem Konto gehörenOLEAFLY_ACCOUNT_STORAGE_MB100 MB
Geteilte Projekte, die einem Konto gehörenOLEAFLY_MAX_PROJECTS_PER_ACCOUNT50
Uploads eines Kontos in einer StundeOLEAFLY_UPLOADS_PER_HOUR300

Ein Wert, den Sie setzen, hat immer Vorrang vor dem Standardwert. Jeder muss eine ganze Zahl von mindestens 1 sein.

  • Speicher zählt die Dateien und den Änderungsverlauf jedes Projekts zusammen, das dem Konto gehört, archivierte eingeschlossen, dazu ihre kompilierten PDFs. Snapshots zählen nicht. Eine Datei, die irgendwer zu einem Projekt hinzufügt, wird dem Inhaber des Projekts angerechnet. Ist das Konto des Inhabers voll, lehnt der Server neue Dateien und kompilierte PDFs für seine Projekte ab, und er kann kein weiteres Projekt teilen. Die Datei bleibt auf dem Computer der Person, die sie hinzugefügt hat. Getippter Text wird weiterhin synchronisiert.
  • Geteilte Projekte zählt die Projekte, die das Konto teilt, auch solche, die noch hochgeladen werden. Archivierte Projekte zählen nicht, wer also eines nicht mehr teilt, schafft Platz.
  • Uploads zählt jeden Datei- und Snapshot-Upload in einem Zeitfenster von einer Stunde. Kompilierte PDFs zählen nicht. Oleafly sendet eine abgelehnte Datei später von selbst erneut.

Der Überblick der Admin-Konsole zeigt diese Limits nicht. Bei eingeschalteter offener Registrierung nennt das Protokoll des Servers sie bei jedem Start.

  • Das Serverprotokoll ist das, was docker compose logs oleafly-server, Coolifys Logs oder journalctl -u oleafly-server zeigen. OLEAFLY_LOG_LEVEL legt fest, wie viel es sagt.
  • Das Sicherheitsprotokoll zeichnet Anmeldungen und abgelehnte Anmeldungen, Geräte, Personen, Rollen, Einstellungen, Projekte und Gäste auf, jeweils mit Zeit und IP-Adresse. Admins und Maintainer lesen es unter Sicherheitsprotokoll in der Admin-Konsole. Einträge, die älter als OLEAFLY_SECURITY_LOG_DAYS Tage sind, werden gelöscht.
  • Projektzugriffsprotokolle zeichnen auf, wer ein Projekt geöffnet, ihm beigetreten oder eine Kopie heruntergeladen hat, mit Gerätenamen und Zeit. Der Eigentümer eines Projekts schaltet eines ein, wenn Zugriffsprotokolle für Projekte erlauben an ist, und nur dieser Eigentümer kann es lesen. Dieselbe Aufbewahrungszeit gilt.

Was eine vollständige Sicherung braucht, hängt davon ab, wo Dateien gespeichert sind:

  • Dateien auf der Festplatte (OLEAFLY_BLOB_STORE=fs, die Standardeinstellung): Datenbank, Dateien und Snapshots liegen alle im Datenordner. Sichern Sie den ganzen Ordner.
  • Dateien in einem Bucket: Der Datenordner hält die Datenbank, der Bucket hält Dateien und Snapshots. Eine Kopie der Datenbank plus der Bucket ist eine vollständige Sicherung. Aktivieren Sie die Versionierung für den Bucket, damit ein versehentlich gelöschtes Objekt zurückgeholt werden kann.
Wo der Server Daten speichert und was zu sichern istMit Dateien auf der Festplatte, der Standard, enthält der Datenordner die Datenbank und den Ordner blobs mit Dateien und Snapshots, Sie sichern also den ganzen Ordner. Mit Dateien in einem Bucket enthält der Datenordner die Datenbank und ein S3-Bucket die Dateien und Snapshots, Sie sichern also Datenbank und Bucket.Dateien auf der Festplatte (Standard)Dateien in einem Bucketoleafly-serverDatenordnerDatenbank: Konten, Einstellungen, Protokolleblobs: Dateien und SnapshotsDen ganzen Ordner sichernoleafly-serverDatenordnerDatenbankS3-BucketDateien undSnapshotsDatenbank und Bucket sichernWo der Server Daten speichert und was zu sichern istMit Dateien auf der Festplatte, der Standard, enthält der Datenordner die Datenbank und den Ordner blobs mit Dateien und Snapshots, Sie sichern also den ganzen Ordner. Mit Dateien in einem Bucket enthält der Datenordner die Datenbank und ein S3-Bucket die Dateien und Snapshots, Sie sichern also Datenbank und Bucket.Dateien auf der Festplatte (Standard)Dateien in einem Bucketoleafly-serverDatenordnerDatenbank und blobs(Dateien, Snapshots)Den ganzen Ordner sichernoleafly-serverDatenordnerDatenbankS3-BucketDateien undSnapshotsDatenbank undBucket sichern
Was ein vollständiges Backup braucht, hängt davon ab, wo die Dateien liegen.

Sichern Sie regelmäßig und halten Sie die Kopien privat, denn sie enthalten jedes Projekt. Ihre Einstellungen, etwa .env, liegen nicht im Datenordner, bewahren Sie also auch von ihnen eine Kopie auf.

Mit Docker stoppt der Server für ein paar Sekunden, während Sie das Volume kopieren. Oleafly verbindet sich von selbst wieder. Führen Sie diese Befehle im Ordner des Servers aus, in /opt/oleafly-server, wenn Sie das Installationsprogramm verwendet haben.

Terminalfenster
cd /opt/oleafly-server
sudo docker compose stop oleafly-server
sudo docker run --rm -v oleafly-server_oleafly-data:/data:ro -v "$PWD":/backup debian:13.7-slim tar -C /data -czf /backup/oleafly-data-$(date +%F).tar.gz .
sudo docker compose start oleafly-server

Mit systemd:

Terminalfenster
sudo systemctl stop oleafly-server
sudo tar -C /var/lib/private/oleafly-server -czf /root/oleafly-data-$(date +%F).tar.gz .
sudo systemctl start oleafly-server

Kopieren Sie das Archiv auf eine andere Maschine.

Auf Coolify beginnt der Name des Volumes mit der ID der Ressource. Finden Sie ihn mit docker volume ls --filter name=oleafly-data, verwenden Sie ihn anstelle von oleafly-server_oleafly-data und stoppen und starten Sie den Server über das Dashboard von Coolify statt mit docker compose.

Ein Backup, das Sie nie wiederhergestellt haben, ist nur eine Hoffnung. Diese Übung startet eine zweite Kopie des Servers aus einem Backup, lässt die laufende unberührt und prüft, dass beide derselbe Server sind. Verwenden Sie das Datum Ihres eigenen Archivs anstelle von 2026-10-11.

Terminalfenster
cd /opt/oleafly-server
sudo docker volume create oleafly-restore-drill
sudo docker run --rm -v oleafly-restore-drill:/data -v "$PWD":/backup:ro debian:13.7-slim tar -C /data -xzf /backup/oleafly-data-2026-10-11.tar.gz
sudo docker run -d --name oleafly-restore-drill -v oleafly-restore-drill:/data -e OLEAFLY_PUBLIC_URL=https://restore-drill.invalid -e OLEAFLY_GITHUB_CLIENT_ID=restore-drill -e OLEAFLY_GITHUB_CLIENT_SECRET=restore-drill "$(sudo docker compose images -q oleafly-server)"
sudo docker run --rm --network container:oleafly-restore-drill curlimages/curl:8.22.0 -fsS --retry 10 --retry-connrefused --retry-delay 1 http://127.0.0.1:8080/.well-known/oleafly-server
curl -fsS https://collab.example.org/.well-known/oleafly-server

Die server_id in den beiden Antworten muss übereinstimmen. Die Übungskopie hat eine Platzhalter-GitHub-Anmeldung, die niemanden anmelden kann, und keinen offenen Port, niemand kann sie also verwenden. Entfernen Sie sie, wenn Sie fertig sind:

Terminalfenster
sudo docker rm -f oleafly-restore-drill
sudo docker volume rm oleafly-restore-drill

Um mit Docker Compose wirklich wiederherzustellen, stoppen Sie den Server, ersetzen Sie den Inhalt des Volumes durch das Archiv und starten Sie ihn wieder:

Terminalfenster
cd /opt/oleafly-server
sudo docker compose stop oleafly-server
sudo docker run --rm -v oleafly-server_oleafly-data:/data -v "$PWD":/backup:ro debian:13.7-slim sh -c 'find /data -mindepth 1 -delete && tar -C /data -xzf /backup/oleafly-data-2026-10-11.tar.gz'
sudo docker compose start oleafly-server

Mit systemd:

Terminalfenster
sudo systemctl stop oleafly-server
sudo find /var/lib/private/oleafly-server -mindepth 1 -delete
sudo tar -C /var/lib/private/oleafly-server -xzf /root/oleafly-data-2026-10-11.tar.gz
sudo systemctl start oleafly-server

Auf einem wiederhergestellten Server fehlen die Änderungen, die Personen nach dem Backup gemacht haben. Jede App merkt es, wenn sie sich neu verbindet, ob sie offen blieb oder später geöffnet wurde, und sendet ihre eigenen fehlenden Änderungen erneut. Dafür muss niemand etwas tun. Eine Änderung, die auf einer fehlenden Änderung einer anderen Person aufbaut, wartet, bis diese Person das Projekt öffnet, weil nur ihre App ihre Änderungen senden kann. Bitten Sie alle, die um die Zeit des Ausfalls bearbeitet haben, das Projekt einmal zu öffnen.

Ein Archiv enthält nur das, was bei seiner Erstellung da war. Litestream (öffnet in einem neuen Tab) kopiert jede Änderung an der Datenbank des Servers etwa eine Sekunde später in einen S3-kompatiblen Bucket. Die Compose-Datei enthält ihn als optionalen Dienst.

Litestream kopiert nur die Datenbank. Liegen die Dateien in einem Bucket, hält der Bucket bereits Dateien und Snapshots, die Litestream-Kopie und der Bucket zusammen können also eine verlorene Festplatte zurückbringen. Liegen die Dateien auf der Festplatte, erstellen Sie weiterhin Archive des Volumes, denn Litestream kopiert den Ordner blobs nicht.

  1. Erstellen Sie einen Bucket oder einen Ordner in einem, den nur der Litestream dieses Servers verwendet. Teilen Sie ihn nicht mit OLEAFLY_BLOB_STORE. Geben Sie Litestream einen Schlüssel, der den Bucket auflisten und Objekte darin lesen, schreiben und löschen kann.

  2. Fügen Sie die Angaben zu .env hinzu:

    Terminalfenster
    LITESTREAM_REPLICA_URL=s3://lab-backups/oleafly-server
    LITESTREAM_REGION=eu-west-1
    LITESTREAM_ACCESS_KEY_ID=your-access-key-id
    LITESTREAM_SECRET_ACCESS_KEY=your-secret-access-key
    COMPOSE_PROFILES=litestream

    Für einen Speicher außer Amazon S3 setzen Sie außerdem LITESTREAM_ENDPOINT auf seine Adresse und LITESTREAM_REGION auf die Region, die er erwartet (auto für R2). COMPOSE_PROFILES sorgt dafür, dass jeder docker compose-Befehl Litestream einschließt.

  3. Starten Sie ihn:

    Terminalfenster
    sudo docker compose up -d
  4. Prüfen Sie, dass er die Datenbank kopiert hat. Dies gibt eine Zeile mit snapshot complete aus:

    Terminalfenster
    sudo docker compose logs litestream | grep 'snapshot complete'

Litestream erstellt einmal am Tag eine vollständige Kopie und behält eine Woche an Kopien sowie die Änderungen dazwischen. Der Zeitplan steht in litestream.yml.

Diese Übung stellt die Datenbank aus dem Bucket in einem temporären Volume wieder her, startet darauf eine zweite Kopie des Servers und prüft, dass beide derselbe Server sind. Der laufende Server wird nicht angerührt.

Terminalfenster
cd /opt/oleafly-server
sudo docker run --rm -v oleafly-litestream-drill:/data "$(sudo docker compose images -q oleafly-server)" --version
sudo docker compose run --rm --no-deps -v oleafly-litestream-drill:/restore litestream restore -config /etc/litestream.yml -o /restore/oleafly-server.sqlite3 /data/oleafly-server.sqlite3
sudo docker run -d --name oleafly-litestream-drill -v oleafly-litestream-drill:/data -e OLEAFLY_PUBLIC_URL=https://restore-drill.invalid -e OLEAFLY_GITHUB_CLIENT_ID=restore-drill -e OLEAFLY_GITHUB_CLIENT_SECRET=restore-drill "$(sudo docker compose images -q oleafly-server)"
sudo docker run --rm --network container:oleafly-litestream-drill curlimages/curl:8.22.0 -fsS --retry 10 --retry-connrefused --retry-delay 1 http://127.0.0.1:8080/.well-known/oleafly-server
curl -fsS https://collab.example.org/.well-known/oleafly-server

Der erste Befehl erzeugt das temporäre Volume mit dem Eigentümer, den der Server braucht. Die server_id in den letzten beiden Antworten muss übereinstimmen. Entfernen Sie die Kopie, wenn Sie fertig sind:

Terminalfenster
sudo docker rm -f oleafly-litestream-drill
sudo docker volume rm oleafly-litestream-drill

Ist die Datenbankdatei beschädigt oder weg, der Rest des Datenordners aber in Ordnung, stoppen Sie den Server und Litestream, entfernen Sie die Reste der Datenbank, stellen Sie sie wieder her und starten Sie erneut:

Terminalfenster
cd /opt/oleafly-server
sudo docker compose stop oleafly-server litestream
sudo docker run --rm -v oleafly-server_oleafly-data:/data debian:13.7-slim rm -rf /data/oleafly-server.sqlite3 /data/oleafly-server.sqlite3-wal /data/oleafly-server.sqlite3-shm /data/.oleafly-server.sqlite3-litestream
sudo docker compose run --rm --no-deps litestream restore -config /etc/litestream.yml /data/oleafly-server.sqlite3
sudo docker compose up -d

Nach einer verlorenen Festplatte mit Dateien in einem Bucket führen Sie die Befehle oben auf dem neuen, leeren Volume aus und behalten dieselben Bucket-Einstellungen in .env. Jedes Projekt kommt mit seinen Dateien und Snapshots zurück.

Nach einer verlorenen Festplatte mit Dateien auf der Festplatte stellen Sie Ihr neuestes Archiv wieder her und lassen es dabei. Setzen Sie keine neuere Datenbank aus Litestream auf ein älteres Archiv. Die Datenbank würde auf Dateien und Snapshots verweisen, die das Archiv nicht hat, und diese Projekte würden sich nicht öffnen lassen.

Sichern Sie zuerst. Der Server aktualisiert seine Datenbank beim ersten Start einer neuen Version; zu einer älteren Version zurückzukehren bedeutet also, das Backup wiederherzustellen, das Sie vor dem Update gemacht haben.

  • Installation mit einem Befehl: Führen Sie curl -fsSL https://oleafly.com/server/install.sh | sudo sh -s -- update aus. Es behält .env, holt die Dateien und das Image der neuen Version und startet den Server neu.
  • Docker Compose von Hand: Laden Sie die Dateien der neuen Version wie in Docker Compose von Hand in den Ordner des Servers herunter und führen Sie dann sudo docker compose up -d aus.
  • Coolify: Wählen Sie Redeploy. Beim veröffentlichten Image zieht das die neueste Version unter dem Tag des Images.
  • Render: Öffnen Sie den Dienst und starten Sie ein manuelles Deployment, das das Image erneut zieht.
  • Railway: Stellen Sie den Dienst wieder über sein Menü bereit. Railway kann ein Image aus der Registry von GitHub auch von selbst aktualisieren.
  • systemd: Installieren Sie die neue Version wie in Den Server herunterladen, und führen Sie dann sudo systemctl restart oleafly-server aus.

Oleafly prüft die Version des Servers bei jeder Verbindung. Können App und Server nicht zusammenarbeiten, sagt Oleafly, welches von beiden ein Update braucht.

Bildvorschau

KI-Antworten konnten nicht geladen werden

Versuchen Sie es erneut oder durchsuchen Sie die Dokumentation.