Configuración
Las variables de entorno del servidor, la web y el daemon, lo que cambia en producción y lo que hacen docker compose y el Makefile.
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
- Texto: si la variable está vacía, vale el valor por defecto.
- Booleanos:
1,t,trueo0,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_RUNTIMEyDOCKER_RUNTIMEaceptan tres estados:true,yes,ono1encienden;false,no,offo0apagan; cualquier otra cosa esauto, encendido fuera de producción.- Producción es exactamente
APP_ENV=production. Cualquier otro valor cuenta como desarrollo.
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 | 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
| 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 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
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_ORIGINyDOCKER_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
- Sin
JWT_SECRET, o con un valor de ejemplo, en cualquier modo. - Una entrada de
TRUSTED_PROXIESque no es una IP ni una red. - Una
DATABASE_URLque 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
| 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 se configura con $HQF_HOME/config.json y unas pocas variables. Están en la referencia del CLI:
claves de configuración y
variables de entorno.
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.
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 |