191 lines
4.3 KiB
Markdown
191 lines
4.3 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
|
|
|
|
For live development with hot reloading, React DevTools support, and TypeScript compilation on-the-fly.
|
|
|
|
### Prerequisites
|
|
|
|
- Docker
|
|
- Docker Compose
|
|
|
|
### Running the Server (Backend)
|
|
|
|
The server uses TypeScript with hot reloading via `ts-node-dev`.
|
|
|
|
```bash
|
|
docker compose -f docker-compose.dev.yml up
|
|
```
|
|
|
|
This will:
|
|
- Build the server container using `Dockerfile.server`
|
|
- Mount the `server/` directory for live code changes
|
|
- Run `npm run start:dev` which uses `ts-node-dev` for hot reloading
|
|
- Expose the server on port 8930
|
|
|
|
### Testing the Server
|
|
|
|
The server uses Jest for unit testing. Tests are located in `server/tests/`.
|
|
|
|
To run tests:
|
|
|
|
```bash
|
|
docker compose run --rm server npm test
|
|
```
|
|
|
|
This will run all test files matching `*.test.ts` in the `server/tests/` directory.
|
|
|
|
To run tests in watch mode:
|
|
|
|
```bash
|
|
docker compose run --rm server npm run test:watch
|
|
```
|
|
|
|
Note: If you add `test:watch` script, but for now, it's just `test`.
|
|
|
|
### Running the Client (Frontend)
|
|
|
|
The client is a React application with hot reloading and debug support.
|
|
|
|
```bash
|
|
docker compose -f docker-compose.client.dev.yml up
|
|
```
|
|
|
|
This will:
|
|
- Mount the `client/` directory for live code changes
|
|
- Run `npm start` in development mode
|
|
- Enable React DevTools and hot module replacement
|
|
- Expose the client on port 3001 (HTTPS)
|
|
- Proxy API calls to the server at `http://host.docker.internal:8930`
|
|
|
|
### Full Development Stack
|
|
|
|
To run both server and client together:
|
|
|
|
```bash
|
|
# Terminal 1: Server
|
|
docker compose -f docker-compose.dev.yml up
|
|
|
|
# Terminal 2: Client
|
|
docker compose -f docker-compose.client.dev.yml up
|
|
```
|
|
|
|
Open `https://localhost:3001` in your browser. The client will hot-reload on code changes, and the server will restart automatically on backend changes.
|
|
|
|
## Production
|
|
|
|
For production deployment, the client is built as static files and served directly by the Node.js server.
|
|
|
|
### Building
|
|
|
|
```bash
|
|
docker compose build
|
|
```
|
|
|
|
This builds the production image using `Dockerfile`, which:
|
|
- Installs server dependencies and builds TypeScript to `dist/`
|
|
- Installs client dependencies and builds static files to `client/build/`
|
|
- Copies the built client files to be served by the server
|
|
|
|
### Running
|
|
|
|
```bash
|
|
docker compose up
|
|
```
|
|
|
|
This will:
|
|
- Start the server on port 8930
|
|
- Serve the built client static files
|
|
- Mount the `db/` directory for persistent database storage
|
|
- Mount `server/routes/` for dynamic route files
|
|
|
|
The application will be available at `http://localhost:8930`.
|
|
|
|
### Environment Variables
|
|
|
|
Create a `.env` file in the project root with any required environment variables. The server start script loads these via `export $(cat ../.env | xargs)`.
|
|
|
|
## 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/).
|