hsmod/README-dev.md

Development Environment Recommendations

This stack is most maintainable when the dev environment is repeatable and configuration is centralized. The current scripts assume Ubuntu 16.04 and hard-coded dependencies. The goal here is to make the environment predictable without touching the protocol or rewriting core services.

Key recommendations:

• Standardize the dev workflow with containers (prefer docker-compose).
• Centralize ports, credentials, and paths into a single .env file.
• Provide a single entrypoint script to build/start/stop/log services.
• Keep database and service initialization scripted and idempotent.

Focused Plan (Maintainability Only)

Phase 1: Audit and Baseline (1–3 days)

• Inventory the current scripts and dependencies in hearthmod/.
• Confirm service ports and startup order (gameserver → lobbyserver → web).
• Capture required Couchbase buckets and data seed steps.

Phase 2: Repeatable Local Environment (1–2 weeks)

• Add docker-compose.yml to orchestrate Couchbase, gameserver, lobbyserver, and web services.
• Add .env.example for all required configuration values.
• Create a single ./dev or ./scripts/dev.sh entrypoint:
  • dev build (build C services and web assets)
  • dev up (start all services)
  • dev down (stop services)
  • dev logs (tail logs)

Phase 3: Configuration Cleanup (1–2 weeks)

• Replace hard-coded ports and credentials with env-configured values.
• Add a minimal config loader in hm_web and in C servers (config file or env).
• Update nginx config to use env-substituted paths.

Phase 4: Minimal Tests + Docs (1 week)

• Add a simple smoke test script that validates service ports and Couchbase connectivity.
• Document the workflow in README-dev.md and update top-level README with a pointer.

Deliverables Checklist

• docker-compose.yml with defined services and volumes
• .env.example with required config variables
• A single dev entrypoint script
• Updated docs (this file) and a quick-start section

Non-Goals (Intentionally Deferred)

• Updating Hearthstone protocol compatibility
• Rewriting the database or switching away from Couchbase
• Migrating C services to a different language

If you want, I can start by drafting the docker-compose.yml and a dev script tailored to the current repo layout.