Ir al contenido
HQ Fabric

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, 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

VariableQué controlaPor defecto
APP_ENVEl modo: production o desarrollodevelopment
PORTPuerto de la API8080
BIND_ADDRInterfaz de escucha127.0.0.1 fuera de producción; todas en producción
DATABASE_URLLa conexión a Postgrespostgres://hqfabric:hqfabric@localhost:5432/hqfabric?sslmode=disable
JWT_SECRETFirma las sesiones. Si falta SECRETS_KEY, también cifra los secretos guardadosobligatoria; no puede ser changeme, secret ni otro valor de ejemplo
SECRETS_KEYCifra los secretos guardados en la base (AES-256-GCM), como el token de GitHubel valor de JWT_SECRET
SECRETS_KEY_OLDLa clave anterior: al arrancar, se vuelve a cifrar con SECRETS_KEY lo que siga con éstavacía
APP_URLLa URL pública de la web: enlaces en PRs y comentarios, y vuelta de la GitHub Apphttp://localhost:3000
FRONTEND_ORIGINOrígenes que admiten CORS y el WebSocket del navegador, separados por comas, en cualquier modo. Con *, CORS sin credenciales y nunca el WebSocketel valor de APP_URL
ALLOW_SIGNUPSi 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óntrue
RESEND_API_KEYEnvía los códigos de acceso por correo con Resend. Sin ella, el código va al logvacía
EMAIL_FROMEl remitente del correoHQ Fabric <noreply@example.com>
DEFAULT_LOCALEEl idioma de las cuentas nuevas: es o enes
INSTANCE_ADMINSCorreos de los administradores de la instancia, separados por comas. Con ALLOW_SIGNUP=false, los únicos que crean su cuenta sin invitaciónvacío: la primera cuenta registrada
TRUST_PROXYFiarse de X-Forwarded-For, X-Real-IP y X-Forwarded-Protofalse
TRUSTED_PROXIESDesde qué IPs o redes se aceptan esas cabeceras127.0.0.0/8 y ::1/128
PUBLIC_API_URLLa URL de la API que llega desde otras máquinas: VPS y webhooks de la GitHub Appvacía
HQF_EXTRA_HOSTSMá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 remotavacía
HOST_RUNTIMEOfrecer «Usar esta máquina» en Runtimesauto
HOST_RUNTIME_HOMELa carpeta de ese runtime~/.hqfabric/host
HQF_AGENT_ENV_ALLOWPara «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 agentesvacía
REMOTE_RUNTIMESOfrecer «Añadir VPS / EC2» (instalación por SSH)true
REMOTE_ALLOW_LOOPBACKPermitir runtimes SSH en 127.0.0.1, para pruebasfalse
HQF_DIST_DIRLa carpeta con hqf-<os>-<arch> para instalar en máquinas de otra plataformavacía; busca también bin/dist
DOCKER_RUNTIMEOfrecer «Crear runtime en Docker»auto
DOCKER_BINEl CLI de Dockerdocker del PATH
DOCKER_RUNTIME_SERVER_URLLa URL con la que los contenedores llegan a la APIhttp://host.docker.internal:<PORT>
DOCKER_RUNTIME_NETWORKLa red Docker de los contenedoresvacía
DOCKER_RUNTIME_ISOLATEQue los contenedores sólo salgan por el proxy hqf-egresstrue
CONNECTORS_ALLOW_HTTPConectores de Azure DevOps Server o Jira por http://false
CONNECTORS_ALLOW_LOOPBACKConectores en loopback, para pruebas. En producción siempre es falsefalse
GITHUB_API_URLSustituye https://api.github.com, para pruebasvací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

AspectoFuera de producciónCon APP_ENV=production
BIND_ADDR vacío127.0.0.1Todas las interfaces
HOST_RUNTIME y DOCKER_RUNTIME en autoEncendidosApagados. Con true, se encienden igual
Login sin RESEND_API_KEYEl código va al log para cualquieraSó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_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

  • 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

VariableQué controlaCuándo se leePor defecto
NEXT_PUBLIC_API_URLLa URL de la API para el navegadoral compilarhttp://localhost:8080
NEXT_PUBLIC_WS_URLLa URL de los WebSocketal compilarla de la API, con ws://
HQF_HELP_URLEl enlace «Ayuda»: una ruta propia o una URL http(s)en cada petición/ayuda
HQF_SUPPORT_EMAILEl correo de soporte; sin él no se muestraen cada peticiónvací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.

ServicioImagenPuerto en tu máquinaDatos
dbpgvector/pgvector:pg17127.0.0.1:${POSTGRES_PORT:-5432}, sólo loopbackvolumen pgdata
serverdocker/Dockerfile.server (Go 1.25, Alpine)${SERVER_PORT:-8080}, todas las interfaces—
webdocker/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

ObjetivoQué hace
make setupSi 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 dbdocker compose up -d db
make devmake 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-serverSólo el servidor
make dev-webSólo la web
make buildCompila bin/server, bin/hqf y la web
make cliCompila bin/hqf
make distCompila hqf para Linux y macOS, amd64 y arm64, en bin/dist
make selfhostmake setup y docker compose up -d --build
make selfhost-stopdocker compose down
make db-backupCopia de la base en backups/hqfabric-<fecha>.dump (pg_dump -Fc)
make testgo vet y las pruebas Go sin red fuera de 127.0.0.1. Necesita macOS (sandbox-exec)
make docsEste sitio en desarrollo, en http://localhost:3001
make docs-buildCompila este sitio; se sirve con cd apps/docs && pnpm start

En esta página