178 lines
5.0 KiB
Markdown
178 lines
5.0 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```plantuml
|
|
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
|
|
|
|
```json
|
|
{}
|
|
```
|
|
|
|
#### Response
|
|
|
|
```json
|
|
{
|
|
"gameId": "id",
|
|
"gameState": {
|
|
"tiles": []
|
|
}
|
|
}
|
|
```
|
|
|
|
## Configuration
|
|
|
|
Add security tokens in `server/config/local.json`:
|
|
|
|
```bash
|
|
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
|
|
```bash
|
|
curl -X POST http://localhost:8930/api/v1/games/
|
|
```
|
|
|
|
### Get Game Status
|
|
```bash
|
|
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/](https://delapouite.com/) and licensed as [CC-BY-3.0](https://creativecommons.org/licenses/by/3.0/).
|