Autoalojar HQ Fabric con Docker
Levanta la base de datos, el servidor y la web en contenedores, en modo producción.
Con docker compose levantas los tres servicios de HQ Fabric en una máquina: PostgreSQL, el servidor y la web. Es lo
que usarías para un servidor de tu equipo. Los agentes no corren en estos contenedores: corren en los runtimes que
conectes después, con el daemon hqf.
Antes de arrancar, cambia una línea del .env. Sin ella, la API no responde.
Antes de empezar
- Docker con docker compose.
- openssl y, para
make setup, pnpm y Go (instala también las dependencias de desarrollo). - Los puertos 8080 y 3000 libres. PostgreSQL sólo se publica en
127.0.0.1:5432.
Pasos
Crea el .env
git clone https://github.com/jarciahdz111/hqfabric.git
cd hqfabric
make setupmake setup crea el .env con JWT_SECRET, SECRETS_KEY y la contraseña de PostgreSQL aleatorias. Compose las
lee de ahí.
Ponlo en producción
Abre el .env y cambia APP_ENV:
APP_ENV=productionEl .env de make setup dice development, y compose usa ese valor. En desarrollo, el servidor sólo escucha en
127.0.0.1 dentro de su contenedor, y el puerto que compose publica no le llega: la conexión se corta. En producción
escucha en todas las interfaces del contenedor.
Si la web no va a estar en http://localhost:3000, cambia también estas, con tus URLs:
APP_URL=https://hqfabric.tu-dominio.com
FRONTEND_ORIGIN=https://hqfabric.tu-dominio.com
NEXT_PUBLIC_API_URL=https://api.hqfabric.tu-dominio.com
NEXT_PUBLIC_WS_URL=wss://api.hqfabric.tu-dominio.comNEXT_PUBLIC_API_URL y NEXT_PUBLIC_WS_URL quedan dentro de la imagen de la web al compilarla: si las cambias
después, vuelve a construirla.
Configura el correo, o usa el log
En producción, los códigos de acceso se mandan por correo con Resend. Pon tu clave:
RESEND_API_KEY=re_…
EMAIL_FROM=HQ Fabric <hqfabric@tu-dominio.com>Sin RESEND_API_KEY, el código va al log del servidor, pero sólo el del administrador de la instancia o el de la
primera cuenta: al resto no se le crea código, aunque la respuesta sea la misma. Así puedes entrar tú primero y
configurar el correo después. Con ALLOW_SIGNUP=false, pon tu correo en INSTANCE_ADMINS: es la única forma de crear
la primera cuenta con el registro cerrado.
Levanta los contenedores
make selfhostmake selfhost repite make setup, que no toca un .env que ya existe, y hace docker compose up -d --build. La
primera vez construye las imágenes del servidor y de la web, y tarda unos minutos.
Container hqfabric-db-1 Healthy
Container hqfabric-server-1 Started
Container hqfabric-web-1 StartedEntra y crea tu workspace
Abre la web (http://localhost:3000, o tu APP_URL) y pide un código con tu correo. Sin correo configurado, búscalo
en el log del servidor:
docker compose logs server | grep 'Verification code'server-1 | level=WARN msg="Verification code (configure RESEND_API_KEY to send real emails)" email=ana@hqfabric.example code=482913Con el código, entra y crea tu primer workspace.
Comprueba que funciona
curl -s http://localhost:8080/healthz
curl -s http://localhost:8080/api/config{"checks":{"db":"ok"},"status":"ok"}
{"allow_signup":true,"default_locale":"es","dev_code_hint":false,"email_configured":false,"version":"0.1.0"}dev_code_hint en false confirma que estás en producción. Al arrancar, el servidor avisa en el log de lo que
conviene revisar en un despliegue (deployment security). Con esta configuración salen dos avisos: TRUST_PROXY no
está activo, y la base de datos va sin sslmode, porque compose la conecta por la red interna.
Lo que compose no pasa al servidor
Al contenedor del servidor sólo le llegan doce variables del .env. TRUST_PROXY, TRUSTED_PROXIES,
INSTANCE_ADMINS, PUBLIC_API_URL, SECRETS_KEY_OLD y las de los runtimes no llegan aunque las escribas: añádelas a
la sección environment del servicio server en docker-compose.yml. Lo necesitas, por ejemplo, para poner un proxy
con TLS delante (TRUST_PROXY) o para fijar quién administra la instancia (INSTANCE_ADMINS). La lista completa
está en Configuración.
Parar y respaldar
make selfhost-stop
make db-backupmake selfhost-stop para los contenedores y conserva los datos en el volumen pgdata. make db-backup guarda una
copia de la base en backups/ con la fecha; la base tiene que estar en marcha. Haz una antes de actualizar: las
migraciones se aplican solas cuando el servidor nuevo arranca.
Siguiente paso
Conecta una máquina como runtime y lanza tu primera tarea.