Héberger Excalidraw sur VPS : tableau blanc sans abonnement

Pourquoi auto-héberger Excalidraw plutôt que d'utiliser la version en ligne

Ce que vous gagnez concrètement

• Zéro abonnement logiciel — les deux composants (interface et serveur de collaboration) sont MIT. Vous payez le VPS, rien d'autre.
• Confidentialité des maquettes — le dessin en direct reste sur votre infrastructure. La scène enregistrée et les images d'une salle sont à traiter (Firebase par défaut) : voir « Ce qui marche vraiment en auto-hébergement ».
• Accès sous votre contrôle — allowlist d'IP, SSO OIDC ou HTTP Basic Auth devant nginx selon le niveau d'isolation requis.
• Sessions et membres sans quota imposés — pas de plafond par plan ; la seule limite est la RAM du serveur, et excalidraw-room est un service Node.js léger.
• Persistance optionnelle — montez un volume Docker ou branchez un bucket S3 compatible pour archiver les tableaux exportés en JSON.
• Intégration dans un parc self-hosted — une instance Excalidraw aux côtés de Penpot, Mattermost ou Docmost ferme le périmètre SaaS de toute une agence.

Architecture : deux conteneurs, rôles distincts

Prérequis

Checklist prérequis

• Un VPS avec au moins 1 vCPU et 512 Mo de RAM (1 Go recommandé pour une équipe).
• Docker Engine et Docker Compose Plugin installés (docker compose version pour vérifier).
• Un nom de domaine pointé vers l'IP du VPS — sans TLS les WebSockets sont bloqués par les navigateurs modernes.
• Accès SSH root ou un utilisateur avec droits sudo.
• Un certificat TLS valide — ServOrbit configure Let's Encrypt automatiquement.

Déployer Excalidraw en 5 étapes

1. 01

   Créer le VPS et installer Docker

   Provisionnez un VPS Ubuntu 24.04 depuis l'espace ServOrbit. Une fois connecté en SSH, si Docker n'est pas encore présent, installez-le en une passe :

   curl -fsSL https://get.docker.com | sh

   Vérifiez que Docker Compose Plugin répond avant de continuer :

   docker compose version

2. 02

   Construire l'image avec votre URL de collaboration

   Clonez le dépôt officiel, puis réglez l'adresse de la salle dans le fichier .env.production du dépôt avant de construire. Remplacez collab.yourdomain.com par le sous-domaine alloué à excalidraw-room :

   git clone https://github.com/excalidraw/excalidraw.git
cd excalidraw
sed -i 's|^VITE_APP_WS_SERVER_URL=.*|VITE_APP_WS_SERVER_URL=https://collab.yourdomain.com|' .env.production
docker build -t my-excalidraw:latest .

   Pourquoi pas --build-arg ? Le Dockerfile amont ne déclare aucun ARG pour les variables VITE_APP_* : un --build-arg VITE_APP_WS_SERVER_URL=… n'atteint jamais la commande de build, l'image se construit normalement et continue de viser le serveur d'Excalidraw. Le .dockerignore amont n'admet d'ailleurs que .env.development et .env.production : un .env.production.local serait ignoré. L'adresse est gravée dans le bundle, donc changer de domaine impose de reconstruire.

   Vérifiez le résultat : docker run --rm --entrypoint sh my-excalidraw:latest -c "grep -rl oss-collab.excalidraw.com /usr/share/nginx/html || echo propre" doit afficher propre. L'image officielle excalidraw/excalidraw convient pour des essais locaux, mais elle vise les services publics d'Excalidraw.

