# Local development installation

This guide covers setting up HexaHost GameCloud on a single machine for development.

## Prerequisites

| Tool | Version |
|------|---------|
| Node.js | 22.x |
| pnpm | 9.x |
| Go | 1.23+ |
| Docker Engine | 24+ |
| Docker Compose | v2 |

Optional:

- `make` (for node-agent)
- Traefik with external network `traefik-network`

## 1. Clone and configure

```bash
git clone <repository-url> hexahost-gamecloud
cd hexahost-gamecloud
cp .env.example .env
```

Edit `.env` and set at minimum:

- `SESSION_SECRET` and `ENCRYPTION_KEY` — generate with `openssl rand -base64 32`
- `DATABASE_URL`, `REDIS_URL` — defaults work with compose
- `NODE_ID` — any unique string for local agent testing

## 2. Install dependencies

```bash
pnpm install
```

## 3. Start infrastructure

```bash
# Optional: create Traefik network if using external routing
docker network create traefik-network 2>/dev/null || true

# Start PostgreSQL, Redis, MinIO, Mailpit, API, Worker, Web
docker compose -f deploy/compose/compose.dev.yml --env-file .env up -d
```

Verify health:

```bash
curl -s http://localhost:3001/healthz
curl -s http://localhost:3000/api/health
```

Mailpit UI: http://localhost:8025  
MinIO console: http://localhost:9001 (default `minioadmin` / `minioadmin`)

## 4. Run applications locally (without Docker)

Alternatively, run only infrastructure in Docker and apps on the host:

```bash
docker compose -f deploy/compose/compose.dev.yml --env-file .env up -d postgres redis minio mailpit

pnpm dev
```

## 5. Node agent (optional)

```bash
cd apps/node-agent
export NODE_ID=local-dev-node
export NODE_AGENT_PUBLIC_URL=ws://localhost:3001/api/v1/nodes/ws
make build
make run
```

Health: http://localhost:9100/healthz

## 6. Quality checks

```bash
pnpm lint
pnpm typecheck
pnpm test
cd apps/node-agent && make test
```

## Troubleshooting

### `traefik-network` not found

Either create the network (`docker network create traefik-network`) or remove the external network from compose for pure local dev.

### Port conflicts

Adjust `API_PORT`, `WEB_PORT`, `POSTGRES_PORT`, `REDIS_PORT` in `.env`.

### MinIO bucket missing

The `minio-init` service creates the bucket on first start. Restart compose if it failed:

```bash
docker compose -f deploy/compose/compose.dev.yml up minio-init
```

## Next steps

- Phase 1: database migrations and authentication — see `docs/IMPLEMENTATION_STATUS.md`
- Production deployment: `deploy/traefik/`, `deploy/ansible/` (Phase 9)