Aller au contenu
Oleaflyv0.4.12

Faire tourner un serveur

Tous les paramètres d'Oleafly Server, le stockage des fichiers sur disque ou dans un bucket S3, les PDF compilés, le fonctionnement derrière un proxy, les limites pour une classe sur un même réseau et pour chaque compte, les journaux, les sauvegardes, les restaurations et les mises à jour.

Cette page traite de l’exploitation quotidienne d’Oleafly Server. Pour l’installer, commencez par Gérer un serveur de collaboration.

Le serveur lit ses paramètres dans des variables d’environnement. Une variable définie mais vide est considérée comme non définie. Si un paramètre est manquant ou mal formé, le serveur ne démarre pas, et son journal indique lequel.

VariableCe qu’elle faitValeur par défaut
OLEAFLY_PUBLIC_URLL’adresse HTTPS que les gens saisissent dans Oleafly. Elle peut inclure un chemin, comme https://www.cs.example.edu/oleafly. Obligatoire. Les fichiers Compose et Coolify la définissent pour vous.Aucune
OLEAFLY_BINDL’adresse et le port sur lesquels le serveur écoute.0.0.0.0:8080
OLEAFLY_DATA_DIRLe dossier pour la base de données et les fichiers stockés./data
OLEAFLY_SERVER_NAMELe nom que les gens voient dans Oleafly, comme Smith Lab.Oleafly Server
OLEAFLY_SERVER_ICON_URLL’adresse HTTPS d’une image carrée affichée à côté du nom.Aucune
OLEAFLY_SETUP_CODEVotre propre code de configuration à usage unique : au moins 12 lettres ou chiffres, avec des tirets ou des espaces si vous voulez. Sans lui, le serveur en génère un.Généré
OLEAFLY_GITHUB_CLIENT_ID, OLEAFLY_GITHUB_CLIENT_SECRETActive la connexion avec GitHub.Désactivé
OLEAFLY_GITHUB_URLL’adresse d’un GitHub Enterprise Server.https://github.com
OLEAFLY_GITHUB_API_URLL’adresse de l’API GitHub, si la vôtre est inhabituelle.https://api.github.com, ou /api/v3 sous OLEAFLY_GITHUB_URL
OLEAFLY_GITHUB_LABELLe texte du bouton de connexion GitHub.GitHub
OLEAFLY_OIDC_<NAME>_ISSUER, OLEAFLY_OIDC_<NAME>_CLIENT_ID, OLEAFLY_OIDC_<NAME>_CLIENT_SECRETActive un fournisseur OpenID Connect appelé <NAME>.Désactivé
OLEAFLY_OIDC_<NAME>_LABELLe texte de son bouton de connexion, comme University login.<NAME>
OLEAFLY_OIDC_<NAME>_TRUST_EMAILConsidère chaque adresse courriel de ce fournisseur comme vérifiée. Lisez d’abord Adresses courriel vérifiées.false
OLEAFLY_SMTP_URL, OLEAFLY_MAIL_FROMCourriel. Lisez Courriel.Désactivé
OLEAFLY_OPEN_SIGNUPDonne un compte de membre à toute personne qui se connecte avec l’un de vos fournisseurs. Lisez Inscription ouverte.false
OLEAFLY_WEBActive l’accès par navigateur. Lisez Accès par navigateur.false
OLEAFLY_BLOB_STOREL’endroit où sont stockés les fichiers tels que les figures et les PDF. fs les garde dans OLEAFLY_DATA_DIR. Une adresse comme s3://lab-bucket ou s3://lab-bucket/oleafly les garde dans un bucket.fs
OLEAFLY_S3_ENDPOINTL’adresse d’un stockage compatible S3 autre qu’Amazon S3, comme MinIO ou Cloudflare R2. Laissez-la vide pour Amazon S3.Amazon S3
OLEAFLY_S3_REGIONLa région du bucket.us-east-1
OLEAFLY_S3_ACCESS_KEY_ID, OLEAFLY_S3_SECRET_ACCESS_KEYLa clé que le serveur utilise pour le bucket. Obligatoire avec une adresse s3://.Aucune
OLEAFLY_MAX_PROJECT_MBLe plus gros projet que le serveur accepte, en mégaoctets.200
OLEAFLY_MAX_FILE_MBLe plus gros fichier individuel, en mégaoctets.50
OLEAFLY_MAX_MEMBERS_PER_PROJECTLe nombre maximal de personnes sur un projet.20
OLEAFLY_ACCOUNT_STORAGE_MBLe stockage maximal pour les projets qu’un compte possède, en mégaoctets. Lisez Limites par compte.Aucune limite, ou 100 avec l’inscription ouverte
OLEAFLY_MAX_PROJECTS_PER_ACCOUNTLe nombre maximal de projets partagés qu’un compte peut posséder.Aucune limite, ou 50 avec l’inscription ouverte
OLEAFLY_UPLOADS_PER_HOURLe nombre de téléversements de fichiers et d’instantanés qu’un compte peut faire en une heure.Aucune limite, ou 300 avec l’inscription ouverte
OLEAFLY_SIGN_IN_BURSTLe nombre de requêtes de connexion qu’une adresse réseau peut émettre en rafale. Une connexion en demande environ six, donc la valeur par défaut couvre 50 personnes se connectant à la fois depuis une même adresse.300
OLEAFLY_SIGN_IN_PER_MINUTELe nombre de requêtes de connexion qu’une adresse réseau obtient en retour chaque minute après la rafale.120
OLEAFLY_EMAIL_LINKS_PER_IPLe nombre de courriels de connexion que le serveur envoie aux personnes d’une même adresse réseau en 15 minutes.100
OLEAFLY_EMAIL_LINKS_PER_ADDRESSLe nombre de courriels de connexion qu’une même adresse courriel peut recevoir en 15 minutes. Ne peut pas dépasser OLEAFLY_EMAIL_LINKS_PER_IP.3
OLEAFLY_DEVICE_CODES_PER_IPLe nombre de codes de connexion que les personnes d’une même adresse réseau peuvent demander en 10 minutes.100
OLEAFLY_SNAPSHOT_MEMORY_MBLa quantité de mémoire, en mégaoctets, que le serveur peut utiliser pour construire les instantanés des projets.La moitié de la limite de mémoire du conteneur, ou 1024 sans limite
OLEAFLY_BEHIND_PROXYPrend l’adresse de chaque personne dans l’en-tête X-Forwarded-For qu’ajoute votre proxy. Les fichiers Compose, Coolify et Render l’activent.false
OLEAFLY_PROXY_HOPSLe nombre de proxys que chaque requête traverse avant d’atteindre le serveur. Nécessite OLEAFLY_BEHIND_PROXY=true.1
OLEAFLY_LOG_LEVELLa quantité de ce que le serveur journalise : error, warn, info, debug ou trace. Les bibliothèques utilisées par le serveur ne journalisent que des avertissements, sauf si vous choisissez debug ou trace.info
OLEAFLY_SECURITY_LOG_DAYSLe nombre de jours de conservation des entrées du journal de sécurité, des entrées des journaux d’accès aux projets et des invitations d’invités répondues ou expirées.365
OLEAFLY_ARCHIVE_DAYSLe nombre de jours de conservation d’un projet après que son propriétaire a arrêté de le partager.30
OLEAFLY_POLL_HOLD_SECONDSLa durée pendant laquelle le serveur garde une requête de long-polling ouverte quand aucune modification n’attend, de 1 à 40 secondes. Gardez-la quelques secondes sous le délai d’inactivité de tout proxy placé devant le serveur.25

