Alojar Excalidraw en un VPS: pizarra colaborativa sin suscripción

Por qué autoalojar Excalidraw en lugar de usar la versión pública

Beneficios concretos

• Cero suscripción de software — los dos componentes (interfaz y servidor de colaboración) son MIT. Pagas el VPS, nada más.
• Confidencialidad de los mockups — el dibujo en directo permanece en tu infraestructura. La escena guardada y las imágenes de una sala hay que tratarlas aparte (Firebase por defecto): consulta « Lo que funciona de verdad al autoalojar ».
• Acceso bajo tu control — allowlist de IP, SSO OIDC o HTTP Basic Auth delante de nginx según el nivel de aislamiento requerido.
• Sesiones y miembros ilimitados — sin límite por plan; el único límite es la RAM del servidor, y excalidraw-room es un servicio Node.js ligero.
• Persistencia opcional — monta un volumen Docker o conecta un bucket S3 compatible para archivar pizarras exportadas como JSON.
• Integración en un stack autoalojado — una instancia de Excalidraw junto a Penpot, Mattermost o Docmost cierra el perímetro SaaS de una agencia completa.

Arquitectura: dos contenedores, roles distintos

Requisitos previos

Lista de comprobación de requisitos

• Un VPS con al menos 1 vCPU y 512 MB de RAM (1 GB recomendado para un equipo).
• Docker Engine y Docker Compose Plugin instalados (docker compose version para verificar).
• Un nombre de dominio apuntando a la IP del VPS — sin TLS los WebSockets quedan bloqueados en los navegadores modernos.
• Acceso SSH root o un usuario con derechos sudo.
• Un certificado TLS válido — ServOrbit configura Let's Encrypt automáticamente.

Desplegar Excalidraw en 5 pasos

1. 01

   Crear el VPS e instalar Docker

   Aprovisiona un VPS Ubuntu 24.04 desde tu panel de ServOrbit. Una vez conectado por SSH, si Docker no está instalado aún, ejecuta:

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

   Verifica que Docker Compose Plugin responde antes de continuar:

   docker compose version

2. 02

   Construir la imagen con tu URL de colaboración

   Clona el repositorio oficial y fija la dirección de la sala en el archivo .env.production del repositorio antes de construir. Reemplaza collab.yourdomain.com con el subdominio que asignes a 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 .

   ¿Por qué no --build-arg? El Dockerfile de origen no declara ningún ARG para las variables VITE_APP_*: un --build-arg VITE_APP_WS_SERVER_URL=… nunca llega al comando de build, la imagen se construye con normalidad y sigue apuntando al servidor de Excalidraw. Además, el .dockerignore de origen solo admite .env.development y .env.production, así que un .env.production.local se ignoraría. La dirección queda grabada en el bundle, por lo que cambiar de dominio obliga a reconstruir.

   Comprueba el resultado: docker run --rm --entrypoint sh my-excalidraw:latest -c "grep -rl oss-collab.excalidraw.com /usr/share/nginx/html || echo limpio" debe mostrar limpio. La imagen oficial excalidraw/excalidraw sirve para pruebas locales, pero apunta a los servicios públicos de Excalidraw.

3. 03

   Escribir el archivo docker-compose.yml

   Crea un directorio de trabajo y escribe el siguiente archivo. Ambos servicios escuchan internamente; nginx (siguiente paso) es el único punto de entrada público:

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

   Contenido del 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:

   Arranca el stack:

   docker compose up -d

4. 04

   Configurar nginx con las cabeceras WebSocket

   Este es el paso donde fallan en silencio la mayoría de los despliegues: sin las cabeceras Upgrade y Connection, el navegador abre una conexión HTTP normal en lugar de un WebSocket, y la colaboración parece no funcionar sin ningún mensaje de error visible.

   Bloque nginx para el frontend de Excalidraw (draw.yourdomain.com):

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

   Bloque nginx para el servidor de sala (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;
       }
   }

   Recarga nginx (nginx -s reload) tras colocar los bloques.

