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

# For development (hot-reload)
PRODUCTION=0 ./launch.sh

# For production (static build)
PRODUCTION=1 ./launch.sh

The repository includes a helper script launch.sh that wraps docker compose with sane defaults for this project. It sets a stable compose project name and the common compose files so you can run commands from the repo root without extra flags.

Common examples:

# Start the development stack (hot-reload client/server)
./launch.sh up

# Tail logs for the client
./launch.sh logs peddlers-client

# Show running services
./launch.sh ps

# Stop everything
./launch.sh down

# Build images (no cache)
./launch.sh build

# Start production mode (uses the 'prod' profile)
./launch.sh --production up

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)

If you need to manually build the production image, use the helper which ensures the correct compose files and project name are used:

./launch.sh build

Or using docker compose directly (explicit project and files):

docker compose -p peddlers-of-ketran -f docker-compose.yml -f docker-compose.dev.yml build

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.