155 lines
6.0 KiB
Markdown
155 lines
6.0 KiB
Markdown
# OpenSEO — stack self-host en Coolify
|
|
|
|
> Resuelto el **2026-08-27** contra el host real.
|
|
> Target: **LXC 102** (`coolify`), servicio compose, FQDN
|
|
> **`https://openseo.urieljareth.org`**.
|
|
> Imagen: **`ghcr.io/every-app/open-seo:sha-c469a48`** (mismo SHA que el deploy
|
|
> fallido anterior — esta vez la build de Vite sí corre, en el entrypoint).
|
|
|
|
---
|
|
|
|
## Por qué existe este stack
|
|
|
|
El deploy previo (`uuid kj0kccsb4d46tm0d6qe6docy`, `name=open-seo:main-...`,
|
|
deployment `fkojyfkqzp69hcba6miy8oer`) terminó con Coolify marcando verde y
|
|
**Caddy respondiendo 404 a todo**. Diagnóstico:
|
|
|
|
- `build_pack=railpack` clonó `every-app/open-seo@main`, construyó imagen local
|
|
con el mismo SHA `c469a48ae90ab58413b198fe3d1ac1aa90a9b070` y la cacheó.
|
|
- En el redeploy: `No build configuration changed & image found (...) Build
|
|
step skipped` → la imagen cacheada **no tenía `/app/dist`** (los artefactos
|
|
del build de Vite) y Coolify la reusó.
|
|
- Caddy (`/Caddyfile` con `root * /app/dist` + SPA fallback a `/index.html`)
|
|
no encontró nada y devolvió 404 a `/`, `/robots.txt`, `/health`.
|
|
- El README upstream lo dice textual: *"We recommend self-hosting with
|
|
Cloudflare as opposed to Railway, Coolify or Dokploy. We plan to make it
|
|
simpler to host on those platforms in the next few months."*
|
|
|
|
**Solución:** dejar de seguir upstream y consumir la **imagen prebuilt** que el
|
|
propio equipo publica en GHCR. Esa imagen tiene la cadena correcta:
|
|
`docker-entrypoint.sh` corre preflight → migrations → `pnpm run build` (que sí
|
|
genera `/app/dist`) → `vite preview` en el puerto `3001`. Y usa un fingerprint
|
|
para no reconstruir cuando los env vars relevantes no cambiaron.
|
|
|
|
Stack: **un solo servicio** (OpenSEO es self-contained: SQLite vía workerd en
|
|
`/app/.wrangler`, volumen `openseo-data`). Sin DB externa.
|
|
|
|
---
|
|
|
|
## Archivos
|
|
|
|
| Archivo | Para qué |
|
|
|---|---|
|
|
| `docker-compose.coolify.yml` | Compose que consume Coolify vía `POST /services` |
|
|
| `.env.example` | Template de env vars (sin secretos) |
|
|
| `.env.coolify` | **No committed.** Lo crea el operador con `cp .env.example .env.coolify` y rellena |
|
|
|
|
---
|
|
|
|
## Variables de entorno
|
|
|
|
Hardcoded en el compose (porque son decisión de arquitectura, no secretos):
|
|
|
|
| Var | Valor | Por qué |
|
|
|---|---|---|
|
|
| `PORT` | `3001` | Es donde escucha `vite preview` (per `Dockerfile.selfhost`) |
|
|
| `AUTH_MODE` | `local_noauth` | Single admin, sin pantalla de login. Aquí no tenemos `TEAM_DOMAIN`/`POLICY_AUD` de Cloudflare Access |
|
|
| `ALLOWED_HOST` | `openseo.urieljareth.org` | Sin esto, Vite bloquea toda petición externa con "Blocked request" |
|
|
| `CLOUDFLARE_INCLUDE_PROCESS_ENV` | `true` | Lo exige el runtime workerd para que process.env llegue a los bindings |
|
|
|
|
Suministradas vía `.env.coolify` (env vars del servicio en Coolify):
|
|
|
|
| Var | Default | Efecto |
|
|
|---|---|---|
|
|
| `DATAFORSEO_API_KEY` | vacío | **WARN** del preflight (no FAIL). Vacío = la app arranca, los workflows SEO devuelven "no data" |
|
|
| `OPENSEO_TELEMETRY_DISABLED` | `1` | Apaga el heartbeat anónimo |
|
|
| `DO_NOT_TRACK` | `1` | Alias del anterior |
|
|
| `OPENROUTER_API_KEY` | vacío | Habilita a SAM (el agente SEO integrado) si se setea |
|
|
| `OPENROUTER_MODEL` | vacío | Modelo a usar con SAM |
|
|
|
|
---
|
|
|
|
## Deploy
|
|
|
|
### 1. (Manual, una sola vez) Ingress del túnel de Cloudflare
|
|
|
|
El token de Cloudflare **no está** en `.env.local.ps1`, así que esto se hace en
|
|
el dashboard:
|
|
|
|
1. Cloudflare Zero Trust → Networks → Tunnels → tunnel `urieljareth` →
|
|
Configure → Public hostname.
|
|
2. Add a public hostname:
|
|
- Subdomain: `openseo`
|
|
- Domain: `urieljareth.org`
|
|
- Service: **HTTP** (no HTTPS, lo gestiona Coolify/Traefik)
|
|
- URL: `coolify.urieljareth.org` (o la IP interna del proxy de Coolify —
|
|
misma que usan los demás subdominios)
|
|
|
|
### 2. Crear el servicio en Coolify
|
|
|
|
```powershell
|
|
. .\.env.local.ps1
|
|
|
|
# Crear el archivo de env real (gitignored)
|
|
Copy-Item .\stacks\open-seo\.env.example .\stacks\open-seo\.env.coolify
|
|
# Editar .\stacks\open-seo\.env.coolify si quieres setear DATAFORSEO_API_KEY
|
|
|
|
.\deploy_skill\scripts\New-CoolifyService.ps1 `
|
|
-AppPath .\stacks\open-seo `
|
|
-AppName open-seo `
|
|
-Fqdn https://openseo.urieljareth.org `
|
|
-PrimaryService app `
|
|
-ProjectName "AI AGENCY" -EnvironmentName production `
|
|
-EnvFile .\stacks\open-seo\.env.coolify `
|
|
-InstantDeploy
|
|
```
|
|
|
|
### 3. Esperar al primer arranque
|
|
|
|
El primer `up` tarda **1-2 min**: preflight + migrations + vite build + arranque
|
|
de `vite preview`. Traefik no enruta hasta que el contenedor esté `healthy`.
|
|
|
|
```powershell
|
|
.\coolify_skill\scripts\Test-CoolifyServiceReady.ps1 -Uuid <uuid> -WaitSeconds 600
|
|
```
|
|
|
|
### 4. Verificar
|
|
|
|
```powershell
|
|
# 1. Endpoint público responde (TLS emitido, Traefik enrutando)
|
|
curl.exe -k -sSI https://openseo.urieljareth.org/
|
|
|
|
# 2. Status del contenedor
|
|
.\coolify_skill\scripts\Get-CoolifyDockerStatus.ps1 -Filter openseo
|
|
|
|
# 3. Logs del entrypoint (debería verse "Preflight passed")
|
|
.\scripts\Invoke-ProxmoxSsh.ps1 -Command "pct exec 102 -- docker logs <cont> --tail 60"
|
|
|
|
# 4. Preflight reporta lo que falta
|
|
.\scripts\Invoke-ProxmoxSsh.ps1 -Command "pct exec 102 -- docker exec <cont> wget -qO- http://127.0.0.1:3001/api/health"
|
|
```
|
|
|
|
---
|
|
|
|
## Rollback / limpieza
|
|
|
|
| Acción | Comando |
|
|
|---|---|
|
|
| Parar la app rota original | `docker stop kj0kccsb4d46tm0d6qe6docy-055629993145` (vía `pct exec 102 --`) |
|
|
| Borrar la app rota de Coolify | UI → Service `kj0kccsb4d46tm0d6qe6docy` → Delete |
|
|
| Re-deployar | UI → Service `open-seo` → Redeploy |
|
|
|
|
---
|
|
|
|
## Cosas que caducan
|
|
|
|
- **El tag `:sha-c469a48` se queda viejo.** Cuando el upstream publique un SHA
|
|
más reciente, actualizar el `image:` en `docker-compose.coolify.yml` y
|
|
redeployar. `v0.1.6` también existe (publicado 8 días antes).
|
|
- **El entrypoint vuelve a buildear `dist`** cada vez que algún env var del
|
|
prefijo `VITE_*` / `AUTH_MODE` / `POSTHOG_*` / `TURNSTILE_SITE_KEY` /
|
|
`BYPASS_EMAIL_VERIFICATION` cambie. Es intencional — el fingerprint está
|
|
ahí para no rehacer cuando nada relevante cambió.
|
|
- **Coolify normaliza el compose al guardarlo y borra los comentarios.** La
|
|
versión con explicaciones es la del repo, no la que se ve en la UI.
|