ft_transcendence

---

🏓 Play pong online with your friends in real time

📝 Table of Contents

• About
• Getting Started
  • Prerequisites
  • Deploy locally
  • Developing and installing dependencies
  • OpenAPI
  • Migrate the database schema
  • Seed the database
  • Testing and linting
• Two-factor authentication
• Exploring DB
• Deployment
  • Prerequisites
  • Installing
• Built Using
• Contributing
• Acknowledgments

🧐 About

The primary purpose of this website is to play pong against other players and show everyone how good you are!

🏁 Getting Started

These instructions will get you a copy of the project up and running on your local machine for development and testing purposes. See deployment for notes on how to deploy the project on a live system.

Prerequisites

What things do you need to install the software, and how to install them.

git

docker compose

npm

node

nestjs

knex

make

Deploy locally

A step-by-step series of examples that tell you how to get a development environment running.

Register a new OAuth application on the 42 intranet

Set the Redirect URIs

http://localhost:3000/api/v1/auth/login
http://localhost/api/v1/auth/login

Clone the GitHub repository

git clone https://github.com/42AGV/ft_transcendence.git

Change the current working directory to ft_transcendence

cd ft_transcendence

Either create a .env file in the root directory containing the following environment variables (replace the FORTYTWO_APP_ID and FORTYTWO_APP_SECRET with the ones from the OAuth application you created in the previous step):

NOTE: You can generate UUIDs using the uuidgen command

FORTYTWO_APP_ID=your-42-app-id
FORTYTWO_APP_SECRET=your-42-app-secret
SESSION_SECRET=your-session-secret-uuid
MEMCACHED_SECRET=your-memcached-secret-uuid
WEBSITE_OWNER_PASSWORD=your-owner-password
WEBSITE_OWNER_USERNAME=your-owner-username

Or export them from the shell like:

export FORTYTWO_APP_ID=your-42-app-id
export FORTYTWO_APP_SECRET=your-42-app-secret
export SESSION_SECRET=your-session-secret-uuid
export MEMCACHED_SECRET=your-memcached-secret-uuid
export WEBSITE_OWNER_PASSWORD=your-owner-password
export WEBSITE_OWNER_USERNAME=your-owner-username

Start the application using make

make all

You can now access the web application at http://localhost:3000 and the Swagger documentation for the API at http://localhost:3000/api

Install the node packages required for the web and server application.

cd transcendence-app
npm ci
cd ../webapp
npm ci
cd ..

Some useful commands to see the output logs of the Docker containers

make log-wa
make log-tr
make log-db

NOTE: The logs of the transcendence-app don't include the version in the routes

NOTE: For advanced use cases, you can connect to a service using the Docker container IP and port

Inspect the containers

make get-ip

Access using the Docker container IP and the service port

After a config file change, please run the following command to recreate the images, renew anonymous volumes and restart the Docker containers

make re

Developing and installing dependencies

This project is a monorepo. We use a very simple setup taking advantage of npm workspaces. This allows us to have local libraries and share code across different services.

You may need to start developing, in order to do so, you should install dependencies and build packages (note that previous local deployment point explained how to deploy the app on a docker environment, no locally). From the root of the project just run:

npm i to install dependencies

and then, to build packages:

npm run build-packages

You may want to add a new dependency to a service. Just run npm i inside of the service path as you would do normally.

OpenAPI

We use OpenAPI Generator to generate the files at webapp/src/shared/generated from the OpenAPI specifications at transcendence-app/swagger-spec/swagger-spec.yaml.

Please don't modify these files manually.

generate-openapi

To generate the files, run the following command from the root directory:

make gen

make gen creates both yaml file and generated webapp files. To generate only webapp generated files run make gen-webapp. To generate only swagger spec run make spec.

Migrate the database schema

We use knex to migrate the database schema, more info here.

To run the migrations, execute the following command from the root directory:

make migrate

To create a migration, run the following command from the transcendence-app directory (replace migration_name with the name you want)

npx knex migrate:make migration_name

Seed the database

We use knex to seed the database, more info here.

To run seed files, run the following command from the root directory:

make seed

To create a seed file, run the following command from the transcendence-app directory (replace 00X_seed_name with the name you want)

npx knex seed:make 00X_seed_name

NOTE: Knex executes the seed files in alphabetical order

🔧 Testing and linting

Change the working directory to webapp or transcendence-app

cd webapp
npm test
npm run test:e2e

And coding style tests

Change the working directory to webapp or transcendence-app and run style check

cd transcendence-app
npm run style

🔐 Two-factor authentication

We use the otplib library to generate and validate TOTP tokens and the qrcode library to display a QR code with the 2FA info.

After the user validates the 2FA TOTP token, we store a signed cookie on the client and check its presence on the server using the cookie-parser library.

