# OmniRoute Fly.io Deployment Guide (Español)

🌐 **Languages:** 🇺🇸 [English](../../../../ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇪🇹 [am](../../../am/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇸🇦 [ar](../../../ar/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇦🇿 [az](../../../az/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇧🇬 [bg](../../../bg/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇧🇩 [bn](../../../bn/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇧🇦 [bs](../../../bs/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇨🇿 [cs](../../../cs/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇩🇰 [da](../../../da/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇩🇪 [de](../../../de/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇬🇷 [el](../../../el/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇪🇪 [et](../../../et/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇮🇷 [fa](../../../fa/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇫🇮 [fi](../../../fi/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇫🇷 [fr](../../../fr/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇮🇪 [ga](../../../ga/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇮🇳 [gu](../../../gu/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇳🇬 [ha](../../../ha/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇮🇱 [he](../../../he/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇮🇳 [hi](../../../hi/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇭🇷 [hr](../../../hr/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇭🇺 [hu](../../../hu/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇦🇲 [hy](../../../hy/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇮🇩 [id](../../../id/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇳🇬 [ig](../../../ig/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇮🇹 [it](../../../it/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇯🇵 [ja](../../../ja/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇬🇪 [ka](../../../ka/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇰🇭 [km](../../../km/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇮🇳 [kn](../../../kn/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇰🇷 [ko](../../../ko/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇱🇹 [lt](../../../lt/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇱🇻 [lv](../../../lv/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇮🇳 [ml](../../../ml/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇮🇳 [mr](../../../mr/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇲🇾 [ms](../../../ms/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇲🇹 [mt](../../../mt/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇲🇲 [my](../../../my/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇳🇵 [ne](../../../ne/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇳🇱 [nl](../../../nl/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇳🇴 [no](../../../no/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇮🇳 [or](../../../or/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇮🇳 [pa](../../../pa/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇵🇭 [phi](../../../phi/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇵🇱 [pl](../../../pl/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇵🇹 [pt](../../../pt/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇷🇴 [ro](../../../ro/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇷🇺 [ru](../../../ru/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇱🇰 [si](../../../si/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇸🇰 [sk](../../../sk/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇸🇮 [sl](../../../sl/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇷🇸 [sr](../../../sr/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇸🇪 [sv](../../../sv/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇰🇪 [sw](../../../sw/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇮🇳 [ta](../../../ta/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇮🇳 [te](../../../te/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇹🇭 [th](../../../th/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇹🇷 [tr](../../../tr/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇵🇰 [ur](../../../ur/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇺🇿 [uz](../../../uz/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇻🇳 [vi](../../../vi/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇳🇬 [yo](../../../yo/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/ops/FLY_IO_DEPLOYMENT_GUIDE.md)

---

Este documento describe el proceso real de despliegue de OmniRoute en Fly.io y abarca tres escenarios:

- Desplegar el proyecto actual en Fly.io por primera vez
- Publicar actualizaciones de código posteriores
- Desplegar proyectos nuevos siguiendo el mismo flujo de trabajo

Esta guía se basa en una configuración verificada y funcional para el proyecto actual. El nombre de la aplicación es `omniroute`.

---

## 1. Objetivos del despliegue

- Plataforma: Fly.io
- Método de despliegue: Publicación directa local mediante `flyctl`
- Entorno de ejecución: Uso del `Dockerfile` y de `fly.toml` existentes en el repositorio
- Persistencia de datos: Volumen de Fly montado en `/data`
- URL de acceso: `https://omniroute.fly.dev/`

---

## 2. Configuración clave del proyecto actual

Se ha confirmado que el archivo `fly.toml` del repositorio actual contiene los siguientes elementos clave:

```toml
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"
```

Notas:

- `app = 'omniroute'` determina a qué aplicación de Fly se dirige el despliegue
- `destination = '/data'` determina el directorio de montaje del volumen persistente
- Este proyecto debe establecer `DATA_DIR=/data`; de lo contrario, la base de datos y las claves se escribirán en el directorio temporal del contenedor

---

## 3. Requisitos previos

### 3.1 Instalación de la CLI de Fly

Windows PowerShell:

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

Si el script de instalación falla en su entorno, también puede descargar manualmente el binario de `flyctl` y añadirlo a su `PATH`.

### 3.2 Inicio de sesión en su cuenta de Fly

```powershell
flyctl auth login
```

### 3.3 Verificación del estado de inicio de sesión

```powershell
flyctl auth whoami
flyctl version
```

---

## 4. Primer despliegue del proyecto actual

### 4.1 Clonar el código y acceder al directorio

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

### 4.2 Confirmar el nombre de la aplicación

Abra `fly.toml` y verifique la siguiente línea:

```toml
app = 'omniroute'
```

Si está desplegando en una nueva aplicación propia, puede cambiarlo por un nombre globalmente único, por ejemplo:

```toml
app = 'omniroute-yourname'
```

Nota:

- Asegúrese de que la aplicación que ve en la consola coincida con el valor de `app` en `fly.toml`
- Si anteriormente utilizó un nombre diferente, como `oroute`, no lo confunda con `omniroute`

### 4.3 Crear la aplicación

Si la aplicación aún no existe:

```powershell
flyctl apps create omniroute
```

Si cambió el nombre de la aplicación, sustituya `omniroute` por el nombre que haya elegido.

### 4.4 Primer despliegue

```powershell
flyctl deploy
```

---

## 5. Parámetros obligatorios

Para este proyecto se recomienda configurar, como mínimo, los siguientes parámetros en Fly.io.

### 5.1 Parámetros verificados

Estos parámetros se han utilizado en despliegues reales de la aplicación actual `omniroute`:

- `API_KEY_SECRET`
- `DATA_DIR`
- `JWT_SECRET`
- `MACHINE_ID_SALT`
- `NEXT_PUBLIC_BASE_URL`
- `OMNIROUTE_WS_BRIDGE_SECRET` (obligatorio en producción — se utiliza para la autenticación del puente WebSocket)
- `STORAGE_ENCRYPTION_KEY`

### 5.2 Acerca de `INITIAL_PASSWORD`

El proyecto actual no establece `INITIAL_PASSWORD` porque este despliegue no lo requiere.

Si no se establece:

- El registro de inicio indicará que la contraseña predeterminada es `CHANGEME`
- Debe cambiar la contraseña de inicio de sesión en la configuración del sistema lo antes posible después del despliegue

Si desea inicializar la contraseña del backend sin intervención, puede añadirla más adelante:

- `INITIAL_PASSWORD`

---

## 6. Parámetros recomendados

### 6.1 Configuración de secretos

Se recomiendan las siguientes variables para Fly Secrets:

| Variable                        | Recomendación             | Descripción                                                         |
| ------------------------------- | ------------------------- | ------------------------------------------------------------------- |
| `API_KEY_SECRET`                | Obligatoria               | Se utiliza para generar y validar claves de API                     |
| `JWT_SECRET`                    | Obligatoria               | Se utiliza para las sesiones de inicio de sesión y la firma de JWT  |
| `OMNIROUTE_WS_BRIDGE_SECRET`    | Obligatoria en producción | Secreto de autenticación del puente WebSocket                       |
| `STORAGE_ENCRYPTION_KEY`        | Altamente recomendada     | Cifra en reposo la información confidencial de las conexiones       |
| `MACHINE_ID_SALT`               | Recomendada               | Genera un identificador estable de la máquina                       |
| `INITIAL_PASSWORD`              | Opcional                  | Establece la contraseña inicial del backend en el primer despliegue |
| Credenciales privadas OAuth/API | Según sea necesario       | Configuración de autenticación de plataformas externas              |

### 6.2 Valores recomendados para el proyecto actual

| Variable               | Valor recomendado           |
| ---------------------- | --------------------------- |
| `DATA_DIR`             | `/data`                     |
| `NEXT_PUBLIC_BASE_URL` | `https://omniroute.fly.dev` |

Notas:

- `DATA_DIR=/data` es fundamental y debe coincidir con el punto de montaje del volumen de Fly
- `NEXT_PUBLIC_BASE_URL` se utiliza en el programador, las devoluciones de llamada del frontend y situaciones similares

### 6.3 Configuración de la URL de devolución de llamada de OAuth

Si necesita habilitar proveedores basados en OAuth (p. ej., Antigravity, Gemini o Cursor) en el despliegue de Fly.io, asegúrese de cumplir los dos puntos siguientes:

1. **Establezca `NEXT_PUBLIC_BASE_URL` en su dominio HTTPS público**

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

   Si utiliza un dominio personalizado, sustitúyalo por el dominio correspondiente (p. ej., `https://omniroute.yourdomain.com`).

2. **Configure la URL de devolución de llamada en la consola del proveedor**

   Todos los proveedores OAuth comparten la única ruta de devolución de llamada `/callback`; NO existe una ruta de devolución de llamada específica para cada proveedor:

   ```text
   <NEXT_PUBLIC_BASE_URL>/callback
   ```

   Por ejemplo, independientemente de si se trata de Gemini, Antigravity, Cursor o GitLab Duo:
   - `https://omniroute.fly.dev/callback`

   Si `NEXT_PUBLIC_BASE_URL` no coincide con la URL de devolución de llamada registrada con el proveedor, el flujo de OAuth fallará en el paso de redirección del navegador.

---

## 7. Configuración de secretos con un solo comando

Los siguientes comandos generan valores aleatorios seguros y escriben en un solo paso todos los parámetros necesarios para el proyecto actual en Fly Secrets.

Notas:

- No incluye `INITIAL_PASSWORD`
- Está diseñado para el proyecto actual `omniroute`

```powershell
$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
```

En Linux/macOS, también puede utilizar `openssl rand -hex 32`:

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

Notas:

- `OMNIROUTE_WS_BRIDGE_SECRET` es obligatoria en producción; si falta, impedirá que se complete el protocolo de enlace del puente WebSocket

Si también desea establecer una contraseña inicial:

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

---

## 8. Visualización de los parámetros actuales

```powershell
flyctl secrets list -a omniroute
```

Si la página `Secrets` de la consola no muestra las variables esperadas, compruebe:

- Que está visualizando la aplicación `omniroute`
- Que el valor `app` de `fly.toml` coincide con la aplicación de la consola

---

## 9. Actualizaciones y versiones posteriores

Después de actualizar el código, el proceso de publicación es sencillo:

```powershell
git pull
flyctl deploy
```

Si solo necesita actualizar parámetros sin cambiar el código:

```powershell
flyctl secrets set KEY=value -a omniroute
```

Fly realizará automáticamente una actualización gradual de las máquinas.

### 9.1 Seguimiento de las actualizaciones del repositorio upstream conservando el `fly.toml` de su fork

Si el repositorio actual es un fork y desea sincronizar las actualizaciones desde el upstream `https://github.com/diegosouzapw/OmniRoute`, siga el flujo de trabajo que se indica a continuación.

Primero, verifique sus repositorios remotos:

```powershell
git remote -v
```

Debería ver al menos:

- `origin` apuntando a su propio fork
- `upstream` apuntando al repositorio original

Si `upstream` no está configurado, añádalo:

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

Antes de sincronizar con upstream, obtenga los commits y las etiquetas más recientes:

```powershell
git fetch upstream --tags
```

Compruebe la versión actual y las etiquetas de upstream:

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

> Nota: La versión actual del proyecto es `v3.8.0`. Las referencias a `v3.4.7` que aparecen a continuación se conservan únicamente como ejemplos históricos. Para versiones reales, utilice `:latest` o la etiqueta de la versión actual (p. ej., `:v3.8.0`).

Si desea fusionar la versión más reciente de `main` del upstream conservando de forma forzosa el `fly.toml` de su fork, siga este flujo de trabajo:

```powershell
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
```

Notas:

- `git merge upstream/main` sincroniza el código más reciente del repositorio original
- `git checkout HEAD~1 -- fly.toml` restaura el `fly.toml` propio de su fork a partir del estado anterior a la fusión
- Si upstream no modificó `fly.toml`, este paso no introducirá ninguna diferencia
- Si upstream modificó `fly.toml`, este paso garantiza que el nombre de su aplicación de Fly, el montaje del volumen, la región y otras configuraciones de despliegue específicas del fork no se sobrescriban

Si desea alinearse con una etiqueta de versión específica (p. ej., `v3.4.7`), verifique primero que la etiqueta ya esté incluida en `upstream/main`:

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

Un resultado satisfactorio significa que `upstream/main` ya contiene esa versión; puede fusionar simplemente `upstream/main`.

### 9.2 Secuencia estándar de publicación después de sincronizar con upstream

Después de sincronizar con el repositorio original, siga este orden de publicación recomendado:

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

Este es el flujo de trabajo real utilizado al actualizar el proyecto actual a `v3.4.7` (el ejemplo hace referencia a una versión histórica; la versión actual real es `v3.8.0`).

---

## 10. Comprobaciones posteriores al despliegue

### 10.1 Comprobar el estado de la aplicación

```powershell
flyctl status -a omniroute
```

### 10.2 Ver los registros de inicio

```powershell
flyctl logs --no-tail -a omniroute
```

### 10.3 Verificar la accesibilidad del sitio

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

Un valor de retorno de `200` indica que el sitio responde con normalidad.

---

## 11. Indicadores de éxito

Tras un despliegue correcto, los registros deberían mostrar un contenido similar al siguiente:

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

Estos dos puntos son fundamentales:

- `/data/server.env` confirma que los secretos del entorno de ejecución se escriben en el volumen persistente
- `/data/storage.sqlite` confirma que la base de datos se escribe en el volumen persistente

Si aparece `/app/data/...` en su lugar, `DATA_DIR` está configurado incorrectamente y debe corregirse de inmediato.

---

## 12. Problemas comunes

### 12.1 La página `Secrets` está vacía

Normalmente, hay dos motivos:

- Aún no ha ejecutado `flyctl secrets set`
- Está viendo una aplicación diferente (p. ej., `oroute` en lugar de `omniroute`)

### 12.2 `flyctl deploy` muestra `app not found`

Cree primero la aplicación:

```powershell
flyctl apps create omniroute
```

### 12.3 Error al analizar `fly.toml`

Compruebe lo siguiente:

- Si hay caracteres ilegibles en los comentarios
- Si las comillas y la sangría de TOML son correctas

### 12.4 Los datos no persisten

Compruebe ambas condiciones:

- `fly.toml` contiene `destination = '/data'`
- `DATA_DIR` está establecido en `/data`

### 12.5 ¿Puede ejecutarse sin `INITIAL_PASSWORD`?

Sí, puede ejecutarse. En ese caso, se utilizará la contraseña predeterminada `CHANGEME`. Se recomienda cambiar la contraseña del backend lo antes posible en producción.

---

## 13. Reutilización para proyectos nuevos

Si va a desplegar un proyecto nuevo siguiendo este documento, solo necesita cambiar estos elementos:

1. Cambie el valor de `app` en `fly.toml`
2. Cambie `NEXT_PUBLIC_BASE_URL`
3. Mantenga `DATA_DIR=/data`
4. Vuelva a generar `API_KEY_SECRET`, `JWT_SECRET`, `MACHINE_ID_SALT` y `STORAGE_ENCRYPTION_KEY`
5. Tras el primer despliegue, compruebe que los registros se escriben en `/data`

No reutilice claves de un proyecto anterior.

---

## 14. Lista de comprobación mínima para las versiones del proyecto actual

Los comandos más utilizados para versiones posteriores son:

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

Para una versión normal, el comando principal es simplemente:

```powershell
flyctl deploy
```

Para un primer despliegue en un entorno nuevo, los pasos principales son:

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`