initial commit

docs/operations/installation.md

@@ -0,0 +1,112 @@
+# 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)