Pular para conteúdo

Remover o Tailscale do ambiente local

Motivação

Ninguém mais usa o tailnet para desenvolver, e o make setup falhava por causa dele: o alvo local-serve era dependência do setup, e com o Tailscale parado na máquina o comando terminava em erro depois de instalar tudo certo. Uma dependência que só existe para publicar o ambiente num lugar que ninguém abre não paga o próprio custo.

Comportamento atual

O Caddy servia HTTP puro na :8080 e o tailscale serve publicava isso no tailnet com TLS, em https://oto.tail10981f.ts.net. Esse endereço estava cravado em 74 arquivos — como default do BASE_URL em 45 specs de e2e, no playwright.config, no APP_BASE_URL e no CORS_ORIGINS da API, nos três CLAUDE.md, nos READMEs, na documentação e no ADR-0003.

O HMR do Vite falava wss://<host do tailnet>:443, então por localhost a página carregava e não recarregava sozinha — o que o README da infra registrava como ressalva conhecida.

Comportamento desejado

O ambiente local é http://localhost:8080, e só. O HMR passa pelo mesmo proxy que serve a página (ws://localhost:8080), que o Caddy repassa sem configuração extra — então o hot reload funciona no caminho normal, que era o que a ressalva acima admitia não funcionar.

Os alvos local-serve e local-serve-off saíram, e o make setup deixou de depender deles.

Escopo

Os 74 arquivos que citavam o tailnet. As três menções que ficaram são deliberadas e históricas: o CLAUDE.md da raiz, o README da infra local e o ADR-0003 registram o que havia antes e por que saiu — apagar a memória faria a próxima pessoa reinventar a discussão.

Fora do escopo

O dev-remote e a produção não têm Tailscale e não foram tocados.

Alterações propostas

  • Makefile — local-serve e local-serve-off removidos; setup deixa de depender deles; local-url imprime o endereço fixo em vez de descobrir o nome no tailnet.
  • apps/web/vite.config.ts — HMR por ws://localhost:8080, allowedHosts local.
  • apps/api/app/core/config.py e .env.example — APP_BASE_URL e CORS_ORIGINS locais.
  • apps/e2e — o default de BASE_URL em 47 arquivos, mais o codegen e o .env.example.
  • infra/local/ — Caddyfile, compose e README.
  • Documentação — os três CLAUDE.md, os READMEs, docs/getting-started/setup.md, docs/api/index.md, docs/architecture/deployment.md e o ROADMAP.md.
  • ADR-0003 — corrigido, não apagado: a decisão que ele registra (origem única roteada por path) sobrevive; o que saiu foi a camada de TLS por cima dela.

Impactos

Perde-se alcançar a stack local de outro aparelho — celular ou tablet de verdade, sem instalar CA nenhuma. Era o que o tailnet dava de graça, e é a única coisa que sai junto. A conferência de mobile continua por emulação de largura, que é o que o e2e e os scripts de screenshot já fazem em 375px.

Não se perde nada técnico: localhost é origem segura para o browser, então service worker, PWA e clipboard seguem funcionando sem certificado.

Nada disto chega à produção: o que mudou é ambiente de desenvolvimento, documentação e defaults que todo ambiente real sobrescreve por .env.

Validação

  • make preflight limpo, incluindo a suíte unitária do apps/web.
  • npx tsc --noEmit no apps/web limpo.
  • make local-up e a página pelo proxy: http://localhost:8080/app/ responde 200, e o /mail também.
  • O hot reload foi conferido num browser de verdade, e não pelo arquivo de configuração: carregando a página pelo proxy, o console diz [vite] connecting... e [vite] connected., com o socket em ws://localhost:8080/app/. Antes, a mesma verificação dava ERR_NAME_NOT_RESOLVED no nome do tailnet — que é o defeito que o make setup acusou.