Cómo desplegar una app tldraw en un VPS

Requisitos previos

• VPS con Ubuntu 22.04 o 24.04 y acceso SSH
• Un dominio (ej. canvas.example.com) apuntando a la IP de tu servidor
• Docker y Docker Compose instalados en el VPS
• Node.js 20+ y npm en tu máquina local o CI
• Conocimientos básicos de React y línea de comandos

Avisos importantes

• tldraw es un SDK, no una aplicación servidor. Tú despliegas la app que tú construyes con él.
• La app autoalojada sirve un editor de un solo usuario. El estado se pierde al recargar la página a menos que añadas persistencia.
• La colaboración en tiempo real requiere el backend @tldraw/sync. El destino recomendado es Cloudflare Workers, no un VPS.
• El uso en producción de tldraw requiere una clave de licencia de tldraw.dev. Revisa la licencia del SDK antes de publicar.
• El SDK no sigue versionado semántico. Si usas @tldraw/sync, las versiones de tldraw y @tldraw/sync deben coincidir exactamente.

Paso 1: Conectar y preparar el servidor

ssh root@TU_IP_DEL_SERVIDOR
apt update && apt upgrade -y
apt install -y curl git

Instala Node.js 20.x (LTS):

curl -fsSL https://deb.nodesource.com/setup_20.x | bash -
apt install -y nodejs
node --version   # v20.x
npm --version

Paso 2: Crear una app tldraw

En tu máquina local o CI, crea un proyecto React con Vite:

npm create vite@latest tldraw-canvas -- --template react
cd tldraw-canvas
npm install tldraw

Abre src/App.jsx y reemplaza su contenido con el editor mínimo:

import { Tldraw } from "tldraw";
import "tldraw/tldraw.css";

export default function App() {
  return (
    <div style={{ position: "fixed", inset: 0 }}>
      <Tldraw />
    </div>
  );
}

Prueba la app localmente:

npm run dev

Abre http://localhost:5173 en el navegador. Deberías ver un lienzo en blanco con la barra de herramientas de tldraw.

Compila los assets estáticos para producción:

npm run build

La salida se genera en la carpeta dist/.

Paso 3: Contenerizar la app

Crea un Dockerfile en la raíz del proyecto:

FROM node:20-alpine AS builder
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM nginx:alpine
COPY --from=builder /app/dist /usr/share/nginx/html
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

Crea un archivo nginx.conf para el enrutamiento de SPA:

server {
    listen 80;
    root /usr/share/nginx/html;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }
}

Actualiza el Dockerfile para usar esta configuración:

FROM node:20-alpine AS builder
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM nginx:alpine
COPY --from=builder /app/dist /usr/share/nginx/html
COPY nginx.conf /etc/nginx/conf.d/default.conf
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

Paso 4: Ejecutar con Docker Compose

Crea un docker-compose.yml:

services:
  canvas:
    build: .
    restart: unless-stopped
    ports:
      - "127.0.0.1:3000:80"

Construye e inicia el contenedor:

docker compose build
docker compose up -d
docker compose ps

La app ahora corre en 127.0.0.1:3000 y solo es accesible desde el propio servidor.

Paso 5: Configurar el proxy inverso

Instala Nginx en el VPS:

apt install -y nginx

Crea un archivo de configuración en /etc/nginx/sites-available/canvas:

server {
    listen 80;
    server_name canvas.example.com;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Habilita el sitio:

ln -s /etc/nginx/sites-available/canvas /etc/nginx/sites-enabled/
nginx -t
systemctl reload nginx

Configura HTTPS con Certbot:

apt install -y certbot python3-certbot-nginx
certbot --nginx -d canvas.example.com

Paso 6: Primer acceso

Abre https://canvas.example.com en tu navegador. Deberías ver el editor de tldraw.

• Dibuja una forma y recarga la página. El dibujo se perderá porque no hay backend de persistencia.
• Abre la consola de desarrollador del navegador. No deberías ver errores de red.

Este es un editor de un solo usuario. Todo el estado vive en la pestaña del navegador.

Mantenimiento

• Actualizar tldraw: Ejecuta npm install tldraw@latest, reconstruye la imagen Docker (docker compose build) y reinicia el contenedor (docker compose up -d).
• Actualizar paquetes npm: Revisa periódicamente con npm outdated y npm update, luego reconstruye.
• Reconstruir en el servidor: Clona tu repositorio en el VPS y ejecuta docker compose build && docker compose up -d para desplegar nuevas versiones.
• Respaldos: Como esta configuración no persiste datos, no hay base de datos que respaldar. Si añades persistencia, respalda la base de datos y los archivos subidos.
• Monitoreo: Revisa docker compose logs para errores del contenedor y los logs de Nginx en /var/log/nginx/.

Notas clave

• No se necesita actualización WebSocket para el editor estático. La sincronización WebSocket solo es necesaria cuando añades @tldraw/sync, que se ejecuta en Cloudflare Workers, no en este VPS.
• Esta guía produce una demo de un solo usuario. Añadir cuentas, almacenamiento de documentos y colaboración en tiempo real son tareas separadas que requieren infraestructura adicional.
• tldraw carga fuentes e íconos desde su CDN por defecto. Para despliegues sin conexión a Internet, puedes autoalojar estos assets.
• El SDK no sigue semver. Al actualizar, revisa siempre el changelog de tldraw para cambios incompatibles y asegúrate de que las versiones de tldraw y @tldraw/sync coincidan si usas ambos.