S3-Migration

​

S3-Migration

Diese Anleitung gilt für v5.x und neuer. Wenn Sie diese Anleitung für eine ältere Version verwenden, nutzen Sie in Pfadnamen sharelatex statt overleaf und bei Umgebungsvariablen das Präfix SHARELATEX_ statt OVERLEAF_. Ab v6 überspringen Sie die veralteten user_files-Befehle.

Wir freuen uns, von Ihnen zu hören! Wenn Sie uns mitteilen möchten, wie viele Dateien Sie migriert haben, wie groß deren Gesamtvolumen war und wie lange die Migration gedauert hat, schreiben Sie eine E-Mail an [e-mail].

Diese Anleitung führt Sie durch die Migration von Speicherung auf der Festplatte zu einem S3-kompatiblen Objektspeicher. Sie verweist auf Abschnitte der einführenden Dokumentation zum S3-Setup.

​

Voraussetzungen

• Ein S3-kompatibler Objektspeicher, mit dem kommuniziert werden kann; Optionen finden Sie unter #s3-setup
• Freier Speicherplatz für die Migration der vorhandenen Daten, etwa in Höhe der aktuellen Belegung auf der Festplatte
• Ein Wartungsfenster für die eigentliche Migration
• Ein vollständiges Backup einschließlich der Konfiguration, um daraus wiederherstellen zu können

​

Den für die Migration benötigten Speicherplatz abschätzen

Mit du können wir die aktuelle Festplattenbelegung berechnen:

docker exec sharelatex \
  du --human-readable --max-depth=0 /var/lib/overleaf/data/user_files

docker exec sharelatex \
  du --human-readable --max-depth=0 /var/lib/overleaf/data/template_files

Falls auf dem aktuellen Server nicht genügend Speicherplatz verfügbar ist, versuchen Sie, eine weitere Festplatte an den Server anzuschließen.

Die History-Verzeichnisse haben bereits das richtige Layout. Sie können direkt aus dem per Bind-Mount eingebundenen Quellordner hochladen, wofür kein zusätzlicher Speicherplatz benötigt wird.

​

Migrationsschritte

​

Schritt 0: Die Instanz herunterfahren

Wir müssen sicherstellen, dass alle Nutzer- und Vorlagendateien migriert werden. Am besten fahren Sie die Instanz herunter, damit keine neu hochgeladenen Dateien verloren gehen.

Das Vorgehen beim Herunterfahren finden Sie in unserer Anleitung zur Erstellung eines konsistenten Backups.

​

Schritt 1: Das Verzeichnislayout umschreiben

Für den Upload nach S3 müssen wir das Verzeichnislayout der Projektdateien umschreiben. Das Verzeichnislayout für die lokale Speicherung im Filestore ist <project-id>_<file-id>, das Verzeichnislayout in S3 ist <project-id>/<file-id>.

Im Folgenden wird /srv/overleaf-s3-migration zur Speicherung der Dateien im neuen Verzeichnislayout verwendet. Ersetzen Sie /srv/overleaf-bind-mount durch das Host-Verzeichnis, das unter /var/lib/overleaf eingebunden ist. Führen Sie die Kopierbefehle auf dem Host mit Lese- und Schreibberechtigung für diese Verzeichnisse aus; der Container bleibt gestoppt.

Zum Umschreiben des Layouts können wir tar verwenden:

mkdir -p /srv/overleaf-s3-migration/user_files \
         /srv/overleaf-s3-migration/template_files
tar --create --directory /srv/overleaf-bind-mount/data/user_files . \
| tar --extract --directory /srv/overleaf-s3-migration/user_files \
  --transform=sx_x/x
tar --create --directory /srv/overleaf-bind-mount/data/template_files . \
| tar --extract --directory /srv/overleaf-s3-migration/template_files \
  --transform=sx_x/xg

​

Schritt 2: Die Dateien hochladen

Je nach Vorliebe können Sie den S3-Client minio mc oder die aws cli verwenden, um die Dateien in Ihren S3-kompatiblen Objektspeicher hochzuladen.

aws cli

• Ersetzen Sie hier overleaf-user-files, overleaf-template-files, overleaf-project-blobs und overleaf-chunks durch die Namen Ihrer S3-Buckets.
• Ersetzen Sie außerdem /srv/overleaf-bind-mount durch den lokalen Pfad des Bind-Mounts für /var/lib/overleaf. Standardmäßig ist das ~/overleaf_data bei einer Bereitstellung mit docker-compose.yml und <toolkit-checkout>/data/overleaf bei Verwendung des Toolkits.

