🌐 Esta página aún no está traducida al español. Mostrando referencia en portugués (BR). Ayúdanos a traducir.

Conectar um servidor

O Add Server Wizard é o caminho oficial pra conectar o RoqueOS frontend (em https://roqueos.com.br/app) ao seu RoqueOS Server. Fica em Settings → Server → Adicionar servidor.

Substitui o fluxo antigo que pedia pro user abrir <servidor>:27021/admin no navegador. Agora tudo acontece dentro do app.

Quando usar

• ✅ Servidor recém-instalado (install.sh rodou, sem API Keys ainda) — wizard cria a primeira admin key
• ✅ Servidor já em uso (você tem apiKey + apiSecret salvos) — wizard valida e adiciona à lista
• ✅ Trocar de servidor — adicionar segundo server, alternar entre eles via Switcher na menubar

Fluxo bootstrap (server zerado)

7 steps. Tempo total: ~1 min.

Step 1 — URL

Cole a URL do server. Aceita:

• http://localhost:27021 (Docker rodando na sua máquina — funciona via loopback)
• https://servidor.exemplo.com.br (atrás de Cloudflare Tunnel ou TLS cert)

Wizard normaliza protocolo (servidor.exemplo.com.br → https://servidor.exemplo.com.br automático) e detecta servers já cadastrados antes de prosseguir.

⚠️ HTTP vs HTTPS — limitação do navegador

O frontend roqueos.com.br/app roda em HTTPS. Por design dos browsers modernos (Mixed Content policy), uma página HTTPS NÃO consegue chamar APIs HTTP — o navegador bloqueia a request silenciosamente, antes mesmo de sair da máquina.

Isso significa que tentar conectar http://192.168.1.50:27021 (LAN) ou http://servidor.com:27021 (público) vai falhar com "couldn't connect" que parece bug do servidor mas é o navegador bloqueando.

O wizard detecta isso pra você e mostra um banner amarelo explicando o problema antes da request rolar. Três soluções, em ordem de preferência:

1. HTTPS via Cloudflare Tunnel (recomendado)

Gratuito, plug-and-play. O install.sh já tem suporte built-in:

curl -fsSL https://roqueos.com.br/install.sh | bash -s -- --update
# Depois: Settings → Server → Cloudflare Tunnel → Conectar

Resultado: seu servidor fica em https://<id>.cloud.roqueos.com.br ou seu domínio próprio. TLS automático, sem mexer em firewall, sem precisar IP público.

Guia completo install.sh + Cloudflare Tunnel →

2. Use o app desktop ou mobile

Os wrappers nativos (Microsoft Store, Play Store, App Store) não têm restrição de mixed content — eles rodam código nativo, não páginas web em HTTPS estrito.

• 🪟 Microsoft Store (Windows)
• 🍎 App Store (iOS/macOS)
• 🤖 Google Play (Android)

Bom pra: ambiente homelab onde você não quer/pode configurar tunnel.

3. Servidor em localhost (loopback)

http://localhost:27021, http://127.0.0.1:27021 e http://[::1]:27021 são tratados como contexto seguro pelos browsers modernos via Secure Contexts spec — então funcionam mesmo com frontend HTTPS.

Bom pra: dev local, testar antes de subir num server real.

Step 2 — Detect

Wizard hita 2 endpoints anônimos em paralelo:

• GET /health/version-info — versão + minClientVersion
• GET /admin/setup — se retorna { needsSetup: true }, servidor zerado

Aqui também checa compat de versão. Se servidor está em v1.0.10 mas o client (frontend) requer v1.0.13+, mostra aviso amigável "atualize o server primeiro" + link pro install.sh --update.

Step 3 — Bootstrap (servidor zerado)

Botão "Criar chave admin" → POST /admin/setup (rate-limited por IP no servidor pra evitar setup race).

Retorna { apiKey, apiSecret } que o wizard exibe no próximo step.

Tratamento de race: se 2 navegadores tentam setup ao mesmo tempo, o segundo recebe error: 'Setup already completed' e wizard transita pro step 5 (credentials manual).

Step 4 — keyCreated

Mostra apiKey + apiSecret retornados em fields read-only com botão de copy.

⚠️ Critical UX guard:

• Modal tem closeOnBackdrop=false (não fecha clicando fora)
• Botão X abre sub-modal de confirmação ("Você salvou as credenciais?")
• Checkbox obrigatório "Salvei minhas credenciais" habilita o botão Next
• Se você fechar sem salvar, a chave fica no servidor mas perdida pra você — recovery só via /admin HTML legacy

Step 5 — credentials (servidor já configurado)

Se em step 2 a detecção apontou que setup já foi feito, pula direto pra cá:

• Campo apiKey
• Campo apiSecret
• Link "Abrir painel admin do servidor ↗" (abre <server>/admin HTML legacy em nova aba)

A página legacy continua sendo a porta dos fundos pra recovery e automação.

Step 6 — Nome

Único campo: nome amigável pro servidor (aparece no Server Switcher da menubar).

Default sugerido: URL.hostname (ex.: demo.level-hard.com ou localhost).

Step 7 — Finalize

Wizard chama:

• addBackendService({ name, url }) — salva na lista backendSettings.services
• setApiCredentials(apiKey, apiSecret, serviceId) — guarda creds no Firestore
• setActiveBackendService(serviceId) — torna ativo

Modal fecha. Server está conectado. Você está em Server Mode.

Server Switcher (menubar)

Quando você tem 2+ servidores cadastrados, aparece um dropdown na menubar (canto superior esquerdo) mostrando o servidor ativo. Click pra trocar entre eles.

Status atual (mai/2026): o componente ROSServerSwitcher ainda não foi reconstruído após uma sessão anterior — a feature está planejada mas não shipped. Por enquanto, alternar entre servers é via Settings → Server → clicar no servidor desejado.

Servidor demo público

Pra testar sem instalar nada, RoqueOS oferece um servidor demo público:

• URL: https://demo.level-hard.com
• apiKey: rqos_UB5TtjumUYQ90fHAIhTSfVvuMQiwcaFx
• apiSecret: rqos_sec_gezGxZcqV2jJgxvMxQbkMK7KInzVySIWzG8UqmTpE-dVW2pL

Não é "modo demo" — é um RoqueOS Server real, atualizado pelo founder, com cleanup diário (containers órfãos, agents/sessions > 24h, volumes dangling). Limites no demo:

• Não-admin não vê Server Admin Panel (gate em windowManagement.js)
• Cloud Gaming sometimes purga sessão zumbi
• Containers permanecem ~24h antes do prune

Bom pra: explorar Containers, Terminal, VS Code embarcado, Files. Ruim pra: persistência longa, dados importantes.

Troubleshooting

Sintoma	Solução
"Servidor inacessível"	Confirma curl <url>/health retorna 200. Provavelmente porta 27021 não tá liberada ou Docker parado
"Servidor já cadastrado"	Wizard detectou duplicata. Vá em Settings → Server e selecione o existente
"Servidor desatualizado"	Roda --update no servidor: curl -fsSL https://roqueos.com.br/install.sh | bash -s -- --update
"Setup already completed" mas você nunca configurou	Reset: docker exec roqueos-server sqlite3 /app/data/roqueos.db "DELETE FROM api_keys;" (cuidado — apaga todas as keys existentes)
Server adicionou mas Settings volta vazio	Provavelmente faltou Firestore login. Verifica em DevTools console se Firestore: PERMISSION_DENIED aparece

Referências

• install.sh one-liner — pra subir o servidor antes
• Server Admin Panel — gerenciar depois de conectado
• Volumes & backup — entender persistência
• Composable interno: src/composables/useAddServerWizard.js (estado + flow)