# Configuración (/docs/referencia/configuracion)

El servidor lee su configuración una vez, al arrancar, de variables de entorno. Con `make dev` salen del `.env` de la
raíz del repo; con docker compose, compose las interpola desde ese mismo `.env`. Esta referencia sale de
`internal/config/config.go`, no del `.env.example`: donde el ejemplo se queda corto, lo dice.

Sólo una variable es obligatoria, en cualquier modo: `JWT_SECRET`. `make setup` la genera.

## Cómo se leen [#cómo-se-leen]

- **Texto**: si la variable está vacía, vale el valor por defecto.
- **Booleanos**: `1`, `t`, `true` o `0`, `f`, `false`, en mayúsculas o minúsculas. Cualquier otro valor (`yes`,
  `on`, `no`) se ignora sin avisar y deja el valor por defecto.
- **`HOST_RUNTIME` y `DOCKER_RUNTIME`** aceptan tres estados: `true`, `yes`, `on` o `1` encienden; `false`, `no`,
  `off` o `0` apagan; cualquier otra cosa es `auto`, encendido fuera de producción.
- **Producción** es exactamente `APP_ENV=production`. Cualquier otro valor cuenta como desarrollo.

## El servidor [#el-servidor]

| Variable | Qué controla | Por defecto |
|---|---|---|
| `APP_ENV` | El modo: `production` o desarrollo | `development` |
| `PORT` | Puerto de la API | `8080` |
| `BIND_ADDR` | Interfaz de escucha | `127.0.0.1` fuera de producción; todas en producción |
| `DATABASE_URL` | La conexión a Postgres | `postgres://hqfabric:hqfabric@localhost:5432/hqfabric?sslmode=disable` |
| `JWT_SECRET` | Firma las sesiones. Si falta `SECRETS_KEY`, también cifra los secretos guardados | obligatoria; no puede ser `changeme`, `secret` ni otro valor de ejemplo |
| `SECRETS_KEY` | Cifra los secretos guardados en la base (AES-256-GCM), como el token de GitHub | el valor de `JWT_SECRET` |
| `SECRETS_KEY_OLD` | La clave anterior: al arrancar, se vuelve a cifrar con `SECRETS_KEY` lo que siga con ésta | vacía |
| `APP_URL` | La URL pública de la web: enlaces en PRs y comentarios, y vuelta de la GitHub App | `http://localhost:3000` |
| `FRONTEND_ORIGIN` | Orígenes que admiten CORS y el WebSocket del navegador, separados por comas, en cualquier modo. Con `*`, CORS sin credenciales y nunca el WebSocket | el valor de `APP_URL` |
| `ALLOW_SIGNUP` | Si un correo nuevo puede registrarse. Con `false`, sólo los correos de `INSTANCE_ADMINS` crean su cuenta (así se crea la primera); el resto entra por invitación | `true` |
| `RESEND_API_KEY` | Envía los códigos de acceso por correo con Resend. Sin ella, el código va al log | vacía |
| `EMAIL_FROM` | El remitente del correo | `HQ Fabric <noreply@example.com>` |
| `DEFAULT_LOCALE` | El idioma de las cuentas nuevas: `es` o `en` | `es` |
| `INSTANCE_ADMINS` | Correos de los administradores de la instancia, separados por comas. Con `ALLOW_SIGNUP=false`, los únicos que crean su cuenta sin invitación | vacío: la primera cuenta registrada |
| `TRUST_PROXY` | Fiarse de `X-Forwarded-For`, `X-Real-IP` y `X-Forwarded-Proto` | `false` |
| `TRUSTED_PROXIES` | Desde qué IPs o redes se aceptan esas cabeceras | `127.0.0.0/8` y `::1/128` |
| `PUBLIC_API_URL` | La URL de la API que llega desde otras máquinas: VPS y webhooks de la GitHub App | vacía |
| `HQF_EXTRA_HOSTS` | Más nombres de este servidor para la cabecera `Host`, exactos y separados por comas, sin comodines: p. ej. el nombre con el que llega una máquina remota | vacía |
| `HOST_RUNTIME` | Ofrecer «Usar esta máquina» en Runtimes | `auto` |
| `HOST_RUNTIME_HOME` | La carpeta de ese runtime | `~/.hqfabric/host` |
| `HQF_AGENT_ENV_ALLOW` | Para «Usar esta máquina»: nombres de variables del entorno del servidor que pasan a su daemon, a los agentes y a la verificación. Los secretos del servidor, nunca. Ver [qué entorno reciben los agentes](/docs/referencia/cli#qué-entorno-reciben-los-agentes) | vacía |
| `REMOTE_RUNTIMES` | Ofrecer «Añadir VPS / EC2» (instalación por SSH) | `true` |
| `REMOTE_ALLOW_LOOPBACK` | Permitir runtimes SSH en 127.0.0.1, para pruebas | `false` |
| `HQF_DIST_DIR` | La carpeta con `hqf-<os>-<arch>` para instalar en máquinas de otra plataforma | vacía; busca también `bin/dist` |
| `DOCKER_RUNTIME` | Ofrecer «Crear runtime en Docker» | `auto` |
| `DOCKER_BIN` | El CLI de Docker | `docker` del `PATH` |
| `DOCKER_RUNTIME_SERVER_URL` | La URL con la que los contenedores llegan a la API | `http://host.docker.internal:<PORT>` |
| `DOCKER_RUNTIME_NETWORK` | La red Docker de los contenedores | vacía |
| `DOCKER_RUNTIME_ISOLATE` | Que los contenedores sólo salgan por el proxy `hqf-egress` | `true` |
| `CONNECTORS_ALLOW_HTTP` | Conectores de Azure DevOps Server o Jira por `http://` | `false` |
| `CONNECTORS_ALLOW_LOOPBACK` | Conectores en loopback, para pruebas. En producción siempre es `false` | `false` |
| `GITHUB_API_URL` | Sustituye `https://api.github.com`, para pruebas | vacía |

`PORT`, `CONNECTORS_ALLOW_HTTP`, `CONNECTORS_ALLOW_LOOPBACK` y `GITHUB_API_URL` no están en `.env.example`. El
`SERVER_PORT` del ejemplo no es el puerto del servidor: lo usa docker compose para publicar el puerto en tu máquina.

## Qué cambia en producción [#qué-cambia-en-producción]

| Aspecto | Fuera de producción | Con `APP_ENV=production` |
|---|---|---|
| `BIND_ADDR` vacío | `127.0.0.1` | Todas las interfaces |
| `HOST_RUNTIME` y `DOCKER_RUNTIME` en `auto` | Encendidos | Apagados. Con `true`, se encienden igual |
| Login sin `RESEND_API_KEY` | El código va al log para cualquiera | Sólo se genera, y va al log, el de los administradores de la instancia o el de la primera cuenta. La respuesta es la misma para cualquier correo |

En cualquier modo, el servidor avisa al arrancar, sin pararse, si `APP_URL` o `PUBLIC_API_URL` no son `https://`
(salvo en loopback), si `SECRETS_KEY` falta o es igual a `JWT_SECRET`, si `FRONTEND_ORIGIN` incluye `*`, si la
contraseña de la base es `hqfabric`, si la base está en otra máquina sin `sslmode`, si una entrada de
`HQF_EXTRA_HOSTS` no es un nombre exacto, o si `ALLOW_SIGNUP=false` va sin `INSTANCE_ADMINS`. En producción, además,
si `TRUST_PROXY` está apagado.

## Pedir un código de acceso [#pedir-un-código-de-acceso]

Pedir un código responde lo mismo para cualquier correo, tenga cuenta o no y sea o no de un administrador, y responde
antes de enviarlo: ni la respuesta ni lo que tarda dicen si una cuenta existe. Sólo se rechaza antes un correo mal
escrito (400) o el exceso de peticiones desde una IP (429). Lo demás se decide después, sin cambiar la respuesta: si
ese correo puede entrar (con el registro cerrado, sólo una cuenta que existe o un correo de `INSTANCE_ADMINS`), el tope
de 5 códigos por correo cada 10 minutos, el de la instancia por hora (los administradores lo saltan) y el envío. Si el
correo no puede entrar o pasó un tope, no se envía nada. Un fallo al enviar queda en el log del servidor.

## Qué nombres atiende el servidor [#qué-nombres-atiende-el-servidor]

La API comprueba la cabecera `Host` antes que nada, en cualquier modo. Con otro nombre responde 421
`host_not_allowed`. Así, una página web que haga apuntar su dominio a tu máquina (DNS rebinding) no habla con la API.
Atiende:
- `localhost`, sus subdominios y cualquier dirección IP;
- los nombres de `APP_URL`, `PUBLIC_API_URL`, `FRONTEND_ORIGIN` y `DOCKER_RUNTIME_SERVER_URL`;
- los nombres de `HQF_EXTRA_HOSTS`.

Si un daemon llega por otro nombre, ponlo en `HQF_EXTRA_HOSTS`. La URL del servidor que se escribe al añadir un
runtime remoto o de Docker no cuenta: la escribe el administrador de un workspace, y no amplía la lista de toda la
instancia. Cuando la API rechaza un nombre, el log lo dice, con el nombre y dónde se añade: `Host rechazado (421)`.
Como mucho un aviso cada 10 segundos, con la cuenta de los que se callaron.

## Lo que impide arrancar [#lo-que-impide-arrancar]

- Sin `JWT_SECRET`, o con un valor de ejemplo, en cualquier modo.
- Una entrada de `TRUSTED_PROXIES` que no es una IP ni una red.
- Una `DATABASE_URL` que no se puede leer.
- Postgres sin responder durante unos 60 s (30 intentos, cada 2 s).
- Una migración que falla. Las migraciones se aplican solas al arrancar.

Si el puerto está ocupado, el servidor se apaga **con código 0**. Un supervisor que sólo reinicia ante fallo no lo
levanta: revisa el log.

## La web [#la-web]

| Variable | Qué controla | Cuándo se lee | Por defecto |
|---|---|---|---|
| `NEXT_PUBLIC_API_URL` | La URL de la API para el navegador | al compilar | `http://localhost:8080` |
| `NEXT_PUBLIC_WS_URL` | La URL de los WebSocket | al compilar | la de la API, con `ws://` |
| `HQF_HELP_URL` | El enlace «Ayuda»: una ruta propia o una URL `http(s)` | en cada petición | `/ayuda` |
| `HQF_SUPPORT_EMAIL` | El correo de soporte; sin él no se muestra | en cada petición | vacío |

Las dos primeras quedan dentro del código compilado de la web: si las cambias, vuelve a compilar. `make dev` y
`make build` no le pasan el `.env` de la raíz a la web: allí valen las de tu shell o las de `apps/web/.env*`.

## El daemon y el CLI [#el-daemon-y-el-cli]

El daemon se configura con `$HQF_HOME/config.json` y unas pocas variables. Están en la referencia del CLI:
[claves de configuración](/docs/referencia/cli#claves-de-configuración) y
[variables de entorno](/docs/referencia/cli#variables-de-entorno).

## docker compose [#docker-compose]

`docker-compose.yml` define tres servicios en el proyecto `hqfabric`.

| Servicio | Imagen | Puerto en tu máquina | Datos |
|---|---|---|---|
| `db` | `pgvector/pgvector:pg17` | `127.0.0.1:${POSTGRES_PORT:-5432}`, sólo loopback | volumen `pgdata` |
| `server` | `docker/Dockerfile.server` (Go 1.25, Alpine) | `${SERVER_PORT:-8080}`, todas las interfaces | — |
| `web` | `docker/Dockerfile.web` (Node 22) | `${WEB_PORT:-3000}`, todas las interfaces | — |

Al contenedor `server` sólo le llegan trece variables: `APP_ENV` (fijo en `production`, aunque el `.env` diga otra
cosa), `PORT` (fijo en 8080), `DATABASE_URL` (construida con las `POSTGRES_*` y el host `db`), `JWT_SECRET`,
`SECRETS_KEY`, `APP_URL`, `FRONTEND_ORIGIN`, `ALLOW_SIGNUP`, `INSTANCE_ADMINS`, `HQF_EXTRA_HOSTS`, `RESEND_API_KEY`, `EMAIL_FROM`
y `DEFAULT_LOCALE`. Las demás, como `TRUST_PROXY`, `PUBLIC_API_URL` o `SECRETS_KEY_OLD`, no llegan aunque las pongas en
el `.env`: hay que añadirlas a `docker-compose.yml`.

El servidor de compose arranca siempre en producción, aunque el `.env` que crea `make setup` diga `development`: así
no le llegan ni el código fijo de desarrollo ni la escucha sólo en `127.0.0.1`. Los pasos están en
[Autoalojar con Docker](/docs/empezar/autoalojar-con-docker).

## El Makefile [#el-makefile]

| Objetivo | Qué hace |
|---|---|
| `make setup` | Si no hay `.env`, lo copia de `.env.example` con `JWT_SECRET`, `SECRETS_KEY` y la contraseña de Postgres aleatorias. Después, siempre, `pnpm install` en `apps/web` y `go mod download` |
| `make db` | `docker compose up -d db` |
| `make dev` | `make db` y, en paralelo, el servidor (`go run ./cmd/server` con el `.env`) y la web (`next dev` en `127.0.0.1:3000`). Ctrl+C para los dos |
| `make dev-server` | Sólo el servidor |
| `make dev-web` | Sólo la web |
| `make build` | Compila `bin/server`, `bin/hqf` y la web |
| `make cli` | Compila `bin/hqf` |
| `make dist` | Compila `hqf` para Linux y macOS, amd64 y arm64, en `bin/dist` |
| `make selfhost` | `make setup` y `docker compose up -d --build` |
| `make selfhost-stop` | `docker compose down` |
| `make db-backup` | Copia de la base en `backups/hqfabric-<fecha>.dump` (`pg_dump -Fc`) |
| `make test` | `go vet` y las pruebas Go sin red fuera de 127.0.0.1. Necesita macOS (`sandbox-exec`) |
| `make docs` | Este sitio en desarrollo, en `http://localhost:3001` |
| `make docs-build` | Compila este sitio; se sirve con `cd apps/docs && pnpm start` |