π Play pong online with your friends in real time
- About
- Getting Started
- Two-factor authentication
- Exploring DB
- Deployment
- Built Using
- Contributing
- Acknowledgments
The primary purpose of this website is to play pong against other players and show everyone how good you are!
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.
What things do you need to install the software, and how to install them.
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
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.
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.
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
.
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
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
Change the working directory to webapp
or transcendence-app
cd webapp
npm test
npm run test:e2e
Change the working directory to webapp
or transcendence-app
and run style check
cd transcendence-app
npm run style
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)
You may want to make some test DB queries when developing. Just go to localhost:5050
and log in with [email protected]
, admin
to access the pg-admin client.
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.
What things do you need to install the software, and how to install them.
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
- PostgreSQL - Database
- NestJS - Server Framework
- React - Web Framework
- NodeJs - Server Environment
- Docker - Containerization Platform
If you want to contribute to this project you may follow a set of rules.
- 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.
β οΈ We do not push tomain
, 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 withgit pull --rebase
so you don't corrupt commit history.
- 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
- 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 followingissue_number + short descriptive message
rule in the squash message.
- 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!