aws s3 sync /srv/overleaf-s3-migration/user_files s3://overleaf-user-files
aws s3 sync /srv/overleaf-s3-migration/template_files s3://overleaf-template-files

aws s3 sync /srv/overleaf-bind-mount/data/history/overleaf-project-blobs s3://overleaf-project-blobs
aws s3 sync /srv/overleaf-bind-mount/data/history/overleaf-chunks s3://overleaf-chunks

minio mc

Wir verwenden hier den Server-Alias „s3”; möglicherweise haben Sie einen anderen Namen gewählt.

mc mirror /srv/overleaf-s3-migration/user_files s3/overleaf-user-files
mc mirror /srv/overleaf-s3-migration/template_files s3/overleaf-template-files

mc mirror /srv/overleaf-bind-mount/data/history/overleaf-project-blobs s3/overleaf-project-blobs
mc mirror /srv/overleaf-bind-mount/data/history/overleaf-chunks s3/overleaf-chunks

​

Schritt 3: Die Instanz mit S3 starten

Fügen Sie Ihrer Konfiguration alle S3-bezogenen Variablen hinzu, wie im Abschnitt Übersicht der Variablen der Einrichtungsanleitung für S3 beschrieben.

Behalten Sie den Bind-Mount für das Datenverzeichnis bei: Er kann auch Verschlüsselungsschlüssel für Zotero oder Mendeley enthalten, die nicht nach S3 migriert werden.

Behalten Sie den Bind-Mount einer Scratch-Festplatte für temporäre Dateien unbedingt bei.

Sie können die Instanz jetzt starten und die Migration überprüfen:

• Binärdateien lassen sich im Editor in der Vorschau anzeigen
• Ein PDF mit Bildern lässt sich kompilieren
• Neue Dateien lassen sich hochladen

​

Rollback

Sie können die Migration problemlos rückgängig machen, indem Sie die Schritte umkehren:

1. Fahren Sie die Instanz herunter
2. Spiegeln Sie die Dateien zurück, indem Sie Quelle und Ziel vertauschen
3. Schreiben Sie neue Dateien mit einer umgekehrten transform zurück in das lokale Verzeichnis
4. Starten Sie die Instanz mit der alten Konfiguration neu

# When using aws cli
aws s3 sync s3://overleaf-user-files /srv/overleaf-s3-migration/user_files
aws s3 sync s3://overleaf-template-files /srv/overleaf-s3-migration/template_files
aws s3 sync s3://overleaf-project-blobs /srv/overleaf-bind-mount/data/history/overleaf-project-blobs
aws s3 sync s3://overleaf-chunks /srv/overleaf-bind-mount/data/history/overleaf-chunks

# When using minio mc
mc mirror s3/overleaf-user-files /srv/overleaf-s3-migration/user_files
mc mirror s3/overleaf-template-files /srv/overleaf-s3-migration/template_files
mc mirror s3/overleaf-project-blobs /srv/overleaf-bind-mount/data/history/overleaf-project-blobs
mc mirror s3/overleaf-chunks /srv/overleaf-bind-mount/data/history/overleaf-chunks

# Write files into local Server CE/Server Pro
tar --create --directory /srv/overleaf-s3-migration/user_files . \
| tar \
      --extract \
      --keep-old-files \
      --directory /srv/overleaf-bind-mount/data/user_files \
      --transform=sx./xx --transform=sx/x_x \
      --wildcards '*/*/*'

tar --create --directory /srv/overleaf-s3-migration/template_files . \
| tar \
      --extract \
      --keep-old-files \
      --directory /srv/overleaf-bind-mount/data/template_files \
      --transform=sx./xx --transform=sx/x_xg \
      --wildcards '*/*/*/*/pdf-converted-cache/*' \
      --wildcards '*/*/*/*/pdf' \
      --wildcards '*/*/*/*/zip'

Die erste Transformation entfernt den Ordner der obersten Ebene. Die zweite Transformation wandelt das Verzeichnislayout in ein flaches Layout um. Die Wildcards stellen sicher, dass nur Dateien extrahiert werden, nicht deren übergeordnete (Projekt-)Ordner.