App móvil — compilar e instalar#
🌐 English · 简体中文 · فارسی · Español · Português · 日本語 · 한국어 · Français · Deutsch · Русский
La app móvil de opendray (app/mobile/) es un cliente de control, no un
segundo gateway. Hace el mismo trabajo que el panel de administración web en /admin/:
lanzar y dirigir sesiones, gestionar canales e integraciones, explorar
memoria, leer hosts de git. Los propios agentes siguen ejecutándose en tu
host gateway — el teléfono simplemente se conecta a ellos.
Por eso, la app es inútil por sí sola: se conecta a un gateway de opendray en marcha sobre HTTPS. Pon primero el gateway en marcha (getting-started), luego compila la app y apúntala a la URL de tu gateway.
¿Por qué no hay descarga en App Store / Play Store? opendray es software autoalojado y de un solo inquilino. Una compilación de tienda tendría que incorporar el backend de alguien, que es exactamente lo que opendray no es. Así que compilas la app tú mismo, firmada con tu propia identidad, y solo habla con tu gateway. Los dos caminos soportados a continuación son (A) un APK de Android que instalas manualmente (sideload), y (B) una compilación de iOS que instalas mediante Xcode.
Paso 0 — hacer que el gateway sea accesible desde el teléfono#
La app habla con el gateway por la red, así que el teléfono tiene que poder alcanzarlo.
| Escenario | Qué introducir como Gateway URL |
|---|---|
| Teléfono en la misma LAN que el gateway | http://<gateway-lan-ip>:8770 (p. ej. http://192.168.1.50:8770) |
| Gateway detrás de un reverse proxy con TLS | https://opendray.yourdomain.com |
| Acceso fuera de la LAN (datos móviles, viajes) | Un endpoint HTTPS público — Cloudflare Tunnel, Tailscale, o un reverse proxy nginx/Caddy |
No expongas
:8770directamente a internet. Pon TLS y un ingress por delante. Cloudflare Tunnel es la opción de menor fricción (sin port-forwarding, sin IP pública). Los snippets de nginx / Caddy — incluyendo las cabeceras de upgrade de WebSocket que necesita la terminal de Sessions — están en operator-guide §Topology.
Verifica la accesibilidad desde el teléfono antes de compilar, p. ej. abre la Gateway URL en el navegador del teléfono — deberías obtener la página de inicio de sesión del panel de administración web.
Paso 1 — instalar la cadena de herramientas de Flutter#
La app se compila con Flutter. Lo necesitas en la máquina que hace la compilación (no en el teléfono).
[object Promise]flutter doctor es el filtro: te dice exactamente qué falta para
Android (Android SDK + un dispositivo/emulador) o iOS (Xcode + CocoaPods).
Corrige las líneas ✗ para tu plataforma objetivo antes de continuar.
Obtén las dependencias una vez:
[object Promise]Paso 2A — Android: compilar un APK e instalarlo manualmente#
Este es el camino más simple — sin cuenta de desarrollador, sin tienda.
Compilar el APK#
[object Promise]La salida queda en:
[object Promise]Nota sobre la firma. De fábrica, la compilación de release se firma con el keystore de depuración (ver el
TODOenandroid/app/build.gradle.kts). Eso está bien para sideload personal. Si quieres una clave de subida adecuada (requerida para Play Store, y buena higiene para una compilación que mantendrás actualizada), sigue Flutter — Sign the app y añade unsigningConfigpararelease.
Llevar el APK al teléfono#
Elige el que te resulte conveniente:
[object Promise]O transfiere el archivo .apk al teléfono (equivalente a AirDrop, un
recurso compartido de archivos, un enlace de descarga, un correo a ti mismo) y púlsalo. Android te pedirá
permitir "Instalar apps desconocidas" para la app que esté abriendo el
archivo (Files, Chrome, etc.) — concédelo, luego confirma la instalación.
La app aparece como Opendray (io.opendray.opendray).
Paso 2B — iOS: compilar e instalar mediante Xcode#
iOS no tiene un equivalente a instalar-un-APK manualmente — cada instalación está firmada con código. Necesitas un Mac con Xcode y un Apple ID. Un Apple ID gratuito funciona (la app se vuelve a firmar cada 7 días; reinstalas cuando el perfil de aprovisionamiento expira). Una cuenta de pago de Apple Developer (US$99/año) da perfiles de un año de duración y TestFlight.
Configuración de firma única#
[object Promise]En Xcode:
- Selecciona el target Runner → pestaña Signing & Capabilities.
- Marca Automatically manage signing.
- Team: elige el equipo de tu Apple ID (añade tu Apple ID en Xcode → Settings → Accounts si no está listado).
- Bundle Identifier: viene como
io.opendray.opendray. Con un Apple ID gratuito, este ID exacto puede estar ya ocupado del lado de Apple — si Xcode muestra un error de aprovisionamiento, cámbialo a algo único comoio.opendray.opendray.<tunombre>.
Compilar e instalar en el iPhone#
- Conecta el iPhone vía USB; confía en el ordenador cuando se te pida.
- Activa el Modo de desarrollador en el teléfono: Settings → Privacy & Security → Developer Mode → activar → reiniciar.
- En el desplegable de dispositivos de Xcode (barra superior), selecciona tu iPhone.
- Pulsa ▶ Run (o
⌘R). Xcode compila, firma e instala.
O contrólalo desde la CLI y deja que Xcode gestione la firma:
[object Promise]Primer lanzamiento en el dispositivo#
iOS no ejecutará una app firmada por un equipo personal hasta que confíes en el perfil del desarrollador:
- En el teléfono: Settings → General → VPN & Device Management → tu Apple ID → Trust.
La app aparece como Opendray en la pantalla de inicio.
Expiración del Apple ID gratuito. Tras ~7 días la app deja de lanzarse ("could not verify app"). Vuelve a ejecutar la compilación desde Xcode para refrescar el perfil. Una cuenta de pago evita esto.
Paso 3 — conectar la app a tu gateway#
El primer lanzamiento muestra la pantalla de incorporación:
- Gateway URL — introduce la URL del Paso 0
(p. ej.
https://opendray.yourdomain.com). Pulsa Continue. - Sign in —
admin+ tu contraseña de administración (la que estableciste en[admin].password, o la que cambiaste después).
Eso es todo — aterrizas en las mismas superficies que el panel de administración web: Sessions, Channels, Integrations, Memory, Git, Settings.
Para apuntar la app a un gateway diferente más tarde, pulsa Change en la pantalla de inicio de sesión (o Settings → server) y vuelve a introducir la URL.
Actualizar la app#
No hay actualización automática — reinstalas tras obtener el nuevo código:
[object Promise]La cadena de versión propia de la app vive en app/mobile/pubspec.yaml
(version: <semver>+<build>).
Solución de problemas#
| Síntoma | Causa | Solución |
|---|---|---|
| "could not connect" en la incorporación | El teléfono no puede alcanzar la Gateway URL | Abre la URL en el navegador del teléfono; corrige primero la IP de LAN / túnel / TLS (Paso 0) |
| El inicio de sesión funciona pero la terminal de Sessions nunca conecta | El reverse proxy está descartando el upgrade de WebSocket | Añade las cabeceras WS — operator-guide §Topology |
| Android bloquea la instalación | "Instalar apps desconocidas" no concedido | Permítelo para la app que abre el .apk (Files / Chrome) |
| "Untrusted Developer" en iOS al lanzar | El perfil de equipo personal aún no es de confianza | Settings → General → VPN & Device Management → Trust |
| "Unable to install / signing" en iOS dentro de Xcode | Conflicto de Bundle ID con un Apple ID gratuito | Cambia el Bundle Identifier a io.opendray.opendray.<tunombre> |
| La app de iOS deja de abrirse tras una semana | El perfil del Apple ID gratuito expiró (7 días) | Vuelve a ejecutar desde Xcode, o usa una cuenta de pago |
flutter doctor muestra ✗ para tu plataforma |
Falta Android SDK / Xcode / CocoaPods | Sigue la línea exacta que imprime flutter doctor |
Consulta también#
- getting-started.md — pon en marcha el gateway al que se conecta la app
- operator-guide.md — topología de reverse proxy / túnel para acceso fuera de la LAN
- Flutter — build & release Android
- Flutter — build & release iOS