Ir al contenido
HQ Fabric

Instalar HQ Fabric en tu máquina

Levanta el servidor, la base de datos y la web en local, y entra con tu primer workspace.

En unos minutos tendrás el servidor, la base de datos y la web corriendo en tu máquina. Es la forma de probar HQ Fabric y de trabajar en su código. Para un servidor que use tu equipo, sigue Autoalojar con Docker.

Antes de empezar

  • Go 1.25 o más nuevo.
  • Node.js 22 y pnpm.
  • Docker, para PostgreSQL.
  • git 2.45.1 o más nuevo. El daemon no arranca con uno más viejo.
  • openssl, que make setup usa para generar los secretos.
  • Los puertos 5432, 8080 y 3000 libres.

Pasos

Clona el repositorio

git clone https://github.com/jarciahdz111/hqfabric.git
cd hqfabric

Crea la configuración e instala las dependencias

make setup

Si no hay un .env, lo copia de .env.example con tres secretos aleatorios: JWT_SECRET, SECRETS_KEY y la contraseña de PostgreSQL. Si ya existe, no lo toca. Después instala las dependencias de la web (pnpm install) y de Go (go mod download).

✔ .env creado con JWT_SECRET, SECRETS_KEY y POSTGRES_PASSWORD aleatorios

El .env queda en desarrollo (APP_ENV=development).

Arranca todo

make dev

Levanta PostgreSQL en Docker (docker compose up -d db) y, en paralelo, el servidor y la web. El servidor aplica las migraciones al arrancar y escucha en 127.0.0.1:8080:

level=INFO msg="applied migration" name=048_tareas_base_sha.sql
level=INFO msg="HQ Fabric server listening" addr=127.0.0.1:8080 env=development version=0.1.0

La web queda en http://127.0.0.1:3000. Ctrl+C para los dos.

Entra con tu correo

Abre http://127.0.0.1:3000. Escribe tu correo en Correo de trabajo y pulsa Enviar código. Sin correo configurado, el servidor no lo envía: la web te avisa de que el código está en los logs. Búscalo en la terminal de make dev, en la línea Verification code, junto a tu correo, y pulsa Entrar.

Con el registro abierto (ALLOW_SIGNUP=true, por defecto), un correo nuevo crea su cuenta al entrar. Escríbelo bien: una errata crea otra cuenta.

Crea tu primer workspace

La web te lleva a Crea tu primer workspace. Pon un Nombre y un Prefijo de issues (por ejemplo, HQF para issues como HQF-1) y pulsa Crear workspace. Un workspace agrupa a tu equipo, tus agentes, tus proyectos y su Malla de Contexto. Quien lo crea es su owner.

Comprueba que funciona

El servidor responde en /healthz y dice si llega a la base de datos:

curl -s http://127.0.0.1:8080/healthz
{"checks":{"db":"ok"},"status":"ok"}

Si algo falla

  • El servidor no arranca y no dice por qué. Si el puerto 8080 está ocupado, el servidor se apaga con código 0. Mira qué lo usa (lsof -i :8080) o cambia PORT en el .env.
  • No llega a la base de datos. El servidor reintenta durante unos 60 s y sale. Comprueba que Docker corre y que docker compose ps muestra db sano.
  • El código no vale. Usa el último que salió en el log del servidor para tu correo: al pedir otro, el anterior deja de valer.

Siguiente paso

Conecta tu máquina como runtime y lanza tu primera tarea.

En esta página