3. 03

   Écrire le fichier docker-compose.yml

   Créez un répertoire de travail et posez le fichier suivant. Les deux services écoutent en interne ; nginx (à l'étape suivante) est le seul point d'entrée public :

   mkdir ~/excalidraw-stack && cd ~/excalidraw-stack

   Contenu du docker-compose.yml :

   services:
     excalidraw:
       image: my-excalidraw:latest
       restart: unless-stopped
       networks:
         - excalidraw
   
     excalidraw-room:
       image: excalidraw/excalidraw-room:latest
       environment:
         - CORS_ORIGIN=https://draw.yourdomain.com
       restart: unless-stopped
       networks:
         - excalidraw
   
   networks:
     excalidraw:

   Lancez la stack :

   docker compose up -d

4. 04

   Configurer nginx avec les en-têtes WebSocket

   C'est l'étape où la plupart des déploiements échouent en silence : sans les en-têtes Upgrade et Connection, le navigateur ouvre une connexion HTTP normale au lieu d'un WebSocket, et la collaboration semble ne pas démarrer sans aucun message d'erreur visible.

   Bloc nginx pour le frontend Excalidraw (draw.yourdomain.com) :

   server {
       listen 443 ssl;
       server_name draw.yourdomain.com;
   
       location / {
           proxy_pass http://excalidraw:80;
           proxy_set_header Host $host;
       }
   }

   Bloc nginx pour le serveur de salle (collab.yourdomain.com) :

   server {
       listen 443 ssl;
       server_name collab.yourdomain.com;
   
       location / {
           proxy_pass http://excalidraw-room:80;
           proxy_http_version 1.1;
           proxy_set_header Upgrade $http_upgrade;
           proxy_set_header Connection "upgrade";
           proxy_set_header Host $host;
           proxy_read_timeout 86400s;
       }
   }

   Rechargez nginx (nginx -s reload) après avoir posé les blocs.

5. 05

   Tester la collaboration en temps réel

   Ouvrez https://draw.yourdomain.com dans deux onglets ou deux navigateurs différents. Dans la barre d'outils, cliquez sur Live collaboration et créez une session. Copiez le lien de session dans le second onglet.

   Dessinez quelque chose dans le premier onglet : le trait doit apparaître dans le second en temps réel. S'il n'apparaît pas, vérifiez d'abord les en-têtes WebSocket dans nginx (les devtools réseau du navigateur montrent si la connexion est passée en 101 Switching Protocols). Un status 200 sur la requête WebSocket indique que nginx n'a pas transmis les en-têtes Upgrade.

   Ouvrez ensuite l'onglet réseau du navigateur : la connexion temps réel doit viser collab.yourdomain.com, jamais oss-collab.excalidraw.com. Ce que Firebase reçoit est traité dans la section suivante.

Ce qui marche vraiment en auto-hébergement

Trois montages possibles, et ce que chacun laisse chez un tiers

• Montage A — salle seule (celui de ce guide). Vous changez VITE_APP_WS_SERVER_URL et rien d'autre. Le dessin en direct transite par votre serveur ; la scène enregistrée et les images des salles restent écrites dans le Firebase d'Excalidraw. Acceptable pour des tableaux peu sensibles, à ne pas présenter comme « rien chez un tiers ».
• Montage B — salle + votre propre projet Firebase. Vous créez un projet Firebase à vous et placez sa configuration JSON dans VITE_APP_FIREBASE_CONFIG. Le code ne lit que cette variable ; nous ne l'avons pas déployé de bout en bout, et Firebase reste un service de Google, pas de l'auto-hébergement au sens strict.
• Montage C — instance en solo. Vous servez l'interface seule, sans salle ni lien : chacun dessine, exporte en .excalidraw ou en image, et archive les fichiers chez vous. Rien ne part vers un tiers pour la collaboration, puisqu'il n'y en a pas.
• Ce qui n'existe pas côté officiel. Aucun serveur de stockage ouvert pour les liens #json=, ni une option qui bascule tout le périmètre vers votre domaine par une seule variable à l'exécution. Si votre exigence est « aucune donnée chez un tiers » avec collaboration et partage, la réponse honnête est un travail d'adaptation ou de fork, pas une installation.

Variable → fonction → ce qui casse sans elle

Faites défiler le tableau

Vérifier qui reçoit quoi

Dépannage : la collaboration ne démarre pas, ou ne se souvient de rien

Symptômes, causes, remèdes

• La session part vers oss-collab.excalidraw.com (onglet réseau) alors que vous avez construit votre image. Cause : l'adresse n'a pas été prise en compte à la construction (--build-arg sans effet, .env.production.local ignoré par le .dockerignore). Remède : éditer .env.production, reconstruire, rejouer la vérification grep de l'étape 2. Un changement de domaine suit la même règle.
• La connexion à la salle est refusée depuis le navigateur. Cause fréquente après avoir posé CORS_ORIGIN : l'origine ne correspond pas exactement à celle de la page (schéma http au lieu de https, port, slash final). Remède : la valeur doit être l'origine exacte de l'interface, par exemple https://draw.yourdomain.com.
• Les traits passent en direct, mais un participant qui rejoint plus tard, ou après un redémarrage de la salle, ne retrouve pas le contenu ou les images. Cause : la scène et les images sont enregistrées via Firebase, pas par excalidraw-room, qui ne retient rien. Si VITE_APP_FIREBASE_CONFIG est vide ou injoignable, rien n'est relu. Remède : choisir le montage A ou B ci-dessus.
• Avertissement Error JSON parsing firebase config. Supplied value: dans la console du navigateur. Cause : VITE_APP_FIREBASE_CONFIG n'est pas un JSON valide, le plus souvent à cause de guillemets mal protégés ou d'un retour à la ligne dans le fichier. Remède : JSON sur une seule ligne, entre apostrophes dans .env.production, comme dans le fichier amont.
• Le partage par lien échoue, ou le lien produit pointe vers json.excalidraw.com. Cause : VITE_APP_BACKEND_V2_POST_URL et VITE_APP_BACKEND_V2_GET_URL n'ont pas été changées, ou visent un serveur qui n'implémente pas l'API attendue. Remède : garder le défaut en connaissance de cause, ou échanger des fichiers .excalidraw.
• Erreur de chiffrement ou de génération de clé sur un réseau local en http://. Cause : l'API de chiffrement du navigateur (window.crypto) n'est exposée qu'en contexte sécurisé ; le fil amont signale ce piège pour l'auto-hébergement en réseau local. Remède : servir l'interface en HTTPS (ou sur localhost), comme l'exige le prérequis TLS plus haut.

Excalidraw auto-hébergé vs alternatives SaaS

Faites défiler le tableau

Aller plus loin : SSO et allowlist d'IP

allow 203.0.113.0/24;
allow 198.51.100.42;
deny all;

Intégration dans un parc self-hosted