peddlers-of-ketran/README.md

Peddlers of Ketran

This project consists of both the front-end React client and back-end Node.js game API server for the Settlers of Catan-style board game.

The application is designed to run inside Docker containers. Do not run npm install or modify node_modules locally, as this can create environment drift. All development and building should be done through the provided Docker workflows.

Development and Production

The application can be launched in development or production mode by setting the PRODUCTION environment variable.

• Set PRODUCTION=0 (or leave unset) for development mode: hot-reloading server and client.
• Set PRODUCTION=1 for production mode: static built site served by the server.

Prerequisites

• Docker
• Docker Compose

Launching (using docker compose)

This project runs directly with the Docker Compose CLI from the repository root. Examples:

# Development (hot-reload client/server)
PRODUCTION=0 docker compose up -d --profile dev

# Production (static build served by the server)
PRODUCTION=1 docker compose up -d --profile prod

# Tail logs for the client/service
docker compose logs -f peddlers-client

# Show running services
docker compose ps

# Stop everything and remove orphans
docker compose down --remove-orphans

# Build images
docker compose build

### Ensuring container-created files match your host UID/GID

When running containers that mount the workspace (dev/test), files created by the container may be owned by root which can be inconvenient on the host. To avoid this, images in this repo accept build-time args `HOST_UID` and `HOST_GID` and create a matching user inside the image. Set these to your current UID/GID before building so runtime-created files use your ownership.

Example (bash):

```bash
export HOST_UID=$(id -u)
export HOST_GID=$(id -g)
# Build images with the host UID/GID baked in
docker compose build peddlers-test peddlers-of-ketran peddlers-client peddlers-of-ketran-dev

# Then run in dev mode as usual (hot-reload):
PRODUCTION=0 docker compose up -d --profile dev

If you prefer to set these in .env, add HOST_UID=... and HOST_GID=... to the file in the repo root.

#### Development Mode

When `PRODUCTION=0`:
- Server runs with hot-reloading via `ts-node-dev` on port 8930
- Client runs with React hot module replacement on port 3001 (HTTPS)
- Client proxies API calls to the server
- Both services run in separate containers with mounted source directories

Open `https://localhost:3001` in your browser for the client. Changes to server or client code will trigger automatic reloads.

#### Production Mode

When `PRODUCTION=1`:
- Builds static client files and serves them directly from the Node.js server
- Server runs compiled TypeScript from `dist/` on port 8930
- No hot-reloading; requires rebuild for changes
- Database mounted for persistence

The application will be available at `http://localhost:8930`.

### Building (for Production)

To manually build the production image:

```bash
docker compose build peddlers-of-ketran

Environment Variables

Create a .env file in the project root with any required environment variables. Recommended variables used by the repository tooling:

• COMPOSE_PROJECT_NAME (optional) — project name to be used by docker compose. Defaults to peddlers-of-ketran in this repo helper.
• COMPOSE_FILE (optional) — colon-delimited list of compose files. Example: docker-compose.yml:docker-compose.dev.yml.
• PRODUCTION — set to 1 for production profile, 0 (or unset) for development.

The repository already appends these to .env for convenience. If you prefer to manage them yourself, remove or edit those lines in .env.

Architecture

skinparam componentStyle rectangle

component "Server" as server
component "Resources" as res
component "Client" as client
component "Game" as game
component "Player" as player

package "Game" as game {
  component Players as players
}

server <-> resource : serves static files to client
client <-> server : API calls
player <-> client
players -r-> player
server -> game

API Documentation

POST /api/v1/game

Request

{}

Response

{
  "gameId": "id",
  "gameState": {
    "tiles": []
  }
}

Configuration

Add security tokens in server/config/local.json:

cat << EOF > server/config/local.json
{
  "tokens": [ {
    "$(whoami)": "$(< /dev/urandom tr -dc _A-Z-a-z-0-9 | head -c${1:-32};echo;)"
  } ]
}
EOF

Testing

Create New Game

curl -X POST http://localhost:8930/api/v1/games/

Get Game Status

curl -X GET http://localhost:8930/api/v1/games/:id

Game States

• Lobby: Players register, choose colors, roll for position, set ready
• Active: Gameplay phase

Chat is available at all times for registered players.

License Attribution

The dice faces (dice-six-faces-*.svg) are Copyright https://delapouite.com/ and licensed as CC-BY-3.0.