## Sommaire 1) Introduction 2) Description du projet 3) La pile technologique 1) Le serveur 2) Le site web 3) La base de données 4) Le serveur 1) Les dépendances 2) Le fonctionnement 5) Le site web 1) Les dépendances 2) Le fonctionnement 6) La base de données 7) Installation du projet 1) Docker Compose 2) Script Shell 3) Manuellement 8) Conclusion ## Introduction Cette documentation est à destination des futurs développeurs travaillant sur Freetube. Elle a pour but d’expliquer le fonctionnement technique de toutes les couches de l’application et à justifier les choix pris pour chaque langage et framework.  La documentation est une ressource indispensable pour tous ceux voulant comprendre le fonctionnement interne de Freetube. Les parties démontrées ici couvrent toutes les couches de l’application. Par ailleurs des diagrammes UML et schémas de base de données vous sont fournies pour une meilleure compréhension du code. Un indexe est disponible en fin de document.  Cette documentation est à un but technique, elle rentre volontairement dans les détails du fonctionnement de chaque partie. Elle n’est pas faite pour être lu par un utilisateur, un manuel utilisateur vous a été fournies pour remplir ce besoin. De plus les documentations externes sont disponible en fin de document et un **Swagger** est présent sur l'endpoint `/api/api-docs` pour une documentation de l'API plus approfondie. ## Description du projet Il m’a été demandé de créer une plateforme concurrente à YouTube nommée Freetube. Cette alternative a pour but de mieux remplir les demandes des utilisateurs, pas d’abonnement ni publicité pour consommer ou poster des vidéos sur la plateforme.  Le cahier des charges du projet demande certaines fonctionnalités à implémenter. Les utilisateurs doivent pourvoir regarder des vidéos sans avoir à se connecter où à créer de compte, ils doivent pouvoir créer un compte et le gérer, pouvoir créer une chaîne la gérer et y poster des vidéos. La fonctionnalité de vidéo privé a aussi été demandé.  Pour ce projet j’avais la main libre sur la pile technologique à utiliser tout en respectant les demandes d’efficacité d’une plateforme de streaming vidéo. ## La pile technologique ### Le serveur Le serveur a été codé en **Nodejs**, j’ai choisi ce langage car il permet d’implémenter une **API REST** efficacement grâce à son implémentation native de l’asynchrone indispensable pour une API REST. NodeJS étant basé sur **Javascript** il n’est pas le plus efficient mais ce n’est pas dérangeant car nous travaillons avec une API, le temps de réponse sera biaisé par la connexion internet de l’utilisateur. ### Le site web Le site web a lui été codé en **ReactJS** une librairie Javascript permettant de créer des interfaces utilisateur. ReactJS étant lui aussi basé sur Javascript, cela permet une maintenabilité plus simple car les deux parties sont dans le même langages, de plus le site web bénéficie lui aussi de l’implémentation de l’asynchrone. J’ai choisi d’utiliser ReactJS car il permet l’utilisation de **components** permettant le live reload et évite la duplication de code inutile. ### La base de données La base de données est en **PostgreSQL**, un langage basé sur **SQL** largement utilisé pour communiquer avec une base de données. Cependant PostgreSQL possède quelques avantages par rapport à une base de données comme **MySQL**, il intègre une très bonne gestion du **JSON** que j’ai beaucoup utilisé dans ce projet et il est **Open Source**. ## Le serveur ### Les dépendances Le serveur NodeJS sert de plateforme entre le site web et la base de données, il doit donc pouvoir recevoir des requêtes HTTP et envoyer des requêtes SQL. Pour les requêtes HTTP j’ai choisis le framework **ExpressJS** car il est très connu et a donc beaucoup de contenu disponible sur internet. Pour les requêtes SQL j'ai utilisé la librairie **pg** qui permet de communiquer avec PostgreSQL, cette librairie peux gérer les fermetures de connexion inutile comme les time out ou les oublies.  Puisque l’API transmet des données sensibles j’ai dû sécuriser les endpoints en vérifiant les données entrantes, pour cela j’ai utilisé **express-validator** qui permet de créer des **middlewares** pour vérifier les données. Pour les images et les fichiers vidéo j’ai utilisé **multer** qui s’intègre très bien avec ExpressJS. Pour l’authentification par **Github** j’ai choisi de passé par **PassportJS** qui s’occupe du passage de token entre GitHub et le backend.  Pour la gestion de l’authentification j’ai utilisé **Json Web Token** qui permet de générer et de vérifier des tokens d’authentifications. Pour l’encryption des mots de passe **Bcrypt** a été utilisé. ### Le fonctionnement Chaque endpoints et diviser en trois parties distinctes, la définition de la route, qui va définir l’URL à appeler, les middlewares qui vont effectuer les vérifications et modifications des données avant leur utilisation, et les controllers qui vont faire les actions (appels de base données, déplacement de fichier...). Des diagrammes UML expliquant les routes unes-à-unes est disponible dans le dossier “Diagramme_UML”. Chaque endpoints qui doivent être protégées par l’utilisation d’un compte utilisent le middleware “auth.middleware.js” pour vérifier la validité d’un token. ## Le site web ### Les dépendances Le site web ne doit faire aucun calcul, tout passe donc par des requête HTTP, j'ai donc utilisé la librairie **fetch** intégré à NodeJS dans sa version 22.  Pour l’hébergement j’ai choisi **NGINX** car il permet de d’héberger un site et de faire des redirections, il m’a permis de rediriger les requêtes vers l’API en passant par la route “/api/” ce qui évite d’exposer des ports inutilement.  NGINX permet aussi de mettre en place l’**HTTPS** avec des **certificats SSL** ce qui chiffre les requêtes du site et de l'API.  Le site fonctionnant avec ReactJS nécessite l’utilisation de **Vite** pour le développement et le déploiement.  Freetube est un site multi-page et doit utiliser un système de routage. Pour cela j’ai utilisé **React Router 7** car il est très utilisé et donc très bien documenté. Pour la partie style du site web, j'ai utilisé TailwindCSS dans sa version 4.0. Tailwind permet de créer des classes CSS directement depuis le JSX et prend en charge le responsive grâce a des **breakpoints**. Il est notamment plus léger que ses concurrents car il créer ses classes CSS au moment du build contrairement, par exemple, a Bootstrap qui à besoin d'un fichier contenant toue les classes CSS de la librairie pour fonctionner. ### Le fonctionnement Les éléments du site sont divisés en plusieurs parties, les pages sont dans le dossier “/src/pages” et servent à accueillir et à mettre en forme les composants et à appeler les services.   Les composants dans le dossier “/src/components” servent à diviser le code et à éviter la duplication, un composant peut être appelé plusieurs fois sur plusieurs pages différentes. Les composants ne font pas d'appel aux services, les événements liés aux composants sont passer en paramètre de ces dernier.  Les modales sont dans le dossier “/src/modals” et sont toujours afficher au-dessus de la vue principale. Comme les composants elles ne fonts aucun appels aux services, les événements liés aux modales sont passer en paramètre de ces derniers. Elles sont toujours appelées en fin de fichier.  Les services présent dans le dossier “/src/services” sont les seuls fichiers faisant appel à l’API (à l’exception du fichier AuthContext.jsx). Les services sont organisés de la même manière que les endpoints. Un service peut être appelé plusieurs fois dans plusieurs pages.  Les routes utilisées par React Router sont présente dans le fichier “/src/routes/route.jsx”. Les routes ayant besoin d’un compte sont protégées par “ProtectedRoute” et rédigeront automatiquement à la page de connexion. React Router n’étant pas directement compatible avec le système de NGINX une configuration supplémentaire est nécessaire, elle est détaillée dans le fichier “/nginx/default.conf”. ## La base de données La structure de la base de données est créée automatiquement par le serveur au lancement, chaque modification effectuée doit être modifié dans le fichier `/backend/src/utils/database.js` dans la fonction `initDb()`.   La base de données étant relationnelle, elle repose sur beaucoup de clé étrangère détaillés dans le schéma fourni. A savoir que les enfants se détruisent automatiquement si le lien parent est supprimé grâce à la condition “ON CASCADE” présente dans chacun des liens.   Le port de la base de données (5432 par defaut) ne doit jamais être exposé sans pare-feu, seul le serveur doit y avoir accès. Pour cela PostgreSQL propose deux fichiers de configuration. `pg_hba` créer des règles internes en fonction de l’utilisateur, la base cible et l’IP du client et `postgres.conf` qui permet de définir un schéma d’IP autorisé. A savoir que si le projet et lancé via Docker seul localhost peut avoir accès à cette base de données. ## Installation et lancement **Ces instructions sont prévues pour un serveur tournant sous Ubuntu 24.04/Debian 12.** Par conséquent certaines commandes peuvent être incompatible avec votre système, cependant cotre système d'exploitation fournis des commandes alternatives. Freetube peut être installé de trois manière différentes : - Docker Compose - Script Shell - Manuellement ### Installation avec Docker Compose #### Installer Docker et Docker Compose De part la [documentation officielle de Docker](https://docs.docker.com/engine/install/ubuntu/) ```bash # Add Docker's official GPG key: sudo apt-get update sudo apt-get install ca-certificates curl sudo install -m 0755 -d /etc/apt/keyrings sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc sudo chmod a+r /etc/apt/keyrings/docker.asc # Add the repository to Apt sources: echo \ "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \ $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}") stable" | \ sudo tee /etc/apt/sources.list.d/docker.list > /dev/null sudo apt-get update sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin ``` #### Paramétrages NGINX Quelque modification doivent être faites pour le fonctionnement de NGINX ```nginx server { #------------------------------ ici ------------------------------- server_name ; #------------------------------------------------------------------ listen 80; return 301 https://$host$request_uri; } server { #------------------------------ ici ------------------------------- server_name ; #------------------------------------------------------------------ listen 443 ssl; root /usr/share/nginx/html; index index.html index.htm; client_max_body_size 500M; ssl_certificate /etc/nginx/ssl/nginx-selfsigned.crt; ssl_certificate_key /etc/nginx/ssl/nginx-selfsigned.key; ssl_protocols TLSv1.2 TLSv1.3; ssl_ciphers HIGH:!aNULL:!MD5; location /api/ { if ($request_method = 'OPTIONS') { add_header 'Access-Control-Allow-Origin' '$http_origin' always; add_header 'Access-Control-Allow-Methods' 'GET, POST, PUT, DELETE, OPTIONS' always; add_header 'Access-Control-Allow-Headers' 'Content-Type, Authorization, X-Requested-With' always; add_header 'Access-Control-Allow-Credentials' 'true' always; add_header 'Access-Control-Max-Age' 1728000 always; add_header 'Content-Type' 'text/plain; charset=utf-8' always; add_header 'Content-Length' 0 always; return 204; } proxy_pass http://resit_backend:8000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_set_header Origin $http_origin; proxy_buffering off; add_header 'Access-Control-Allow-Origin' '$http_origin' always; add_header 'Access-Control-Allow-Credentials' 'true' always; proxy_read_timeout 300s; proxy_send_timeout 300s; } location ~* ^/(?!api/).*\.(js|css|png|jpg|jpeg|gif|ico|svg)$ { add_header Cache-Control "no-store, no-cache, must-revalidate, proxy-revalidate, max-age=0"; add_header Pragma "no-cache"; add_header Expires "0"; try_files $uri =404; } location / { add_header Cache-Control "no-store, no-cache, must-revalidate, proxy-revalidate, max-age=0"; try_files $uri $uri/ /index.html; } } ``` #### Création de clé d'API Gmail Rendez-vous sur [Gmail](https://gmail.com) et allez dans le panel d'administration de votre compte Dans la barre de recherche tapez `Mot de passe des applications` Créer un mot de passe et gardez le de côté il servira pour les variables d'environnements #### Création Application OAuth Github Rendez-vous sur [Github](https://github.com) et allez dans les paramètres de votre compte En bas du menu à gauche, cliquez sur `Paramètres de développeur` puis cliquez sur `Application OAuth` Créez une nouvelle application et gardez les clé de côté, elle serviront pour les variables d'environnements #### Mise en place des variables d'environnements A la racine du projet créer un fichier `.env` ```bash touch .env ``` A l'aide de l'éditeur de votre choix entrez dans le fichier ``` nano .env ``` Rentrez les informations dans ce format /!\ les valeurs non-entourées de chevrons **ne doivent pas être modifié**. ```env POSTGRES_USER= POSTGRES_PASSWORD= POSTGRES_DB= POSTGRES_HOST=db BACKEND_PORT=8000 JWT_SECRET= LOG_FILE=/var/log/freetube/access.log GMAIL_USER= GMAIL_PASSWORD= FRONTEND_URL= GITHUB_ID= GITHUB_SECRET= #### Lancement Pour lancer le groupe de conteneur ```bash docker compose up -d # pour détacher de la session ``` ### Installation via le Script Shell #### Ajout des autorisations Pour ajouter les autorisations nécessaire au lancement du script ```bash chmod +x ./deploy.sh ``` #### Création de clé d'API Gmail Rendez-vous sur [Gmail](https://gmail.com) et allez dans le panel d'administration de votre compte Dans la barre de recherche tapez `Mot de passe des applications` Créer un mot de passe et gardez le de côté il servira pour les variables d'environnements #### Création Application OAuth Github Rendez-vous sur [Github](https://github.com) et allez dans les paramètres de votre compte En bas du menu à gauche, cliquez sur `Paramètres de développeur` puis cliquez sur `Application OAuth` Créez une nouvelle application et gardez les clé de côté, elle serviront pour les variables d'environnements #### Lancer l'installation Lancer le script et répondez au question ```bash ./deploy.sh ``` Lancer le projet ```bash cd backend && npm run start cd frontend && npx vite build systemctl enable --now nginx # Pour un démarrage automatique au lancement de la machine systemctl enable --now postgresql ``` ### Installation manuelle #### Création de clé d'API Gmail Rendez-vous sur [Gmail](https://gmail.com) et allez dans le panel d'administration de votre compte Dans la barre de recherche tapez `Mot de passe des applications` Créer un mot de passe et gardez le de côté il servira pour les variables d'environnements #### Création Application OAuth Github Rendez-vous sur [Github](https://github.com) et allez dans les paramètres de votre compte En bas du menu à gauche, cliquez sur `Paramètres de développeur` puis cliquez sur `Application OAuth` Créez une nouvelle application et gardez les clé de côté, elle serviront pour les variables d'environnements #### Mise en place des variables d'environnements A la racine du projet créer un fichier `.env` ```bash touch .env ``` A l'aide de l'éditeur de votre choix entrez dans le fichier ``` nano .env ``` Rentrez les informations dans ce format /!\ les valeurs non-entourées de chevrons **ne doivent pas être modifié**. ```env POSTGRES_USER= POSTGRES_PASSWORD= POSTGRES_DB= POSTGRES_HOST=db BACKEND_PORT=8000 JWT_SECRET= LOG_FILE=/var/log/freetube/access.log GMAIL_USER= GMAIL_PASSWORD= FRONTEND_URL= GITHUB_ID= GITHUB_SECRET= ``` #### Installation des paquets Pour installer PostgreSQL/NGINX ```bash apt install nginx postgresql ``` Pour installer NodeJS de part la [documentation officielle](https://nodejs.org/en/download/) ```bash # Download and install nvm: curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash # in lieu of restarting the shell \. "$HOME/.nvm/nvm.sh" # Download and install Node.js: nvm install 22 # Verify the Node.js version: node -v # Should print "v22.19.0". nvm current # Should print "v22.19.0". # Verify npm version: npm -v # Should print "10.9.3". ``` #### Installations des dépendances NodeJS Pour le serveur ```bash cd backend && npm i --production ``` Pour le site web ```bash cd frontend && npm i --production npx vite build # pour la construction du site ``` #### Configuration de NGINX Dans `/etc/nginx/conf.d/` ajouter le fichier `freetube.conf` avec cette configuration ```nginx server { server_name ; listen 80; return 301 https://$host$request_uri; } server { server_name ; listen 443 ssl; root /usr/share/nginx/html; index index.html index.htm; client_max_body_size 500M; ssl_certificate /etc/nginx/ssl/nginx-selfsigned.crt; ssl_certificate_key /etc/nginx/ssl/nginx-selfsigned.key; ssl_protocols TLSv1.2 TLSv1.3; ssl_ciphers HIGH:!aNULL:!MD5; location /api/ { if ($request_method = 'OPTIONS') { add_header 'Access-Control-Allow-Origin' '$http_origin' always; add_header 'Access-Control-Allow-Methods' 'GET, POST, PUT, DELETE, OPTIONS' always; add_header 'Access-Control-Allow-Headers' 'Content-Type, Authorization, X-Requested-With' always; add_header 'Access-Control-Allow-Credentials' 'true' always; add_header 'Access-Control-Max-Age' 1728000 always; add_header 'Content-Type' 'text/plain; charset=utf-8' always; add_header 'Content-Length' 0 always; return 204; } proxy_pass http://resit_backend:8000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_set_header Origin $http_origin; proxy_buffering off; add_header 'Access-Control-Allow-Origin' '$http_origin' always; add_header 'Access-Control-Allow-Credentials' 'true' always; proxy_read_timeout 300s; proxy_send_timeout 300s; } location ~* ^/(?!api/).*\.(js|css|png|jpg|jpeg|gif|ico|svg)$ { add_header Cache-Control "no-store, no-cache, must-revalidate, proxy-revalidate, max-age=0"; add_header Pragma "no-cache"; add_header Expires "0"; try_files $uri =404; } location / { add_header Cache-Control "no-store, no-cache, must-revalidate, proxy-revalidate, max-age=0"; try_files $uri $uri/ /index.html; } } ``` #### Création de la base de données Pour créer l'utilisateur PostgreSQL ```postgresql CREATE ROLE "" WITH PASSWORD ""; ``` Pour créer la base ```postgresql CREATE DATABASE "" OWNER "