OmniRoute Fly.io Deployment Guide (Português (Brasil))

1. Objetivos da Implantação

• Plataforma: Fly.io
• Método de implantação: publicação direta local usando flyctl
• Ambiente de execução: uso dos arquivos Dockerfile e fly.toml existentes no repositório
• Persistência de dados: Fly Volume montado em /data
• URL de acesso: https://omniroute.fly.dev/

---

2. Configuração Principal do Projeto Atual

Foi confirmado que o arquivo fly.toml no repositório atual contém os seguintes itens principais:

app = 'omniroute'
primary_region = 'sin'

[[mounts]]
  source = 'data'
  destination = '/data'

[processes]
  app = 'node run-standalone.mjs'

[http_service]
  internal_port = 20128

[env]
  TZ = "Asia/Shanghai"
  HOST = "0.0.0.0"
  HOSTNAME = "0.0.0.0"
  BIND = "0.0.0.0"

Observações:

• app = 'omniroute' determina a aplicação Fly à qual a implantação se destina
• destination = '/data' determina o diretório de montagem do volume persistente
• Este projeto deve definir DATA_DIR=/data; caso contrário, o banco de dados e as chaves serão gravados no diretório temporário do contêiner

---

3. Pré-requisitos

3.1 Instalando a CLI do Fly

Windows PowerShell:

pwsh -Command "iwr https://fly.io/install.ps1 -useb | iex"

Se o script de instalação falhar em seu ambiente, você também poderá baixar manualmente o binário flyctl e adicioná-lo ao seu PATH.

3.2 Fazendo Login em Sua Conta Fly

flyctl auth login

3.3 Verificando o Status do Login

flyctl auth whoami
flyctl version

---

4. Primeira Implantação do Projeto Atual

4.1 Clone o Código e Acesse o Diretório

git clone https://github.com/diegosouzapw/OmniRoute.git
cd OmniRoute

4.2 Confirme o Nome da Aplicação

Abra o arquivo fly.toml e verifique a seguinte linha:

app = 'omniroute'

Se estiver implantando em sua própria aplicação nova, você poderá alterá-lo para um nome globalmente exclusivo, por exemplo:

app = 'omniroute-yourname'

Observação:

• Certifique-se de que a aplicação exibida no console corresponda ao valor de app no arquivo fly.toml
• Se você usou anteriormente um nome diferente, como oroute, não o confunda com omniroute

4.3 Crie a Aplicação

Se a aplicação ainda não existir:

flyctl apps create omniroute

Se você alterou o nome da aplicação, substitua omniroute pelo nome escolhido.

4.4 Primeira Implantação

flyctl deploy

---

5. Parâmetros Obrigatórios

Este projeto recomenda configurar pelo menos os seguintes parâmetros no Fly.io.

5.1 Parâmetros Verificados

Estes parâmetros foram usados em implantações reais na aplicação omniroute atual:

• API_KEY_SECRET
• DATA_DIR
• JWT_SECRET
• MACHINE_ID_SALT
• NEXT_PUBLIC_BASE_URL
• OMNIROUTE_WS_BRIDGE_SECRET (obrigatório em produção — usado para autenticação da ponte WebSocket)
• STORAGE_ENCRYPTION_KEY

5.2 Sobre INITIAL_PASSWORD

O projeto atual não define INITIAL_PASSWORD, pois esta implantação não exige esse parâmetro.

Se ele não estiver definido:

• O log de inicialização indicará que a senha padrão é CHANGEME
• Você deve alterar a senha de login nas configurações do sistema assim que possível após a implantação

Se quiser inicializar a senha do backend sem intervenção, você poderá adicioná-la posteriormente:

• INITIAL_PASSWORD

---

6. Parâmetros recomendados

6.1 Configuração de segredos

As variáveis a seguir são recomendadas para o Fly Secrets:

Variável	Recomendação	Descrição
API_KEY_SECRET	Obrigatória	Usada para geração e validação de chaves de API
JWT_SECRET	Obrigatória	Usada para sessões de login e assinatura de JWTs
OMNIROUTE_WS_BRIDGE_SECRET	Obrigatória em produção	Segredo de autenticação da ponte WebSocket
STORAGE_ENCRYPTION_KEY	Altamente recomendada	Criptografa informações confidenciais de conexão em repouso
MACHINE_ID_SALT	Recomendada	Gera um identificador de máquina estável
INITIAL_PASSWORD	Opcional	Define a senha inicial do backend na primeira implantação
Credenciais privadas OAuth/API	Conforme necessário	Configuração de autenticação em plataformas externas

6.2 Valores recomendados para o projeto atual

Variável	Valor recomendado
DATA_DIR	/data
NEXT_PUBLIC_BASE_URL	https://omniroute.fly.dev

Observações:

• DATA_DIR=/data é essencial e deve corresponder ao ponto de montagem do Fly Volume
• NEXT_PUBLIC_BASE_URL é usada pelo agendador, pelos callbacks do frontend e em cenários semelhantes