When the user logs out, we delete the 2FA cookie.

We use the TwoFactorAuthenticatedGuard to check if the user is authenticated + authorized and also two-factor authenticated (this guard uses the canActivate method from the AuthenticatedGuard when the user doesn't have 2FA enabled)

🗄️ Exploring DB

You may want to make some test DB queries when developing. Just go to localhost:5050 and log in with admin@admin.com, admin to access the pg-admin client.

🚀 Deployment

This section is for deploying the app on a production system.

NOTE: The application runs on port 80 in the production environment. If another service uses that port, please shut it down before running it.

Prerequisites

What things do you need to install the software, and how to install them.

git

docker compose

make

Installing

Register a new OAuth application on the 42 intranet

Set the Redirect URIs

http://your-domain-or-ip-here/api/v1/auth/login
http://localhost/api/v1/auth/login

Clone the GitHub repository

git clone https://github.com/42AGV/ft_transcendence.git

Change the current working directory to ft_transcendence

cd ft_transcendence

Either create a .env file in the root directory containing the following environment variables (replace the FORTYTWO_APP_ID and FORTYTWO_APP_SECRET with the ones from the OAuth application you create in the previous step):

NOTE: You can generate UUIDs using the uuidgen command

FORTYTWO_APP_ID=your-42-app-id
FORTYTWO_APP_SECRET=your-42-app-secret
FORTYTWO_APP_CALLBACK_URL=http://your-domain-or-ip-here/api/v1/auth/login
POSTGRES_USER=your-postgres-user
POSTGRES_PASSWORD=your-postgres-password
SESSION_SECRET=your-session-secret-uuid
MEMCACHED_SECRET=your-memcached-secret-uuid
WEBSITE_OWNER_PASSWORD=your-owner-password
WEBSITE_OWNER_USERNAME=your-owner-username

Or export them from the shell like:

export FORTYTWO_APP_ID=your-42-app-id
export FORTYTWO_APP_SECRET=your-42-app-secret
export FORTYTWO_APP_CALLBACK_URL=http://your-domain-or-ip-here/api/v1/auth/login
export POSTGRES_USER=your-postgres-user
export POSTGRES_PASSWORD=your-postgres-password
export SESSION_SECRET=your-session-secret-uuid
export MEMCACHED_SECRET=your-memcached-secret-uuid
export WEBSITE_OWNER_PASSWORD=your-owner-password
export WEBSITE_OWNER_USERNAME=your-owner-username

Start the application using make

make prod

You can now access the web application locally at http://localhost and the Swagger documentation for the API at http://localhost/api

⛏️ Built Using

• PostgreSQL - Database
• NestJS - Server Framework
• React - Web Framework
• NodeJs - Server Environment
• Docker - Containerization Platform

🤝 Contributing

If you want to contribute to this project you may follow a set of rules.

1. Create a new issue or task:

• With every contribution there must be a related issue/task, so if you don't have any, create a new one on the project board with some detailed info about what do you want to accomplish.
• Add an appropiate label which describes issue type: feature, bug, task etc.

2. Create a new branch:

• ⚠️ We do not push to main, never. So you'll need to create a branch to work on it.
• Try to start always from main and do not forget to bring all new changes, preferably with git pull --rebase so you don't corrupt commit history.

3. Naming:

• What about branch naming? A good standard way to name could be issue

• brief description of the task. For example: #11/add-contributing-docs

• We also try to have a normalized way to name commits. Because is complicated to always have great commit messages (despite you should) a good enough naming strategy is adding your issue number followd by the message. This way other devs can keep track of some context of the changes just visiting the related issue because GitHub will link to it. Try something like: #11 / add main contributing points

4. Pull Requests:

• When you are ready, you can create a new PR pointing to main. We have defined two requisites to be able to merge your branch into main:
  • At least two reviewers approved your changes
  • You also have passed all CI checks (tests, linting etc.)
• In the PR description you should add: closing #11 (number of related issue) so when PR gets integrated, issue gets closed automatically
• As with the commits, the ideal is to name it with the issue number followed by a general description of what is about: #11 / add contributing documentation
• Once you pass all these checks, you are responsible to integrate your changes. We have actually two ways: manually or automatically with auto-merge
• We've decided to integrate our branches using a squash strategy. This let us to have some freedom when working in our branches. The only requisite is following issue_number + short descriptive message rule in the squash message.

5. Conflicts:

• How do I solve conflicts? Most likely, someone merged some commits into main that affect the same files and lines as yours. One of the cleanest ways to solve this is just to update (pull) main in your local and, then, rebase main into your branch: git rebase main. Git will make you solve conflicts one by one, you just have to follow the instructions!

🎉 Acknowledgements

• The Documentation Compendium