Como implantar um aplicativo tldraw em uma VPS

Pré-requisitos

• VPS Ubuntu 22.04 ou 24.04 com acesso SSH
• Um nome de domínio (por exemplo, canvas.example.com) apontando para o IP do servidor
• Docker e Docker Compose instalados na VPS
• Node.js 20+ e npm na sua máquina local ou no CI
• Conhecimentos básicos de React e linha de comando

Avisos importantes

• O tldraw é um SDK, não um aplicativo de servidor. Você implanta o aplicativo que criou com ele.
• Por padrão, o aplicativo auto-hospedado oferece um editor para uma única pessoa. O estado é perdido ao atualizar a página, a menos que você adicione persistência.
• A colaboração em tempo real exige o serviço @tldraw/sync. O destino recomendado para a implantação é o Cloudflare Workers, não uma VPS.
• O uso do tldraw em produção exige uma chave de licença de tldraw.dev. Confira a licença do SDK antes de publicar.
• O SDK não segue versionamento semântico. Se usar @tldraw/sync, as versões dos pacotes tldraw e @tldraw/sync precisam ser exatamente iguais.

Etapa 1: conectar-se e preparar o servidor

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

Instale o 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

Etapa 2: criar um aplicativo tldraw

Na sua máquina local ou no CI, crie um novo projeto React com Vite:

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

Abra src/App.jsx e substitua o conteúdo pelo editor tldraw mínimo:

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

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

Teste o aplicativo localmente:

npm run dev

Abra http://localhost:5173 no navegador. Você deverá ver uma tela em branco com a barra de ferramentas do tldraw.

Gere os arquivos estáticos para produção:

npm run build

A saída fica na pasta dist/.

Etapa 3: colocar o aplicativo em um contêiner Docker

Crie um Dockerfile na raiz do projeto:

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;"]

Crie o arquivo nginx.conf para o roteamento de aplicativo de página única:

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

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

Atualize o Dockerfile para usar essa configuração do Nginx:

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;"]

Etapa 4: executar com Docker Compose

Crie um arquivo docker-compose.yml:

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

Compile a imagem e inicie o contêiner:

docker compose build
docker compose up -d
docker compose ps

O aplicativo agora está em execução em 127.0.0.1:3000 e só pode ser acessado pelo próprio servidor.

Etapa 5: configurar o proxy reverso

Instale o Nginx na VPS:

apt install -y nginx

Crie uma configuração de site do Nginx em /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;
    }
}

Ative o site:

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

Configure o HTTPS com Certbot:

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

Etapa 6: primeiro acesso

Abra https://canvas.example.com no navegador. Você deverá ver o editor tldraw.

• Desenhe uma forma e atualize a página. O desenho será perdido porque não há serviço de persistência.
• Abra o console de desenvolvimento do navegador. Você não deverá ver erros de rede.

Este é um editor para uma única pessoa. Todo o estado fica na aba do navegador.

Manutenção

• Atualizar o tldraw: Execute npm install tldraw@latest, gere novamente a imagem Docker (docker compose build) e reinicie o contêiner (docker compose up -d).
• Atualizar pacotes npm: Execute npm outdated e npm update periodicamente, depois recompile o aplicativo.
• Compilar no servidor: Clone seu repositório na VPS e execute docker compose build && docker compose up -d para implantar novas versões.
• Backups: Como esta configuração não persiste dados, não há banco de dados para incluir nos backups. Se adicionar persistência, faça backup do banco de dados e dos recursos enviados.
• Monitoramento: Confira docker compose logs para ver erros do contêiner e os logs de acesso e erro do Nginx em /var/log/nginx/.

Observações importantes

• Não é necessária uma atualização WebSocket para o editor estático. A sincronização por WebSocket só é necessária quando você adiciona @tldraw/sync, que é executado no Cloudflare Workers, não nesta VPS.
• Este guia produz uma demonstração para uma única pessoa. Contas, armazenamento de documentos e colaboração em tempo real são questões separadas que exigem infraestrutura adicional.
• Por padrão, o tldraw carrega fontes e ícones do CDN. Para implantações isoladas de redes externas, você pode hospedar esses recursos por conta própria.
• O SDK não segue o versionamento semântico. Ao atualizar, confira sempre o registro de alterações do tldraw para identificar mudanças incompatíveis e, se usar ambos, confirme que as versões de tldraw e @tldraw/sync são iguais.