6.3 Configuração da URL de callback do OAuth

Se você precisar habilitar provedores baseados em OAuth (por exemplo, Antigravity, Gemini, Cursor) na implantação do Fly.io, certifique-se dos dois pontos a seguir:

1. Defina NEXT_PUBLIC_BASE_URL como seu domínio HTTPS público

   flyctl secrets set NEXT_PUBLIC_BASE_URL=https://omniroute.fly.dev -a omniroute

   Se você estiver usando um domínio personalizado, substitua-o pelo domínio correspondente (por exemplo, https://omniroute.yourdomain.com).

2. Configure a URL de callback no console do provedor

   Todos os provedores OAuth compartilham o mesmo caminho de callback /callback — NÃO há uma rota de callback específica para cada provedor:

   <NEXT_PUBLIC_BASE_URL>/callback

   Por exemplo, seja para Gemini, Antigravity, Cursor ou GitLab Duo:

   • https://omniroute.fly.dev/callback

   Se NEXT_PUBLIC_BASE_URL não corresponder à URL de callback registrada no provedor, o fluxo OAuth falhará na etapa de redirecionamento do navegador.

---

7. Configuração de segredos com um único comando

Os comandos a seguir geram valores aleatórios seguros e gravam todos os parâmetros necessários para o projeto atual no Fly Secrets em uma única etapa.

Observações:

• Não inclui INITIAL_PASSWORD
• Destinado ao projeto atual omniroute

$apiKeySecret = [Convert]::ToHexString((1..32 | ForEach-Object { Get-Random -Minimum 0 -Maximum 256 })).ToLower()
$jwtSecret = [Convert]::ToHexString((1..64 | ForEach-Object { Get-Random -Minimum 0 -Maximum 256 })).ToLower()
$machineIdSalt = [Convert]::ToHexString((1..32 | ForEach-Object { Get-Random -Minimum 0 -Maximum 256 })).ToLower()
$storageKey = [Convert]::ToHexString((1..32 | ForEach-Object { Get-Random -Minimum 0 -Maximum 256 })).ToLower()
$wsBridgeSecret = [Convert]::ToHexString((1..32 | ForEach-Object { Get-Random -Minimum 0 -Maximum 256 })).ToLower()

flyctl secrets set `
  API_KEY_SECRET=$apiKeySecret `
  JWT_SECRET=$jwtSecret `
  MACHINE_ID_SALT=$machineIdSalt `
  STORAGE_ENCRYPTION_KEY=$storageKey `
  OMNIROUTE_WS_BRIDGE_SECRET=$wsBridgeSecret `
  DATA_DIR=/data `
  NEXT_PUBLIC_BASE_URL=https://omniroute.fly.dev `
  -a omniroute

No Linux/macOS, você também pode usar openssl rand -hex 32:

flyctl secrets set OMNIROUTE_WS_BRIDGE_SECRET=$(openssl rand -hex 32) -a omniroute

Observações:

• OMNIROUTE_WS_BRIDGE_SECRET é obrigatória em produção; sua ausência interromperá o handshake da ponte WebSocket

Se você também quiser definir uma senha inicial:

flyctl secrets set INITIAL_PASSWORD=your-strong-password -a omniroute

---

8. Visualizando os parâmetros atuais

flyctl secrets list -a omniroute

Se a página Secrets no console não exibir as variáveis esperadas, verifique:

• Se você está visualizando a aplicação omniroute
• Se o valor de app em fly.toml corresponde à aplicação no console

---

9. Atualizações e lançamentos subsequentes

Após atualizações no código, o processo de lançamento é simples:

git pull
flyctl deploy

Se você precisar apenas atualizar parâmetros sem alterar o código:

flyctl secrets set KEY=value -a omniroute

A Fly realizará automaticamente uma atualização gradual das máquinas.

9.1 Acompanhando atualizações do repositório upstream enquanto preserva o fly.toml do seu fork

Se o repositório atual for um fork e você quiser sincronizar atualizações do upstream https://github.com/diegosouzapw/OmniRoute, siga o fluxo de trabalho abaixo.

Primeiro, verifique seus remotos:

git remote -v

Você deve ver pelo menos:

• origin apontando para o seu próprio fork
• upstream apontando para o repositório original

Se upstream não estiver configurado, adicione-o:

git remote add upstream https://github.com/diegosouzapw/OmniRoute.git

Antes de sincronizar com o upstream, busque os commits e as tags mais recentes:

git fetch upstream --tags

Verifique a versão atual e as tags do upstream:

git describe --tags --always
git show --no-patch --oneline v3.4.7

Observação: a versão atual do projeto é v3.8.0. As referências a v3.4.7 abaixo são mantidas apenas como exemplos históricos. Para lançamentos reais, use :latest ou a tag da versão atual (por exemplo, :v3.8.0).

Se você quiser mesclar a versão mais recente de main do upstream, mantendo forçadamente o fly.toml do seu fork, siga este fluxo de trabalho:

git merge upstream/main
git checkout HEAD~1 -- fly.toml
git add -- fly.toml
git commit -m "chore(deploy): keep fork fly.toml"
git push origin main

Observações:

• git merge upstream/main sincroniza o código mais recente do repositório original
• git checkout HEAD~1 -- fly.toml restaura o fly.toml do seu fork para a versão anterior à mesclagem
• Se o upstream não tiver modificado o fly.toml, esta etapa não introduzirá nenhuma diferença
• Se o upstream tiver modificado o fly.toml, esta etapa garante que o nome da sua aplicação Fly, a montagem do volume, a região e outras configurações de implantação específicas do fork não sejam sobrescritas

Se você quiser alinhar com uma tag de lançamento específica (por exemplo, v3.4.7), primeiro verifique se a tag já está incluída em upstream/main:

git merge-base --is-ancestor v3.4.7 upstream/main

Um retorno bem-sucedido significa que upstream/main já contém essa versão; você pode simplesmente mesclar upstream/main.

9.2 Sequência padrão de lançamento após sincronizar o upstream

Após sincronizar com o repositório original, siga esta ordem de lançamento recomendada:

1. git fetch upstream --tags
2. git merge upstream/main
3. Restaure o fly.toml do fork
4. git push origin main
5. flyctl deploy
6. flyctl status -a omniroute
7. flyctl logs --no-tail -a omniroute

Este é o fluxo de trabalho efetivamente utilizado ao atualizar o projeto atual para v3.4.7 (o exemplo refere-se a uma versão histórica; a versão atual real é v3.8.0).

---

10. Verificações Pós-Implantação

10.1 Verificar o Status da Aplicação

flyctl status -a omniroute

10.2 Visualizar os Logs de Inicialização

flyctl logs --no-tail -a omniroute

10.3 Verificar a Acessibilidade do Site

try {
  (Invoke-WebRequest -Uri "https://omniroute.fly.dev" -MaximumRedirection 5 -UseBasicParsing).StatusCode
} catch {
  if ($_.Exception.Response) {
    $_.Exception.Response.StatusCode.value__
  } else {
    throw
  }
}

Um valor de retorno 200 indica que o site está respondendo normalmente.

---

11. Indicadores de Sucesso

Após uma implantação bem-sucedida, os logs devem exibir um conteúdo semelhante a:

[bootstrap] Secrets persisted to: /data/server.env
[DB] SQLite database ready: /data/storage.sqlite

Estes dois pontos são essenciais:

• /data/server.env confirma que os segredos de runtime são gravados no volume persistente
• /data/storage.sqlite confirma que o banco de dados é gravado no volume persistente

Se você vir /app/data/... em vez disso, DATA_DIR está configurado incorretamente e deve ser corrigido imediatamente.

---

12. Problemas Comuns

12.1 A Página Secrets Está Vazia

Geralmente, há dois motivos:

• Você ainda não executou flyctl secrets set
• Você está visualizando uma aplicação diferente (por exemplo, oroute em vez de omniroute)

12.2 flyctl deploy Relata app not found

Crie a aplicação primeiro:

flyctl apps create omniroute

12.3 Falha na Análise do fly.toml

Verifique o seguinte:

• Se há caracteres corrompidos nos comentários
• Se as aspas e a indentação TOML estão corretas

12.4 Os Dados Não Estão Sendo Persistidos

Verifique ambos os itens a seguir:

• fly.toml contém destination = '/data'
• DATA_DIR está definido como /data

12.5 É Possível Executar Sem INITIAL_PASSWORD?

Sim, é possível. A aplicação usará a senha padrão CHANGEME. Recomenda-se alterar a senha do backend o mais rápido possível em produção.

---

13. Reutilização em Novos Projetos

Se você estiver implantando um novo projeto seguindo este documento, precisará alterar apenas estes itens:

1. Altere o valor de app em fly.toml
2. Altere NEXT_PUBLIC_BASE_URL
3. Mantenha DATA_DIR=/data
4. Gere novamente API_KEY_SECRET, JWT_SECRET, MACHINE_ID_SALT e STORAGE_ENCRYPTION_KEY
5. Após a primeira implantação, verifique se os logs são gravados em /data

Não reutilize chaves de um projeto anterior.

---

14. Checklist Mínimo de Release para o Projeto Atual

Os comandos mais usados em releases posteriores são:

flyctl auth whoami
flyctl status -a omniroute
flyctl secrets list -a omniroute
flyctl deploy
flyctl logs --no-tail -a omniroute

Para uma release normal, o comando principal é simplesmente:

flyctl deploy

Para uma primeira implantação em um novo ambiente, as etapas principais são:

1. flyctl auth login
2. flyctl apps create omniroute
3. flyctl secrets set ... -a omniroute
4. flyctl deploy
5. flyctl logs --no-tail -a omniroute

---

Código-fonte do OmniRoute (a58000c7685f)