NodaroAccount
Docs do Nodaro
DocumentaçãoReferência de nósModelosTemplatesAgentes de IA (MCP)DesenvolvedoresAuto-hospedagemPesquisaComparações

Proxy reverso e HTTPS

Sirva o Nodaro auto-hospedado no seu domínio por HTTPS, com nginx ou Caddy na frente da porta 3000, defina PUBLIC_URL e CORS_ORIGIN e reinicie o app.

Um proxy reverso coloca o seu Nodaro auto-hospedado em um domínio real, com HTTPS. O contêiner do Nodaro já roda um servidor web, o Caddy, na porta 3000, então você adiciona um proxy que faz a terminação TLS na frente dessa porta e informa ao Nodaro o endereço público dele. Tanto o nginx quanto o Caddy funcionam.

O que a porta 3000 serve

O servidor web dentro do contêiner coloca tudo em uma única origem:

CaminhoO que responde
/O editor e os apps, como arquivos estáticos
/v1/*A API, que escuta na porta 9000 dentro do contêiner
/healthO endereço de saúde do contêiner, respondido pela API
/storage/*A mídia no MinIO incluído
/supabase/*O login e a API de dados incluídos
/config.jsAs configurações de tempo de execução que o navegador lê antes de o app iniciar

O seu proxy só precisa encaminhar todas as requisições para a porta 3000.

O endereço de saúde

GET /health na porta 3000 é o endereço de saúde do contêiner. Quem responde é a API, nunca a página do app:

A API está/health responde
No ar200 com {"status":"healthy","timestamp":…,"version":…}
Fora do ar, ou reiniciando502. A API reinicia dentro do contêiner 10 segundos depois de sair.
Travada: aceita a conexão e não responde504, depois de 5 segundos

Uma barra no final, outra combinação de maiúsculas e minúsculas e as outras grafias do endereço leem o mesmo status. Um caminho abaixo dele, como /health/x, não é o endereço e nunca é lido como saudável. Toda resposta traz Cache-Control: no-store, então nenhum cache na frente da instalação guarda um “healthy”. Nada responde na porta 3000 até a API ficar pronta: enquanto as migrações rodam, e depois por até 30 segundos enquanto o servidor web espera pela API.

A verificação de saúde do arquivo compose incluído lê esse endereço. O contêiner nodaro fica saudável quando a API responde pela primeira vez, e não saudável depois de cinco leituras com falha seguidas. O Docker não reinicia um contêiner por ele estar não saudável. Aponte qualquer outra verificação de saúde ou monitor de disponibilidade para esse endereço também, com um limite de tempo próprio.

A verificação de saúde de uma implantação precisa ler a porta 3000. Algumas plataformas de hospedagem, entre elas o Railway, testam a porta que entregam ao contêiner em PORT. A imagem escuta na porta 3000, seja o que for que PORT diga, então toda implantação falha na verificação enquanto a anterior continua servindo. Numa plataforma assim, defina a variável de serviço PORT=3000. Nada mais muda na imagem: a API continua escutando na porta 9000 atrás do servidor web.

Opção A: nginx

Use esta opção quando você já roda o nginx ou outro proxy.

server {
  listen 443 ssl http2;
  server_name nodaro.example.com;
  ssl_certificate     /etc/letsencrypt/live/nodaro.example.com/fullchain.pem;
  ssl_certificate_key /etc/letsencrypt/live/nodaro.example.com/privkey.pem;

  client_max_body_size 100M;
  proxy_buffering off;          # important for SSE

  location / {
    proxy_pass http://127.0.0.1:3000;
    proxy_http_version 1.1;
    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;
  }
}
  • client_max_body_size 100M deixa os uploads passarem.
  • proxy_buffering off mantém os Server-Sent Events fluindo. O Nodaro transmite com eles a saída de texto e o progresso das execuções.

Opção B: Caddy no host

O Caddy obtém um certificado Let's Encrypt para você:

nodaro.example.com {
  reverse_proxy 127.0.0.1:3000 {
    flush_interval -1
  }
}

Abra as portas 80 e 443 e aponte os registros A ou AAAA do domínio para o host. flush_interval -1 mantém os Server-Sent Events fluindo.

Informar ao Nodaro o endereço público

Depois de qualquer uma das opções, defina estas variáveis no .env:

PUBLIC_URL=https://nodaro.example.com
CORS_ORIGIN=https://nodaro.example.com
# On the bundled MinIO, serve the media from the same domain:
R2_PUBLIC_URL=https://nodaro.example.com/storage/nodaro-assets

Depois, aplique-as:

docker compose -f docker-compose.community.yml up -d

Não é preciso recompilar. Na inicialização, o contêiner grava a URL pública, o endereço de login do navegador e a chave anon em /config.js, e o navegador lê esse arquivo antes de o app iniciar.

PUBLIC_URL é o endereço da instalação em todos os lugares: nos callbacks de login e de OAuth, nas URLs de mídia e na verificação de CORS. http://localhost:3000 e PUBLIC_URL são sempre permitidos como origens do navegador.

Servir mais de um nome de host

  • Origens extras. Liste-as em CORS_ORIGIN, separadas por vírgula, por exemplo CORS_ORIGIN=https://nodaro.example.com,http://192.168.1.20:3000.
  • Transmissões no nome de host do visitante. Quando a API compartilha a origem do app, como no contêiner padrão, defina PUBLIC_URL_SAME_ORIGIN=true. O /config.js passa, então, ao navegador o endereço de API / em vez de PUBLIC_URL, de modo que as transmissões ficam no nome de host que o visitante abriu. Só o valor exato true ativa esse comportamento. Deixe a variável sem definir quando a API realmente fica em outro host.

O arquivo do Compose não repassa PUBLIC_URL_SAME_ORIGIN do .env. Adicione-a em environment: do serviço nodaro. Veja Configuração.

Mover as páginas do app para um nome de host próprio

Uma instalação pode responder em um segundo nome de host para as páginas do app. O nome de host original mantém a API, o login e o OAuth, os apps publicados, as incorporações e as apresentações compartilhadas. Os dois nomes de host apontam para o mesmo serviço. FLOW_UI_ORIGIN indica o novo nome de host, e PUBLIC_URL é a origem https do nome de host que você mantém. Funciona em duas etapas:

# Step 1, the pages' own hostname: every hostname keeps serving every page.
FLOW_UI_ORIGIN=https://flow.example.com

# Step 2, the move: the hostnames listed here send the app's pages to it.
LEGACY_UI_HOSTS=app.example.com

Só com FLOW_UI_ORIGIN, as páginas ganham um nome de host próprio, mas nada se muda:

  • Nada é redirecionado. Todos os nomes de host continuam servindo todas as páginas. Os links que o Nodaro escreve, os endereços entregues às pessoas e as chamadas de API das páginas continuam como eram.
  • As configurações salvas no navegador são copiadas uma vez, na primeira visita ao novo nome de host.
  • Um endereço canônico por página pública. Cada página que os buscadores podem indexar indica o seu endereço com um link canônico, em todo nome de host que a serve. A tela inicial, /gallery e /tutorials/... indicam FLOW_UI_ORIGIN. /login, /signup e os apps publicados (/app/...) indicam PUBLIC_URL.
  • O log de inicialização indica o novo nome de host e diz que nenhum nome de host redireciona para ele. Um LEGACY_UI_HOSTS com erro de digitação aparece ali.

Com LEGACY_UI_HOSTS também, a mudança fica ativa:

  • O que é movido. Em um nome de host listado em LEGACY_UI_HOSTS, uma visita a uma das páginas do app é redirecionada para o mesmo caminho e a mesma consulta em FLOW_UI_ORIGIN. Entre as páginas movidas estão a tela inicial, o editor, os projetos, as configurações, a galeria, a biblioteca, os apps e os templates. Liste vários nomes de host separados por vírgulas ou espaços, com qualquer combinação de maiúsculas e minúsculas.
  • O que fica. A API, o OAuth e o login, os apps publicados (/app/...), as incorporações, as apresentações compartilhadas, todos os arquivos e os caminhos desconhecidos nunca são redirecionados. Uma página carregada dentro de um frame também nunca é redirecionada.
  • Um só endereço para as páginas públicas. No novo nome de host, uma visita a /app/..., /embed/... ou /present/... é enviada de volta para PUBLIC_URL.
  • Links. Os links que o Nodaro escreve para as páginas do app indicam o novo nome de host. A API, o emissor do OAuth e os endereços que você entrega a outras pessoas ficam em PUBLIC_URL: apps publicados, incorporações, apresentações compartilhadas, URLs de webhook e os exemplos de API da página de configurações.
  • Status do redirecionamento. 302 por padrão, nunca guardado em cache. LEGACY_UI_REDIRECT_STATUS=301 envia um 301 que o navegador guarda por uma hora.
  • Os links canônicos continuam como na etapa 1.

Nas duas etapas:

  • Contas de redes sociais. Uma conta de rede social conectada a partir de qualquer um dos dois nomes de host informa o resultado à página que iniciou a conexão. O pop-up de conexão termina em PUBLIC_URL, e essa página envia o resultado para os dois nomes de host. Cada nome de host recebe o resultado só nas próprias páginas.
  • Configurações salvas no navegador. Na primeira visita ao novo nome de host, as configurações salvas no navegador são copiadas uma vez do nome de host original. Só as configurações que o novo nome de host ainda não tem são gravadas, e nunca uma sessão de login. Uma configuração alterada depois no nome de host original fica lá. Os dois nomes de host precisam estar no mesmo site, como app.example.com e flow.example.com: entre sites diferentes, a cópia não encontra nada para trazer.
  • Verificações rígidas. FLOW_UI_ORIGIN e PUBLIC_URL são duas origens https diferentes, sem caminho nem porta. Com uma configuração inválida, a API se recusa a iniciar e indica a configuração. Isso acontece quando LEGACY_UI_HOSTS é definida sem FLOW_UI_ORIGIN, ou quando um valor não é uma origem https. Também acontece quando LEGACY_UI_HOSTS indica só o novo nome de host, ou tem uma entrada que não é um nome de host simples.
  • Outros nomes de host. Os nomes de host que não estão em nenhuma das duas configurações não são afetados.

FLOW_PUBLIC_URL é outro nome de FLOW_UI_ORIGIN. O arquivo do Compose não repassa essas variáveis do .env, então adicione-as em environment: do serviço nodaro e reinicie. Não é preciso recompilar.

Mudar a porta

Para servir o app em outra porta do host, mude o lado do host do mapeamento no docker-compose.community.yml, por exemplo "3001:3000". Depois, defina PUBLIC_URL de acordo, como http://localhost:3001.

Como os endereços dos clientes são registrados

O servidor web do contêiner só aceita cabeçalhos X-Forwarded-* de proxies em endereços privados: 127.0.0.1/8, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, fd00::/8 e ::1.

  • Vindo de um proxy confiável, ele reduz o X-Forwarded-For a um único endereço de cliente: a entrada mais à direita que não seja, ela própria, um proxy confiável. Um endereço que um cliente escreveu no cabeçalho é ignorado.
  • Vindo de um proxy em um endereço público, ele substitui esses cabeçalhos pelos valores que ele mesmo observou.

Em uma intranet, a mesma regra ignora os endereços dos próprios usuários quando eles também são privados. Um cliente na LAN pode, então, escolher o endereço que a API registra, por exemplo para os limites de taxa.

Os editores incorporados no seu domínio

Editar no NodarCut, ou Editar em um resultado de vídeo de um app, abre o editor de vídeo hospedado em freecut.nodaro.ai, que só permite ser incorporado a partir de http://localhost:3000. Em qualquer outra origem, como um domínio ou um endereço da LAN, o navegador se recusa a incorporá-lo, e o painel explica o motivo. Abra um chamado no GitHub com a URL que você serve ou rode o seu próprio editor e defina FREECUT_URL. Veja Configuração.

O MCP precisa de um nome de host próprio

Os clientes MCP precisam alcançar a API na porta 9000 diretamente: o servidor web na porta 3000 recusa requisições MCP. Veja MCP.

Servir outros apps no mesmo host

O servidor web do contêiner também lê todo arquivo *.caddy de /etc/caddy/sites.d/ como parte do seu único site. Para servir outro app web ao lado do editor no mesmo host, crie uma imagem a partir da imagem do Nodaro e adicione as rotas do app nesse diretório. Você não edita a configuração embutida.

FROM ghcr.io/nodaroai/nodaro-community:latest
COPY --from=<other app's build> /dist /srv/other-app
COPY other-app.caddy /etc/caddy/sites.d/other-app.caddy
# /etc/caddy/sites.d/other-app.caddy
@other_app path /other /other/*
handle @other_app {
	root * /srv/other-app
	encode zstd gzip
	try_files {path} /index.html
	file_server
}
  • Diretivas, não sites. Um arquivo traz diretivas do site existente, como handle ou redir, nunca um bloco de site próprio. O Caddy ordena os blocos handle pelos caminhos, então uma rota desse diretório responde antes da rota genérica do próprio editor.
  • Caminhos que não se sobrepõem. Evite os caminhos do editor: /v1/*, /supabase/*, /storage/*, /.well-known/*, /config.js, /assets/* e as páginas do próprio editor. Mantenha também os arquivos de cada app sob o caminho dele.
  • Correspondência exata. Indique o caminho exato e também com /*, como em /other /other/*. Um prefixo solto como /other* também pegaria /other-thing.
  • Nenhum arquivo é o padrão. O diretório não precisa existir. Sem ele, o site não muda, e o Caddy registra na partida um aviso esperado: No files matching import glob pattern.
  • Confira o arquivo antes da implantação. Um arquivo que o Caddy não consegue interpretar impede o Caddy de iniciar, e então nada responde na porta 3000. Confira a imagem com a camada nova usando caddy validate --config /etc/caddy/Caddyfile --adapter caddyfile.

Depois de um login, um caminho de um app desses é carregado por inteiro, para que o app responda em vez do editor. Veja Login único (SSO).

Perguntas frequentes

O contêiner do Nodaro já inclui um servidor web?

Sim. O contêiner roda o Caddy na porta 3000. Ele serve o editor, encaminha /v1 para a API na porta 9000 e serve a mídia e o login incluído na mesma origem. Para HTTPS, coloque na frente da porta 3000 um proxy que faça a terminação TLS.

O que preciso mudar depois de colocar o Nodaro atrás de um domínio?

Defina PUBLIC_URL e CORS_ORIGIN com o seu endereço https e, no MinIO incluído, defina R2_PUBLIC_URL como https://your-domain/storage/nodaro-assets. Depois, rode docker compose up -d. Não é preciso recompilar.

Por que o meu proxy nginx quebra a saída em transmissão contínua?

Por padrão, o nginx armazena as respostas em buffer, o que retém os Server-Sent Events. Defina proxy_buffering off. Com o Caddy no host, defina flush_interval -1 no bloco reverse_proxy.

O Nodaro pode responder em mais de um nome de host?

Sim. Liste as origens extras em CORS_ORIGIN, separadas por vírgula. Se a API compartilha a origem do app, como no contêiner padrão, defina também PUBLIC_URL_SAME_ORIGIN=true para que as transmissões fiquem no nome de host que o visitante usa.

Última atualização

Nesta página