5. 05

   Probar la colaboración en tiempo real

   Abre https://draw.yourdomain.com en dos pestañas o dos navegadores distintos. En la barra de herramientas, haz clic en Live collaboration y crea una sesión. Copia el enlace de sesión en la segunda pestaña.

   Dibuja algo en la primera pestaña: el trazo debe aparecer en la segunda en tiempo real. Si no aparece, revisa primero las cabeceras WebSocket en nginx (las herramientas de red del navegador muestran si la conexión ascendió a 101 Switching Protocols).

   Abre después la pestaña de red del navegador: la conexión en tiempo real debe apuntar a collab.yourdomain.com, nunca a oss-collab.excalidraw.com. Lo que recibe Firebase se trata en la sección siguiente.

Lo que funciona de verdad al autoalojar

Tres montajes posibles, y lo que cada uno deja en un tercero

• Montaje A — solo la sala (el de esta guía). Cambias VITE_APP_WS_SERVER_URL y nada más. El dibujo en directo transita por tu servidor; la escena guardada y las imágenes de las salas siguen escribiéndose en el Firebase de Excalidraw. Aceptable para pizarras poco sensibles, no para presentarlo como « nada en un tercero ».
• Montaje B — sala + tu propio proyecto Firebase. Creas un proyecto Firebase propio y pones su configuración JSON en VITE_APP_FIREBASE_CONFIG. El código solo lee esa variable; no lo hemos desplegado de punta a punta, y Firebase sigue siendo un servicio de Google, no autoalojamiento en sentido estricto.
• Montaje C — instancia en solitario. Sirves la interfaz sola, sin sala ni enlace: cada uno dibuja, exporta a .excalidraw o a imagen, y archiva los archivos en tu infraestructura. Nada sale hacia un tercero por colaboración, porque no la hay.
• Lo que no existe en el lado oficial. Ningún servidor de almacenamiento abierto para los enlaces #json=, ni una opción que traslade todo el perímetro a tu dominio con una sola variable en ejecución. Si tu requisito es « ningún dato en un tercero » con colaboración y enlaces, la respuesta honesta es un trabajo de adaptación o de fork, no una instalación.

Variable → función → qué se rompe sin ella

Desplace la tabla

Comprobar quién recibe qué

Solución de problemas: la colaboración no arranca, o no recuerda nada

Síntomas, causas, remedios

• La sesión va a oss-collab.excalidraw.com (pestaña de red) aunque construiste tu imagen. Causa: la dirección no se tuvo en cuenta al construir (--build-arg sin efecto, .env.production.local ignorado por el .dockerignore). Remedio: editar .env.production, reconstruir y repetir la comprobación grep del paso 2. Un cambio de dominio sigue la misma regla.
• El navegador ve rechazada la conexión con la sala. Causa frecuente tras fijar CORS_ORIGIN: el origen no coincide exactamente con el de la página (esquema http en lugar de https, puerto, barra final). Remedio: el valor debe ser el origen exacto de la interfaz, por ejemplo https://draw.yourdomain.com.
• Los trazos aparecen en directo, pero un participante que se une más tarde, o tras un reinicio de la sala, no recupera el contenido ni las imágenes. Causa: la escena y las imágenes se guardan a través de Firebase, no por excalidraw-room, que no retiene nada. Si VITE_APP_FIREBASE_CONFIG está vacía o inalcanzable, nada se relee. Remedio: elegir el montaje A o B de arriba.
• Aviso Error JSON parsing firebase config. Supplied value: en la consola del navegador. Causa: VITE_APP_FIREBASE_CONFIG no es un JSON válido, casi siempre por comillas mal protegidas o un salto de línea en el archivo. Remedio: JSON en una sola línea, entre comillas simples en .env.production, como en el archivo de origen.
• Compartir por enlace falla, o el enlace generado apunta a json.excalidraw.com. Causa: VITE_APP_BACKEND_V2_POST_URL y VITE_APP_BACKEND_V2_GET_URL no se cambiaron, o apuntan a un servidor que no implementa la API esperada. Remedio: conservar el valor por defecto con conocimiento de causa, o intercambiar archivos .excalidraw.
• Error de cifrado o de generación de clave en una red local con http://. Causa: la API de cifrado del navegador (window.crypto) solo se expone en un contexto seguro; el hilo de origen señala esta trampa para el autoalojamiento en red local. Remedio: servir la interfaz en HTTPS (o en localhost), como exige el requisito TLS de arriba.

Excalidraw autoalojado vs alternativas SaaS

Desplace la tabla

Más allá: SSO y listas de IPs permitidas

allow 203.0.113.0/24;
allow 198.51.100.42;
deny all;

Integración en un stack autoalojado