The Pwned Game

This project is a web game where you guess which password is the most popular between two shown on screen.

Technologies

Note: Versions listed here refer to the one used to build the project, but it should work with the most recent minor version of the same major.

Needed on the host

• Angular CLI version 12.
• NodeJS version 14.
• Docker.

Used in the project

• Nginx
• Nodemon
• NodeJS
• Socket.io
• MongoDB
• Express
• Angular
• Angular Material
• Mongoose
• ...

Development: server

Before starting

Please keep in mind that the server needs some enviroment variables to be defined inside an .env in the root folder, which could look like:

HOST_PORT=9000
JWT_SECRET=yummy
MONGO_DB_NAME=hlp-db
MONGO_DB_USERNAME=hlp
MONGO_DB_PASSWORD=hotdog
MONGO_DB_ROOT_PASSWORD=hotdogwithsauce
EMAIL_DEBUG=true

Explanation

• The production server will be available at the port HOST_PORT, which is managed by Nginx. Nginx will serve static files and forward API/socket requests to the backend container
• Database admin access is granted to user root (fixed) with password MONGO_DB_ROOT_PASSWORD, in the authentication db admin (fixed). Another user, MONGO_DB_USERNAME, will be used by the backend server to authenticate to the mongo container in order to have access to the db MONGO_DB_NAME, using password MONGO_DB_PASSWORD.
• JWT_SECRET will be used to sign Json Web Tokens.
• EMAIL_DEBUG, if set to true, will enable email debug mode, meaning that emails will be printed on console if a better way of sending them is not available.

Optional environment variables:

• MAILER_EMAIL and MAILER_PASSWORD are the credentials to use a mail account to send emails. If both have values, nodemailer will use them to send emails.

Currently supported mail services:

• Gmail (More info).

Note: You can prevent uploading sensitive data inside the .env file with:
git update-index --assume-unchanged .env

Development mode

First you need to install server dependencies with npm install, run inside the server folder backend/js.
To develop a server, run the docker compose file for Development mode with:
docker compose -f docker-compose.dev.yml up -d from the root folder. Docker should create these containers:

• mongo that manages the database
  • Data is saved in a named volume by docker hlp-mongo-db-data
  • Logs are saved inside /backend/mongo/data/log on the host machine
  • Mongo setup is stored in /backend/mongo/setup
• hlp-backend-dev with the live version of the nodejs backend mapped with host source files, and updated in real-time by nodemon
  • Every file inside /backend/js is mapped inside the container, including node_modules
  • After an edit is detected by nodemon on the source files (.js, .json) index.js is restarted inside the container, so that changes are online as soon as possible
  • You can look at the container logs for errors or debugging, with docker logs --follow <backend-container-id>

Development: client

To develop the client, follow the instructions in the previous section. When you have the backend ready and listening on its port, you can use any frontend to communicate with it, directly from your local machine or host.

API Documentation

Available in the Wiki.

Developing the Angular Web App client

The client is developed and compiled on the host machine, so you need to run npm install in the frontend folder frontend/angular/hlp to download dependencies. If you want to contribute to the main client made with Angular you can write your code while ng serve provides a live version if it, automatically updated and compiled.

Navigate to http://localhost:4200/. The app will automatically reload if you change any of the source files.

Update dependencies

In order to update the dependencies without accidentally changing the Angular major version, use ng update @angular/cli@^10 @angular/core@^10.

Manual tests

To test the angular client by hand usually you just need to run ng serve, but if you want to make the client available to every machine on your local network, making the angular host similar to a server, you need:

1. To make sure that the backend port is mapped to an host public port and reachable from the local network;
2. To set your machine IP address and backend port inside the environment.ts file;
3. To run ng serve --host 0.0.0.0 --port <port> --disableHostCheck to serve the client on the specified port on your machine ip under your local network.

Code scaffolding

Run ng generate component component-name to generate a new component. You can also use ng generate directive|pipe|service|class|guard|interface|enum|module.

Running unit tests

Run ng test to execute the unit tests via Karma.

Running end-to-end tests

Run ng e2e to execute the end-to-end tests via Protractor.

Production mode

To run the entire project in production mode just type docker compose up -d in the root folder of the repository. This is a simulation of a production environment on your local machine. On Windows, MongoDB /data/db folder can't be mounted on a volume shared with the host machine. To achieve persistency of data, either user docker native modules or an external database. In order to use an external MongoDB database configure it properly (see the configuration file of the project) and use the docker-compose.extdb.yml compose file, after having defined the environment variable MONGO_DB_URL.

Note: Only requests to /api or /socket path are forwarded to the server by Nginx.

Stopping containers

To properly stop running containers use docker compose [-f ...] down. To stop and clean volumes use docker compose [-f ...] down -v.
Note: Volumes left inside docker storage could fill up the space on the host machine!