App mobile — build e instalação#

🌐 English · 简体中文 · فارسی · Español · Português · 日本語 · 한국어 · Français · Deutsch · Русский

O app mobile do opendray (app/mobile/) é um cliente de controle, não um segundo gateway. Ele faz o mesmo trabalho do admin web em /admin/: cria e conduz sessões, gerencia canais e integrações, navega pela memória, lê hosts git. Os próprios agentes continuam rodando no seu host de gateway — o celular apenas se conecta a eles.

Por isso, o app é inútil sozinho: ele se conecta a um gateway opendray em execução via HTTPS. Suba o gateway primeiro (getting-started), depois faça o build do app e aponte-o para a URL do seu gateway.

Por que não há download na App Store / Play Store? O opendray é um software self-hosted e single-tenant. Um build de loja teria que embutir o backend de alguém, que é exatamente o que o opendray não é. Então você faz o build do app por conta própria, assinado com sua própria identidade, e ele fala apenas com o seu gateway. Os dois caminhos suportados abaixo são (A) um APK Android que você instala via sideload, e (B) um build iOS que você instala pelo Xcode.

Etapa 0 — Tornar o gateway acessível a partir do celular#

O app fala com o gateway pela rede, então o celular precisa conseguir alcançá-lo.

Não exponha a :8770 crua para a internet. Coloque TLS e um ingress na frente dela. O Cloudflare Tunnel é a opção de menor atrito (sem port-forwarding, sem IP público). Snippets de nginx / Caddy — incluindo os headers de upgrade de WebSocket que o terminal de Sessões precisa — estão em operator-guide §Topology.

Verifique a acessibilidade a partir do celular antes de fazer o build, por exemplo abrindo a URL do Gateway no navegador do celular — você deve obter a página de login do admin web.

Etapa 1 — Instalar o toolchain do Flutter#

O app é construído com Flutter. Você precisa dele na máquina que faz o build (não no celular).

O flutter doctor é o portão: ele te diz exatamente o que está faltando para Android (Android SDK + um dispositivo/emulador) ou iOS (Xcode + CocoaPods). Corrija as linhas com ✗ da sua plataforma alvo antes de continuar.

Busque as dependências uma vez:

Etapa 2A — Android: buildar um APK e instalar via sideload#

Este é o caminho mais simples — sem conta de desenvolvedor, sem loja.

Buildar o APK#

A saída fica em:

Nota sobre assinatura. Por padrão, o build de release é assinado com o keystore de debug (veja o TODO em android/app/build.gradle.kts). Isso é suficiente para sideload pessoal. Se você quiser uma chave de upload apropriada (obrigatória para a Play Store, e boa prática para um build que você vai manter atualizando), siga Flutter — Sign the app e adicione um signingConfig para release.

Colocar o APK no celular#

Escolha o que for conveniente:

Ou transfira o arquivo .apk para o celular (equivalente ao AirDrop, um compartilhamento de arquivos, um link de download, e-mail para você mesmo) e toque nele. O Android vai pedir para você permitir "Instalar apps desconhecidos" para o app que estiver abrindo o arquivo (Arquivos, Chrome, etc.) — conceda a permissão, depois confirme a instalação.

O app aparece como Opendray (io.opendray.opendray).

Etapa 2B — iOS: buildar e instalar pelo Xcode#

O iOS não tem equivalente a instalar um APK via sideload — toda instalação é code-signed. Você precisa de um Mac com Xcode e um Apple ID. Um Apple ID gratuito funciona (o app é re-assinado a cada 7 dias; você reinstala quando o provisioning profile expira). Uma conta paga do Apple Developer (US$99/ano) dá profiles válidos por um ano e TestFlight.

Configuração de assinatura (uma vez)#

No Xcode:

1. Selecione o target Runner → aba Signing & Capabilities.
2. Marque Automatically manage signing.
3. Team: escolha o time do seu Apple ID (adicione seu Apple ID em Xcode → Settings → Accounts se ele não estiver listado).
4. Bundle Identifier: ele vem como io.opendray.opendray. Com um Apple ID gratuito esse ID exato pode já estar em uso do lado da Apple — se o Xcode mostrar um erro de provisioning, mude-o para algo único como io.opendray.opendray.<yourname>.

Buildar e instalar no iPhone#

1. Conecte o iPhone via USB; confie no computador quando solicitado.
2. Habilite o Developer Mode no celular: Settings → Privacy & Security → Developer Mode → on → reinicie.
3. No dropdown de dispositivos do Xcode (barra superior), selecione seu iPhone.
4. Pressione ▶ Run (ou ⌘R). O Xcode builda, assina e instala.

Ou conduza pelo CLI e deixe o Xcode cuidar da assinatura:

Primeiro lançamento no dispositivo#

O iOS não vai rodar um app assinado por um time pessoal até você confiar no developer profile:

• No celular: Settings → General → VPN & Device Management → seu Apple ID → Trust.

O app aparece como Opendray na tela inicial.

Expiração do Apple ID gratuito. Após ~7 dias o app para de abrir ("could not verify app"). Rode o build novamente pelo Xcode para renovar o profile. Uma conta paga evita isso.

Etapa 3 — Conectar o app ao seu gateway#

O primeiro lançamento mostra a tela de onboarding:

1. Gateway URL — insira a URL da Etapa 0 (ex.: https://opendray.yourdomain.com). Toque em Continue.
2. Sign in — admin + sua senha de admin (a que você definiu em [admin].password, ou alterou depois).

É isso — você chega nas mesmas superfícies do admin web: Sessões, Canais, Integrações, Memória, Git, Configurações.

Para apontar o app para um gateway diferente depois, toque em Change na tela de login (ou Settings → server) e insira a URL novamente.

Atualizando o app#

Não há atualização automática — você reinstala após puxar o código novo:

A string de versão do próprio app fica em app/mobile/pubspec.yaml (version: <semver>+<build>).

Solução de problemas#

Veja também#

• getting-started.md — suba o gateway ao qual o app se conecta
• operator-guide.md — topologia de reverse proxy / tunnel para acesso fora da LAN
• Flutter — build & release Android
• Flutter — build & release iOS