113 lines
2.4 KiB
Markdown
113 lines
2.4 KiB
Markdown
# 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)
|