Awesome
<p align="center"> <img src="https://github.com/antoinezanardi/werewolves-assistant-api-next/blob/main/public/assets/images/logo/full/werewolves-logo.png?raw=true" width="400" alt="logo"/> </p>
๐ Table of Contents
- ๐บ What is this API ?
- โจ Production and development links
- ๐ Available roles
- ๐จ Installation
- ๐ Build
- ๐ณ Docker
- ๐ฏ Tests
- ๐ฟ Env variables
- โ๏ธ Code analysis and consistency
- ๐ Releases & Changelog
- ๐ GitHub Actions
- โจ Misc commands
- ยฉ๏ธ License
- โค๏ธ Contributors
<a name="what-is-this-api">๐บ What is this API ?</a>
Werewolves Assistant API provides over HTTP requests a way of manage Werewolves games to help the game master.
This is the next version of the deprecated Werewolves Assistant API.
This API is used by the Werewolves Assistant Web App.
๐ค Want to know more about this awesome project ? <a href="https://werewolves-assistant.com/about" target="_blank">Check out the dedicated about page</a>.
<a name="production-and-development-urls">โจ Production and development links</a>
๐ Production
The production version of this API is available at api.werewolves-assistant.com.
This API is used by the Werewolves Assistant Web App.
The production server is updated automatically with the latest version of the API when a new release is created. (When a new tag is pushed on the main
branch)
๐ ๏ธ Development
The development version of this API is available at preprod.api.werewolves-assistant.com.
This API is used by the Werewolves Assistant Web App.
The development server is updated automatically when a commit is pushed on the develop
branch.
<a name="available-roles">๐ Available roles</a>
30 different official roles are available to play :
<img src="https://github.com/antoinezanardi/werewolves-assistant-api-next/blob/main/public/assets/images/roles/werewolf/werewolf-small.jpeg?raw=true" width="40"/><br/>Werewolf | <img src="https://github.com/antoinezanardi/werewolves-assistant-api-next/blob/main/public/assets/images/roles/big-bad-wolf/big-bad-wolf-small.jpeg?raw=true" width="40"/><br/>Big Bad Wolf | <img src="https://github.com/antoinezanardi/werewolves-assistant-api-next/blob/main/public/assets/images/roles/accursed-wolf-father/accursed-wolf-father-small.jpeg?raw=true" width="40"/><br/>Accursed Wolf-Father | <img src="https://github.com/antoinezanardi/werewolves-assistant-api-next/blob/main/public/assets/images/roles/white-werewolf/white-werewolf-small.jpeg?raw=true" width="40"/><br/>White Werewolf |
---|---|---|---|
<img src="https://github.com/antoinezanardi/werewolves-assistant-api-next/blob/main/public/assets/images/roles/villager/villager-small.jpeg?raw=true" width="40"/><br/>Villager | <img src="https://github.com/antoinezanardi/werewolves-assistant-api-next/blob/main/public/assets/images/roles/villager-villager/villager-villager-small.jpeg?raw=true" width="40"/><br/> Villager-Villager | <img src="https://github.com/antoinezanardi/werewolves-assistant-api-next/blob/main/public/assets/images/roles/seer/seer-small.jpeg?raw=true" width="40"/><br/>Seer | <img src="https://github.com/antoinezanardi/werewolves-assistant-api-next/blob/main/public/assets/images/roles/cupid/cupid-small.jpeg?raw=true" width="40"/><br/>Cupid |
<img src="https://github.com/antoinezanardi/werewolves-assistant-api-next/blob/main/public/assets/images/roles/witch/witch-small.jpeg?raw=true" width="40"/><br/>Witch | <img src="https://github.com/antoinezanardi/werewolves-assistant-api-next/blob/main/public/assets/images/roles/hunter/hunter-small.jpeg?raw=true" width="40"/><br/>Hunter | <img src="https://github.com/antoinezanardi/werewolves-assistant-api-next/blob/main/public/assets/images/roles/little-girl/little-girl-small.jpeg?raw=true" width="40"/><br/>Little Girl | <img src="https://github.com/antoinezanardi/werewolves-assistant-api-next/blob/main/public/assets/images/roles/defender/defender-small.jpeg?raw=true" width="40"/><br/>Defender |
<img src="https://github.com/antoinezanardi/werewolves-assistant-api-next/blob/main/public/assets/images/roles/elder/elder-small.jpeg?raw=true" width="40"/><br/>Elder | <img src="https://github.com/antoinezanardi/werewolves-assistant-api-next/blob/main/public/assets/images/roles/scapegoat/scapegoat-small.jpeg?raw=true" width="40"/><br/>Scapegoat | <img src="https://github.com/antoinezanardi/werewolves-assistant-api-next/blob/main/public/assets/images/roles/idiot/idiot-small.jpeg?raw=true" width="40"/><br/>Idiot | <img src="https://github.com/antoinezanardi/werewolves-assistant-api-next/blob/main/public/assets/images/roles/two-sisters/two-sisters-small.jpeg?raw=true" width="40"/><br/>Two Sisters |
<img src="https://github.com/antoinezanardi/werewolves-assistant-api-next/blob/main/public/assets/images/roles/three-brothers/three-brothers-small.jpeg?raw=true" width="40"/><br/>Three Brothers | <img src="https://github.com/antoinezanardi/werewolves-assistant-api-next/blob/main/public/assets/images/roles/fox/fox-small.jpeg?raw=true" width="40"/><br/>Fox | <img src="https://github.com/antoinezanardi/werewolves-assistant-api-next/blob/main/public/assets/images/roles/bear-tamer/bear-tamer-small.jpeg?raw=true" width="40"/><br/>Bear Tamer | <img src="https://github.com/antoinezanardi/werewolves-assistant-api-next/blob/main/public/assets/images/roles/stuttering-judge/stuttering-judge-small.jpeg?raw=true" width="40"/><br/>Stuttering Judge |
<img src="https://github.com/antoinezanardi/werewolves-assistant-api-next/blob/main/public/assets/images/roles/rusty-sword-knight/rusty-sword-knight-small.jpeg?raw=true" width="40"/><br/>Rusty Sword Knight | <img src="https://github.com/antoinezanardi/werewolves-assistant-api-next/blob/main/public/assets/images/roles/wild-child/wild-child-small.jpeg?raw=true" width="40"/><br/>Wild Child | <img src="https://github.com/antoinezanardi/werewolves-assistant-api-next/blob/main/public/assets/images/roles/wolf-hound/wolf-hound-small.jpeg?raw=true" width="40"/><br/>Wolf-Hound | <img src="https://github.com/antoinezanardi/werewolves-assistant-api-next/blob/main/public/assets/images/roles/thief/thief-small.jpeg?raw=true" width="40"/><br/>Thief |
<img src="https://github.com/antoinezanardi/werewolves-assistant-api-next/blob/main/public/assets/images/roles/angel/angel-small.jpeg?raw=true" width="40"/><br/>Angel | <img src="https://github.com/antoinezanardi/werewolves-assistant-api-next/blob/main/public/assets/images/roles/pied-piper/pied-piper-small.jpeg?raw=true" width="40"/><br/>Pied Piper | <img src="https://github.com/antoinezanardi/werewolves-assistant-api-next/blob/main/public/assets/images/roles/scandalmonger/scandalmonger-small.jpeg?raw=true" width="40"/><br/>Scandalmonger | <img src="https://github.com/antoinezanardi/werewolves-assistant-api-next/blob/main/public/assets/images/roles/prejudiced-manipulator/prejudiced-manipulator-small.jpeg?raw=true" width="40"/><br/>Prejudiced Manipulator |
<img src="https://github.com/antoinezanardi/werewolves-assistant-api-next/blob/main/public/assets/images/roles/actor/actor-small.jpeg?raw=true" width="40"/><br/>Actor | <img src="https://github.com/antoinezanardi/werewolves-assistant-api-next/blob/main/public/assets/images/roles/devoted-servant/devoted-servant-small.jpeg?raw=true" width="40"/><br/>Devoted Servant |
<a name="installation">๐จ Installation</a>
To install this project, you will need to have on your machine :
We recommend to use the node version specified in the .nvmrc
file.
If you don't have pnpm
installed, you can still use npm
for all commands below, but we recommend to use pnpm
for faster and more reliable installs.
Then, run the following commands :
# Install dependencies and Husky hooks
pnpm install
# Run the app in dev mode
pnpm run start:dev
The above command will start the app in development mode and watch for changes on local.
You can also run the app in development mode with Docker, more information in the Docker section.
<a name="build">๐ Build</a>
In order to build the app for production, run the following command :
# Build the app
pnpm run build
# Run the app in production mode
pnpm run start:prod
You can also run the app in production mode with Docker, more information in the Docker section.
<a name="docker">๐ณ Docker</a>
This app is Docker ready !
The Dockerfile is available at the root of the project. It uses a multi-stage build to optimize the image size and distroless image to reduce the attack surface.
๐จ Development mode
To run the app in development mode with Docker, multiple commands are available :
# Run the app in development mode with Docker
pnpm run docker:dev:start
# Stop the app in development mode with Docker
pnpm run docker:dev:stop
# Reset the app in development mode with Docker (stop, remove image, containers and volumes, then start)
pnpm run docker:dev:reset
When starting the app in development mode with Docker, a container for the API and a container for the MongoDB database are created.
Docker compose will use the development
step of the Dockerfile to build the image.
For more information, please check the docker-compose.yml file.
๐ Production mode
To run the app in production mode with Docker, multiple commands are available :
# Run the app in production mode with Docker
pnpm run docker:production:start
# Stop the app in production mode with Docker
pnpm run docker:production:stop
# Reset the app in production mode with Docker (stop, remove image, containers and volumes, then start)
pnpm run docker:production:reset
When starting the app in production mode with Docker, a container for the API and a container for the MongoDB database are created.
Docker compose will use the production
step of the Dockerfile to build the image.
For more information, please check the docker-compose.yml file.
๐งช Test mode
To run the tests available in this project thanks to Docker, multiple commands are available :
# Deploy test containers (4 databases are created to parallelize tests)
pnpm run docker:test:start
# Stop test containers
pnpm run docker:test:stop
# Reset test containers (stop, remove image, containers and volumes, then start)
pnpm run docker:test:reset
For more information, please check the docker-compose.yml file.
<a name="tests">๐ฏ Tests</a>
๐งช Unit and E2E tests
๐ฅ Acceptance tests
Click on the badge below ๐ to see the reports.
๐ฝ Mutant testing
You can also check the mutation testing report.
โถ๏ธ Commands
Before testing, you must follow the installation steps.
Then, run one of the following commands :
# Assure you started test Docker containers (4 databases are created to parallelize tests)
pnpm run docker:test:start
# Run unit tests with coverage
pnpm run test:unit:cov
# Run e2e tests with coverage
pnpm run test:e2e:cov
# Run both unit and e2e tests with coverage
pnpm run test:cov
# Run both unit and e2e tests only on staged files (run on pre-commit)
pnpm run test:staged
# Run acceptance tests
pnpm run test:cucumber
# Run acceptance tests and publish the report
pnpm run test:cucumber:publish
# Run mutant tests with coverage
pnpm run test:stryker
# Run mutant tests with coverage from scratch (without using the incremental file)
pnpm run test:stryker:force
<a name="env-variables">๐ฟ Env variables</a>
Environnement files are available in the env directory.
You can create a .env
file in this directory to override the default values when starting the API locally with pnpm run start
command.
Environment variables are :
Name | Description | Required | Default value | Limitations |
---|---|---|---|---|
HOST | Host on which the API will be available | โ | 127.0.0.1 | If set, can't be empty string |
PORT | Port on which the API will be available | โ | 8080 | If set, must be a number between 0 and 65535 |
ENVIRONNEMENT | Environment in which the API will run | โ | โ | Must be development , production or test |
DATABASE_HOST | MongoDB database host URL | โ | โ | Can't be empty string |
DATABASE_PORT | MongoDB database port | โ | undefined | If set, must be a number between 0 and 65535 |
DATABASE_NAME | MongoDB database name | โ | โ | Can't be empty string |
DATABASE_USERNAME | MongoDB database user | โ | โ | Can't be empty string |
DATABASE_PASSWORD | MongoDB database password | โ | โ | Can't be empty string |
CORS_ORIGIN | CORS allowed origin | โ | * | If set, can't be empty string |
<a name="code-analysis-and-consistency">โ๏ธ Code analysis and consistency</a>
๐ Code linting & formatting
In order to keep the code clean, consistent and free of bad TS practices, more than 300 ESLint rules are activated !
Complete list of all enabled rules is available in the .eslintrc.js file.
โถ๏ธ Commands
Before linting, you must follow the installation steps.
Then, run one of the following commands :
# Lint
pnpm run lint
# Lint and fix
pnpm run lint:fix
# Lint and fix only on staged files (runs on pre-commit)
pnpm run lint:staged:fix
# Display all configs and rules used in browser using @eslint/config-inspector
pnpm run lint:inspect-config
๐ฅ Project quality scanner
Multiple tools are set up to maintain the best code quality and to prevent vulnerabilities :
You can check the CodeQL analysis report here.
SonarCloud summary is available here.
<a name="versions">๐ Releases & Changelog</a>
Releases on main branch are generated and published automatically by :
It uses the conventional commit strategy.
Each change when a new release comes up is listed in the <a href="https://github.com/antoinezanardi/werewolves-assistant-api-next/blob/master/CHANGELOG.md" target="_blank">CHANGELOG.md file</a>.
Also, you can keep up with changes by watching releases via the Watch GitHub button at the top of this page.
๐ท๏ธ <a href="https://github.com/antoinezanardi/werewolves-assistant-api-next/releases" target="_blank">All releases for this project are available here</a>.
<a name="github-actions">๐ GitHub Actions</a>
This project uses GitHub Actions to automate some boring tasks.
You can find all the workflows in the .github/workflows directory.
๐ข Workflows
Name | Description & Status | Triggered on |
---|---|---|
โ๏ธ Build | Various checks for app health, code quality and tests coverage<br/><br/> | push on develop and all pull requests to develop |
๐ Lint PR Name Into Develop Workflow | Checks if pull request name respects conventionnal-commit rules<br/><br/> | pull-request created or updated |
โต๏ธ Push On Develop Branch Workflow | Uploads app with develop version to Docker Hub <br/><br/> | push on develop |
๐๏ธ Upsert PR Release Workflow | Creates or updates pull request to main depending on commits on develop since last release<br/><br/> | push on develop |
๐ท๏ธ Release Creation Workflow | Creates a new release using semantic-release with tag and updated changelog<br/><br/> | push on main |
๐ Deploy To Production Workflow | Deploys app with last tag version to Docker Hub and GCP <br/><br/> | tag-creation |
<a name="misc-commands">โจ Misc commands</a>
๐ณ Animated tree visualisation of the project's evolution with Gource
# Please ensure that `gource` is installed on your system.
pnpm run gource
๐ Create git branch with a conventional name
pnpm run script:create-branch
โคด๏ธ Create pull request against the develop
branch from current branch
pnpm run script:create-pull-request
๐ฃ To all IntelliJ IDEs users (IntelliJ, Webstorm, PHPStorm, etc.)
All the above commands are available in the .run directory at the root of the project.
You can add them as run configurations in your IDE.
<a name="license">ยฉ๏ธ License</a>
This project is licensed under the MIT License.
<a name="contributors">โค๏ธ Contributors</a>
There is no contributor yet. Want to be the first ?
If you want to contribute to this project, please read the contribution guide.