# Instalar HQ Fabric en tu máquina (/docs/empezar/instalacion-local)

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](/docs/empezar/autoalojar-con-docker).

## Antes de empezar [#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 [#pasos]

<Steps>
<Step>
### Clona el repositorio [#clona-el-repositorio]

```bash
git clone https://github.com/jarciahdz111/hqfabric.git
cd hqfabric
```
</Step>

<Step>
### Crea la configuración e instala las dependencias [#crea-la-configuración-e-instala-las-dependencias]

```bash
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`).

```text
✔ .env creado con JWT_SECRET, SECRETS_KEY y POSTGRES_PASSWORD aleatorios
```

El `.env` queda en desarrollo (`APP_ENV=development`).
</Step>

<Step>
### Arranca todo [#arranca-todo]

```bash
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`:

```text
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.
</Step>

<Step>
### Entra con tu correo [#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.
</Step>

<Step>
### Crea tu primer workspace [#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.
</Step>
</Steps>

## Comprueba que funciona [#comprueba-que-funciona]

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

```bash
curl -s http://127.0.0.1:8080/healthz
```

```json
{"checks":{"db":"ok"},"status":"ok"}
```

## Si algo falla [#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 [#siguiente-paso]

Conecta tu máquina como runtime y lanza [tu primera tarea](/docs/empezar/primera-tarea).