176 lines
4.5 KiB
Markdown
176 lines
4.5 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
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
./launch.sh build
|
|
```
|
|
|
|
Or using docker compose directly (explicit project and files):
|
|
|
|
```bash
|
|
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
|
|
|
|
```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/).
|