Ir al contenido
HQ Fabric

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 setup

make 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=production

El .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.com

NEXT_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 selfhost

make 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  Started

Entra 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=482913

Con 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-backup

make 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.

En esta página