Dans le fichier .env de Compose, mettez une valeur entre guillemets simples si elle contient $ ou #. Les paramètres qui contiennent des secrets peuvent aussi être lus depuis des fichiers. Lisez Garder les secrets hors de .env.

Par défaut, le serveur garde tout dans OLEAFLY_DATA_DIR : la base de données, les fichiers que les gens partagent et les instantanés des projets. Les instantanés sont des copies enregistrées de chaque projet, qui permettent aux gens de rejoindre un projet et de se remettre à niveau rapidement.

Le serveur peut à la place garder les fichiers et les instantanés dans Amazon S3, ou dans un autre stockage doté d’une API compatible S3, comme MinIO ou Cloudflare R2. Dans tous les cas, la base de données reste dans OLEAFLY_DATA_DIR, donc le serveur a toujours besoin de son dossier de données.

  1. Créez un bucket et bloquez son accès public.

  2. Créez une clé capable de lire, écrire et supprimer des objets dans ce bucket et rien d’autre. Sur Amazon S3, cela signifie s3:GetObject, s3:PutObject et s3:DeleteObject sur arn:aws:s3:::lab-bucket/*, ou sur arn:aws:s3:::lab-bucket/oleafly/* si vous utilisez un dossier.

  3. Définissez les variables, par exemple dans .env :

    Fenêtre de terminal
    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

Pour un stockage autre qu’Amazon S3, définissez aussi OLEAFLY_S3_ENDPOINT avec son adresse, comme https://minio.example.org:9000 ou https://<account-id>.r2.cloudflarestorage.com, et OLEAFLY_S3_REGION avec la région qu’il attend (auto pour R2). Le simple http:// fonctionne aussi, mais ne l’utilisez que si le stockage se trouve sur le même réseau privé que le serveur.

La partie après le nom du bucket est un dossier facultatif. Chaque fichier est nommé d’après son empreinte SHA-256 et se trouve sous les deux premiers caractères de cette empreinte, donc un fichier dont l’empreinte commence par 3f9a est stocké sous oleafly/3f/3f9a.... Les instantanés ont leur propre dossier snapshots, avec un dossier pour chaque projet. Quand le serveur relit un fichier ou un instantané, il compare les octets à l’empreinte et refuse celui qui ne correspond pas. Sans bucket, la même organisation se trouve dans le dossier blobs à l’intérieur de OLEAFLY_DATA_DIR.

Si le bucket refuse une requête, cet envoi ou ce téléchargement échoue, et le journal du serveur montre ce que le bucket a dit, comme 403 Forbidden (AccessDenied). Une erreur du serveur, un délai d’attente dépassé ou une connexion interrompue, c’est autre chose : le serveur réessaie jusqu’à trois fois, avec une courte pause aléatoire entre les tentatives. S’il ne peut pas supprimer un objet, il le note et réessaie à chaque passage de maintenance, toutes les 6 heures, pour qu’une panne ne laisse pas d’objets derrière elle.

Quand un projet est partagé, l’application de son propriétaire téléverse le premier instantané et le signe avec la clé de cet appareil. À partir de là, le serveur construit lui-même chaque instantané, à partir de l’instantané précédent et des modifications envoyées depuis. Un nouvel instantané est construit dès qu’un projet accumule 1 000 modifications au-delà du dernier. Le serveur conserve toujours au moins les 2 000 dernières modifications, donc un appareil absent pendant une courte période rattrape son retard à partir de celles-ci et ne retélécharge pas tout le projet.

La construction d’un instantané demande environ dix fois la taille de l’instantané précédent plus les modifications depuis celui-ci. Le serveur ne démarre une construction que si elle tient dans OLEAFLY_SNAPSHOT_MEMORY_MB, et les constructions simultanées se partagent cette quantité. Si une construction ne tient pas, le serveur la saute, journalise la mémoire dont elle a besoin et conserve toutes les modifications du projet. Les appareils rattrapent alors leur retard à partir de ces modifications, quelques mégaoctets à la fois. Augmentez le paramètre et l’instantané suivant sera construit. Le serveur ne stockera pas un instantané plus grand que OLEAFLY_MAX_PROJECT_MB.

Quand un propriétaire ou un éditeur compile avec succès un projet partagé, son application envoie le PDF au serveur, avec son fichier SyncTeX s’il y en a un. Elle en envoie au plus un par minute pour chaque projet. Le serveur garde un PDF et un fichier SyncTeX par projet, avec le nom du fichier principal, qui l’a compilé et quand. L’accès par navigateur montre ce PDF aux personnes du projet.

Chaque envoi remplace le précédent, et l’ancien fichier est supprimé dès que plus rien ne l’utilise. Les fichiers compilés sont stockés avec les autres fichiers, sur disque ou dans le bucket, et sont supprimés avec leur projet. Un fichier compilé peut atteindre OLEAFLY_MAX_FILE_MB. Il compte dans le stockage du compte du propriétaire, mais pas dans les téléversements par heure.

Chaque membre d’un projet peut lire ses fichiers compilés. Seuls les propriétaires et les éditeurs peuvent les remplacer.

Le serveur parle HTTP simple, donc quelque chose devant lui s’occupe du HTTPS : Caddy dans l’installation Compose, le proxy de Coolify, ou un serveur web que vous faites déjà tourner, comme celui de votre université. Ce qui se trouve devant doit :

  • accepter des requêtes aussi grandes que OLEAFLY_MAX_PROJECT_MB
  • ajouter l’adresse du client à X-Forwarded-For

Il devrait aussi transmettre les mises à niveau WebSocket vers /ws et garder ces connexions ouvertes pendant au moins une heure. L’édition en direct les utilise quand elle le peut. Avec l’accès par navigateur activé, il doit aussi les transmettre vers /web/ws, car l’application pour navigateur n’a pas de solution de repli plus lente.

Faites tourner le serveur là où seul le proxy peut l’atteindre. Sur la même machine, définissez OLEAFLY_BIND=127.0.0.1:8080. Définissez ensuite OLEAFLY_BEHIND_PROXY=true.

Certains réseaux bloquent les connexions WebSocket, souvent un réseau universitaire ou d’entreprise avec un proxy de filtrage. L’édition en direct y fonctionne quand même, plus lentement. Quand deux tentatives WebSocket d’affilée échouent alors que le serveur répond toujours en HTTPS, Oleafly passe au long-polling HTTP. Il envoie les modifications vers /api/v1/projects/<project>/frames et attend celles des autres personnes sur /api/v1/projects/<project>/poll, en gardant chaque requête ouverte jusqu’à OLEAFLY_POLL_HOLD_SECONDS. Chaque modification arrive quand même. Oleafly réessaie une WebSocket chaque minute et y revient dès qu’une se connecte.

Tester la connexion dans Oleafly et Tests de connexion dans la console d’administration indiquent quand cela arrive : « Les modifications en direct passent par une voie plus lente, car ce réseau bloque la voie habituelle. Elles arrivent quand même. »

Si vous gérez le proxy devant le serveur, transmettez quand même les mises à niveau WebSocket. Le long-polling fonctionne, mais chaque lot de modifications coûte une requête supplémentaire et un peu plus de retard.

Certains proxys ferment une requête qui reste silencieuse moins de 30 secondes, nginx avec un proxy_read_timeout court, par exemple. Ils répondent aux requêtes de long-polling par une erreur 502 ou 504, et les modifications arrivent en retard. Définissez OLEAFLY_POLL_HOLD_SECONDS quelques secondes sous ce délai, par exemple 8 pour un délai de 10 secondes.

Le serveur note l’adresse d’un client à deux endroits : le journal de sécurité, et les limites sur la fréquence à laquelle une adresse peut lancer une connexion ou ouvrir une connexion en direct.

Sans ce paramètre, le serveur utilise l’adresse de ce qui s’y est connecté. Derrière un proxy, c’est toujours le proxy, donc tout le monde partage une même limite et le journal de sécurité n’affiche que l’adresse du proxy.

Avec OLEAFLY_BEHIND_PROXY=true, le serveur lit l’en-tête X-Forwarded-For et utilise la dernière adresse qu’il contient, celle qu’a ajoutée votre proxy. Si l’en-tête est absent ou ne contient aucune adresse valide, le serveur revient à l’adresse de connexion. Rien d’autre ne change. Le serveur ignore X-Forwarded-Proto, X-Forwarded-Host et Forwarded, et construit chaque adresse qu’il distribue à partir de OLEAFLY_PUBLIC_URL.

Activez-le seulement quand chaque requête passe par votre proxy. Si des gens peuvent aussi atteindre le serveur directement, n’importe qui peut envoyer un X-Forwarded-For inventé, inscrire n’importe quelle adresse dans le journal de sécurité et contourner la limite de connexions.

Avec deux proxys à la suite, par exemple Cloudflare devant le proxy de Coolify, définissez OLEAFLY_PROXY_HOPS=2. Le serveur prend alors la deuxième adresse en partant de la fin. Ne comptez que les proxys traversés par chaque requête. Un tunnel Cloudflare qui mène directement au serveur compte pour un.

Pour vérifier le nombre, connectez-vous depuis votre propre ordinateur et ouvrez Journal de sécurité dans la console d’administration. L’entrée la plus récente devrait afficher votre adresse publique, celle qu’un site comme ifconfig.me indique. Si elle affiche plutôt une adresse privée ou Cloudflare, augmentez OLEAFLY_PROXY_HOPS d’un.

Caddy transmet les connexions WebSocket et X-Forwarded-For sans réglages supplémentaires, et obtient lui-même le certificat. Mettre le HTTPS devant contient le Caddyfile complet.

Obtenez d’abord un certificat pour le domaine, par exemple avec certbot. Enregistrez ensuite ceci sous /etc/nginx/conf.d/oleafly.conf et exécutez sudo nginx -t && sudo systemctl reload nginx :

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 correspond à la valeur par défaut de 200 pour OLEAFLY_MAX_PROJECT_MB. Si vous augmentez l’un, augmentez l’autre.

Il vous faut Apache 2.4.47 ou plus récent, ce que Debian 12 ainsi qu’Ubuntu 22.04 et suivants intègrent. Activez les modules :

Fenêtre de terminal
sudo a2enmod proxy proxy_http ssl

Enregistrez ceci sous /etc/apache2/sites-available/oleafly.conf, puis exécutez sudo a2ensite oleafly && sudo systemctl reload apache2 :

<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 transmet les connexions WebSocket et timeout=3600 les garde ouvertes pendant une heure. Apache ajoute de lui-même l’adresse du client à X-Forwarded-For.

Si le serveur se trouve sous un chemin, incluez ce chemin dans OLEAFLY_PUBLIC_URL, par exemple https://www.cs.example.edu/oleafly, et dans les adresses de rappel que vous enregistrez auprès des fournisseurs de connexion. Le serveur répond avec et sans ce chemin, donc votre proxy peut le transmettre ou le retirer. Avec nginx, utilisez location /oleafly/ { avec les mêmes lignes à l’intérieur, et gardez proxy_pass http://127.0.0.1:8080; sans chemin pour que nginx transmette le chemin.

Toute une classe se connecte souvent depuis une même adresse réseau, par exemple le NAT d’une université. Les valeurs par défaut sont réglées pour cela :

  • Connexions : une adresse obtient une rafale de 300 requêtes de connexion, puis deux par seconde. Une connexion en demande environ six, donc 50 personnes peuvent se connecter à la fois. Modifiez ces valeurs avec OLEAFLY_SIGN_IN_BURST et OLEAFLY_SIGN_IN_PER_MINUTE.
  • Liens par courriel : 100 vers une adresse réseau en 15 minutes, et 3 vers une même adresse courriel. Modifiez ces valeurs avec OLEAFLY_EMAIL_LINKS_PER_IP et OLEAFLY_EMAIL_LINKS_PER_ADDRESS.
  • Codes de connexion : 100 codes, et 10 codes erronés, depuis une adresse en 10 minutes. Modifiez cette valeur avec OLEAFLY_DEVICE_CODES_PER_IP.
  • Les connexions en direct ont leur propre limite, plus élevée, pour qu’une classe entière derrière une même adresse puisse se reconnecter d’un coup après un redémarrage. Seules les connexions qui ne parviennent pas à prouver leur session la consomment : une rafale de 300, puis dix par seconde. Une connexion qui prouve sa session est comptée sur son propre appareil, qui peut se reconnecter 60 fois en rafale, puis une fois par seconde.

Toutes les adresses IPv6 d’un même réseau /64 comptent pour une seule adresse. Ces limites ne s’appliquent par personne que si le serveur voit l’adresse réelle de chacune, donc configurez votre proxy correctement.

Le serveur envoie un ping à chaque connexion en direct toutes les 30 secondes. Il ferme une connexion qui laisse ces pings sans réponse pendant 90 secondes, et une qui cesse de lire ce que le serveur envoie.

Les limites de projet s’appliquent à tous : OLEAFLY_MAX_PROJECT_MB pour un projet entier (200 Mo par défaut), OLEAFLY_MAX_FILE_MB pour un fichier (50 Mo) et OLEAFLY_MAX_MEMBERS_PER_PROJECT pour les personnes d’un projet (20). La Vue d’ensemble de la console d’administration affiche les limites en vigueur.

Trois limites s’appliquent à chaque compte. Elles sont désactivées tant que vous ne les définissez pas, sauf si l’inscription ouverte est activée, ce qui les active avec ces valeurs par défaut :

LimiteParamètreAvec l’inscription ouverte
Stockage des projets qu’un compte possèdeOLEAFLY_ACCOUNT_STORAGE_MB100 Mo
Projets partagés qu’un compte possèdeOLEAFLY_MAX_PROJECTS_PER_ACCOUNT50
Téléversements d’un compte en une heureOLEAFLY_UPLOADS_PER_HOUR300

Une valeur que vous définissez l’emporte toujours sur la valeur par défaut. Chacune doit être un nombre entier d’au moins 1.

  • Stockage additionne les fichiers et l’historique des modifications de chaque projet que le compte possède, projets archivés compris, ainsi que leurs PDF compilés. Les instantanés ne comptent pas. Un fichier ajouté à un projet par n’importe qui compte pour le propriétaire du projet. Une fois le compte du propriétaire plein, le serveur refuse les nouveaux fichiers et les PDF compilés de ses projets, et il ne peut plus partager d’autre projet. Le fichier reste sur l’ordinateur de la personne qui l’a ajouté. Le texte que les personnes tapent continue de se synchroniser.
  • Projets partagés compte les projets que le compte partage, y compris ceux encore en cours de téléversement. Les projets archivés ne comptent pas, donc arrêter le partage de l’un d’eux libère une place.
  • Téléversements compte chaque téléversement de fichier et d’instantané sur une fenêtre d’une heure. Les PDF compilés ne comptent pas. Oleafly renvoie plus tard de lui-même un fichier refusé.

La Vue d’ensemble de la console d’administration n’affiche pas ces limites. Avec l’inscription ouverte activée, le journal du serveur les nomme à chaque démarrage.

  • Le journal du serveur est ce qu’affichent docker compose logs oleafly-server, les Logs de Coolify ou journalctl -u oleafly-server. OLEAFLY_LOG_LEVEL définit son niveau de détail.
  • Le journal de sécurité enregistre les connexions et les connexions refusées, les appareils, les personnes, les rôles, les paramètres, les projets et les invités, chacun avec l’heure et l’adresse IP. Les administrateurs et les mainteneurs le lisent sous Journal de sécurité dans la console d’administration. Les entrées plus vieilles que OLEAFLY_SECURITY_LOG_DAYS jours sont supprimées.
  • Les journaux d’accès aux projets enregistrent qui a ouvert un projet, l’a rejoint ou en a téléchargé une copie, avec le nom de l’appareil et l’heure. Le propriétaire d’un projet en active un quand Autoriser les journaux d’accès aux projets est activé, et seul ce propriétaire peut le lire. La même durée de conservation s’applique.

Ce dont une sauvegarde complète a besoin dépend de l’endroit où les fichiers sont stockés :

  • Fichiers sur disque (OLEAFLY_BLOB_STORE=fs, la valeur par défaut) : la base de données, les fichiers et les instantanés sont tous dans le dossier de données. Sauvegardez le dossier entier.
  • Fichiers dans un bucket : le dossier de données contient la base de données et le bucket contient les fichiers et les instantanés. Une copie de la base de données plus le bucket constituent une sauvegarde complète. Activez le versioning du bucket pour pouvoir retrouver un objet supprimé par erreur.
Où le serveur garde ses données, et que sauvegarderAvec les fichiers sur le disque, l’option par défaut, le dossier de données contient la base de données et le dossier blobs avec les fichiers et les instantanés : vous sauvegardez tout le dossier. Avec les fichiers dans un bucket, le dossier de données contient la base de données et un bucket S3 contient les fichiers et les instantanés : vous sauvegardez la base de données et le bucket.Fichiers sur le disque (par défaut)Fichiers dans un bucketoleafly-serverDossier de donnéesBase de données : comptes, réglages, journauxblobs : fichiers et instantanésSauvegardez tout le dossieroleafly-serverDossier de donnéesBase de donnéesBucket S3Fichiers etinstantanésSauvegardez la base de données et le bucketOù le serveur garde ses données, et que sauvegarderAvec les fichiers sur le disque, l’option par défaut, le dossier de données contient la base de données et le dossier blobs avec les fichiers et les instantanés : vous sauvegardez tout le dossier. Avec les fichiers dans un bucket, le dossier de données contient la base de données et un bucket S3 contient les fichiers et les instantanés : vous sauvegardez la base de données et le bucket.Fichiers sur le disque (par défaut)Fichiers dans un bucketoleafly-serverDossier de donnéesBase de données et blobs(fichiers, instantanés)Sauvegardez tout le dossieroleafly-serverDossier de donnéesBase de donnéesBucket S3Fichiers etinstantanésSauvegardez la base de donnéeset le bucket
Ce qu’il faut pour une sauvegarde complète dépend de l’endroit où sont stockés les fichiers.

Sauvegardez régulièrement et gardez les copies privées, puisqu’elles contiennent tous les projets. Vos paramètres, comme .env, ne se trouvent pas dans le dossier de données, donc gardez-en aussi une copie.

Avec Docker, le serveur s’arrête quelques secondes pendant que vous copiez le volume. Oleafly se reconnecte tout seul. Exécutez ces commandes dans le dossier du serveur, /opt/oleafly-server si vous avez utilisé l’installateur.

Fenêtre de terminal
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

Avec systemd :

Fenêtre de terminal
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

Copiez l’archive sur une autre machine.

Sur Coolify, le nom du volume commence par l’identifiant de la ressource. Trouvez-le avec docker volume ls --filter name=oleafly-data, utilisez-le à la place de oleafly-server_oleafly-data, et arrêtez et démarrez le serveur depuis le tableau de bord de Coolify plutôt qu’avec docker compose.

Une sauvegarde que vous n’avez jamais restaurée n’est qu’un espoir. Cet exercice démarre une deuxième copie du serveur depuis une sauvegarde, laisse celle qui tourne tranquille, et vérifie que les deux sont le même serveur. Utilisez la date de votre propre archive à la place de 2026-10-11.

Fenêtre de terminal
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

Le server_id des deux réponses doit correspondre. La copie de l’exercice a une connexion GitHub factice qui ne peut connecter personne, et aucun port ouvert, donc personne ne peut l’utiliser. Supprimez-la quand vous avez fini :

Fenêtre de terminal
sudo docker rm -f oleafly-restore-drill
sudo docker volume rm oleafly-restore-drill

Pour restaurer vraiment avec Docker Compose, arrêtez le serveur, remplacez le contenu du volume par l’archive, puis démarrez-le à nouveau :

Fenêtre de terminal
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

Avec systemd :

Fenêtre de terminal
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

Il manque au serveur restauré les modifications que les gens ont faites après la sauvegarde. Chaque application s’en aperçoit quand elle se reconnecte, qu’elle soit restée ouverte ou ouverte plus tard, et renvoie ses propres modifications manquantes. Personne n’a rien à faire pour cela. Une modification qui s’appuie sur la modification manquante de quelqu’un d’autre attend que cette personne ouvre le projet, car seule son application peut envoyer ses modifications. Demandez à tous ceux qui modifiaient le projet autour du moment de la panne de l’ouvrir une fois.

Une archive ne contient que ce qui s’y trouvait au moment où vous l’avez créée. Litestream (s’ouvre dans un nouvel onglet) copie chaque modification apportée à la base de données du serveur vers un bucket compatible S3 environ une seconde après qu’elle survient. Le fichier Compose l’inclut comme service facultatif.

Litestream ne copie que la base de données. Si les fichiers sont dans un bucket, le bucket contient déjà les fichiers et les instantanés, donc la copie Litestream et le bucket ensemble permettent de retrouver un disque perdu. Si les fichiers sont sur disque, continuez aussi à faire des archives du volume, car Litestream ne copie pas le dossier blobs.

  1. Créez un bucket, ou un dossier dans un bucket, que seul le Litestream de ce serveur utilise. Ne le partagez pas avec OLEAFLY_BLOB_STORE. Donnez à Litestream une clé capable de lister le bucket et de lire, écrire et supprimer les objets qu’il contient.

  2. Ajoutez les détails à .env :

    Fenêtre de terminal
    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

    Pour un stockage autre qu’Amazon S3, définissez aussi LITESTREAM_ENDPOINT avec son adresse et LITESTREAM_REGION avec la région qu’il attend (auto pour R2). COMPOSE_PROFILES fait en sorte que chaque commande docker compose inclut Litestream.

  3. Démarrez-le :

    Fenêtre de terminal
    sudo docker compose up -d
  4. Vérifiez qu’il a copié la base de données. Ceci affiche une ligne avec snapshot complete :

    Fenêtre de terminal
    sudo docker compose logs litestream | grep 'snapshot complete'

Litestream fait une copie complète une fois par jour et garde une semaine de copies ainsi que les modifications entre elles. Le calendrier se trouve dans litestream.yml.

Cet exercice restaure la base de données depuis le bucket dans un volume temporaire, démarre une deuxième copie du serveur dessus, et vérifie que les deux sont le même serveur. Le serveur en cours d’exécution n’est pas touché.

Fenêtre de terminal
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

La première commande crée le volume temporaire avec le propriétaire dont le serveur a besoin. Le server_id des deux dernières réponses doit correspondre. Supprimez la copie quand vous avez fini :

Fenêtre de terminal
sudo docker rm -f oleafly-litestream-drill
sudo docker volume rm oleafly-litestream-drill

Quand le fichier de base de données est endommagé ou disparu mais que le reste du dossier de données va bien, arrêtez le serveur et Litestream, supprimez ce qui reste de la base de données, restaurez-la puis démarrez à nouveau :

Fenêtre de terminal
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

Après un disque perdu avec les fichiers dans un bucket, exécutez les commandes ci-dessus sur le nouveau volume vide et gardez les mêmes paramètres de bucket dans .env. Chaque projet revient avec ses fichiers et ses instantanés.

Après un disque perdu avec les fichiers sur disque, restaurez votre archive la plus récente et arrêtez-vous là. Ne posez pas une base de données plus récente de Litestream par-dessus une archive plus ancienne. La base pointerait vers des fichiers et des instantanés que l’archive ne contient pas, et ces projets ne s’ouvriraient pas.

Sauvegardez d’abord. Le serveur met à jour sa base de données au premier démarrage d’une nouvelle version, donc revenir à une version plus ancienne suppose de restaurer la sauvegarde faite avant la mise à jour.

  • Installation en une commande : exécutez curl -fsSL https://oleafly.com/server/install.sh | sudo sh -s -- update. Elle garde .env, récupère les fichiers et l’image de la nouvelle version, puis redémarre le serveur.
  • Docker Compose à la main : téléchargez les fichiers de la nouvelle version dans le dossier du serveur comme dans Docker Compose à la main, puis exécutez sudo docker compose up -d.
  • Coolify : sélectionnez Redeploy. Avec l’image publiée, cela récupère la version la plus récente sous l’étiquette de l’image.
  • Render : ouvrez le service et lancez un déploiement manuel, qui récupère à nouveau l’image.
  • Railway : déployez à nouveau le service depuis son menu. Railway peut aussi mettre à jour tout seul une image du registre de GitHub.
  • systemd : installez la nouvelle version comme dans Télécharger le serveur, puis exécutez sudo systemctl restart oleafly-server.

Oleafly vérifie la version du serveur à chaque connexion. Si l’application et le serveur ne peuvent pas travailler ensemble, Oleafly indique lequel a besoin d’une mise à jour.

Aperçu de l’image

Impossible de charger les réponses de l’IA

Réessayez ou cherchez dans la documentation.