HexaHost-GameCloud/docs/operations/installation.md

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

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

pnpm install

3. Start infrastructure

# 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:

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:

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

pnpm dev

5. Node agent (optional)

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

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:

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)