Merge pull request #271 from Arquisoft/readme/update

Updated the readme and the quickstart files
Arquisoft · Apr 22, 2024 · 6abbd04 · 6abbd04
2 parents 14476a9 + 5d6e5c4
commit 6abbd04
Show file tree

Hide file tree

Showing 2 changed files with 109 additions and 63 deletions.
diff --git a/Quickstart.md b/Quickstart.md
@@ -14,19 +14,45 @@ and launch it with docker compose:
 docker compose --profile dev up --build
 ```
 
+This will start the following components:
+
+ - The project database (using PostgreSQL).
+ - The question generator module.
+ - The API/backend.
+ - The webapp.
+ - The reverse proxy server used to serve HTTPS requests to the webapp.
+
+Do note that, as it is, the project will expect SSL keys in certain places. You may check [the proxy configuration](./proxy_conf/config.conf) and [the application properties of the API](./api/src/main/resources/application.properties) to find out where (the keys are not included in the release or in the repository). You may also remove the reverse proxy and comment out or delete the relevant if you do not have your own keys. Do note the project code is given as-is.
+
 ### Starting Component by component
 
-First, start the database. Either install and run Mongo or run it using docker:
+In the case you intend to run component by component, you will at the very least need your own SSL keys (see above how to bypass this requirement). Then, you may start starting the application.
+
+First, start the database. Either install and run PostgreSQL or run it using docker:
+
+```sh
+docker run -d -p 27017:27017 postgres:latest
+```
+
+You may also host your own PostgreSQL instance in the cloud. Now, launch the API. Do note you may need to install the relevant dependencies first: your IDE should do this for you; if it does not or you do not have one then you must run the following command inside both `api` and `questiongenerator` modules:
 
-```docker run -d -p 27017:27017 --name=my-mongo mongo:latest```
+```sh
+mvn install
+```
 
-You can also use services like Mongo Altas for running a Mongo database in the cloud.
+Lastly, go to the webapp directory and launch this component with 
+
+```sh
+npm install
+```
 
-Now, launch the auth, user and gateway services. Just go to each directory and run `npm install` followed by `npm start`.
+followed by 
 
-Lastly, go to the webapp directory and launch this component with `npm install` followed by `npm start`.
+```sh
+npm start
+```
 
-After all the components are launched, the app should be available in localhost in port 3000.
+After all the components are launched, the app should be available in localhost in port 3000 and 8443 for the API, or whatever port configure the app to use.
 
 ## Deployment
 
@@ -42,9 +68,9 @@ We are going to use the first approach, creating a virtual machine in a cloud se
 
 The machine for deployment can be created in services like Microsoft Azure or Amazon AWS. These are in general the settings that it must have:
 
-- Linux machine with Ubuntu > 20.04.
+- Linux machine with Ubuntu >= 20.04 (any Linux machine will do as long as you know which steps do not apply to you and how to perform the equivalent ones, though).
 - Docker and docker-compose installed.
-- Open ports for the applications installed (in this case, ports 3000 for the webapp and 8000 for the gateway service).
+- Open ports for the applications installed (in this case, ports 3000 for the webapp and 8443 for the API, or whatever port configure the app to use).
 
 Once you have the virtual machine created, you can install **docker** and **docker-compose** using the following instructions:
 
@@ -68,30 +94,46 @@ In this repository, this process is done automatically using **GitHub Actions**.
 
 As you can see, unitary tests of each module and e2e tests are executed before pushing the docker images and deploying them. Using this approach we avoid deploying versions that do not pass the tests.
 
-The deploy action is the following:
+The deploy action that does not include the SSL service is the following:
 
 ```yml
 deploy:
     name: Deploy over SSH
     runs-on: ubuntu-latest
-    needs: [docker-push-userservice,docker-push-authservice,docker-push-gatewayservice,docker-push-webapp]
+    needs: [docker-push-api, docker-push-webapp, docker-push-question-generator, docker-push-kiwiq]
     steps:
     - name: Deploy over SSH
       uses: fifsky/ssh-action@master
+      env:
+        API_URI: ${{ secrets.DEPLOY_HOST }}
+        DATABASE_USER: ${{ secrets.DATABASE_USER }}
+        DATABASE_PASSWORD: ${{ secrets.DATABASE_PASSWORD }}
+        JWT_SECRET: ${{ secrets.JWT_SECRET }}
       with:
         host: ${{ secrets.DEPLOY_HOST }}
         user: ${{ secrets.DEPLOY_USER }}
         key: ${{ secrets.DEPLOY_KEY }}
         command: |
           wget https://raw.githubusercontent.com/arquisoft/wiq_en2b/master/docker-compose.yml -O docker-compose.yml
           wget https://raw.githubusercontent.com/arquisoft/wiq_en2b/master/.env -O .env
-          docker compose down
-          docker compose --profile prod up -d
+          echo "DATABASE_USER=${{ secrets.DATABASE_USER }}" >> .env
+          echo "DATABASE_PASSWORD=${{ secrets.DATABASE_PASSWORD }}" >> .env
+          echo "JWT_SECRET=${{ secrets.JWT_SECRET }}" >> .env
+          echo "API_URI=https://${{ secrets.DEPLOY_HOST }}:8443" >> .env
+          echo "SSL_PASSWORD=${{ secrets.SSL_PASSWORD }}" >> .env
+          docker compose --profile prod down
+          docker compose --profile prod up -d --pull always
 ```
 
 This action uses three secrets that must be configured in the repository:
+
 - DEPLOY_HOST: IP of the remote machine.
 - DEPLOY_USER: user with permission to execute the commands in the remote machine.
 - DEPLOY_KEY: key to authenticate the user in the remote machine.
+- DATABASE_USER: the default user of the database.
+- DATABASE_PASSWORD: the password of the user.
+- JWT_SECRET: the secret needed to generate the JWT tokens.
+- SSL_PASSWORD: the password of the SSL keys
+- API_URI: the URI the API is deployed to, port included.
 
 Note that this action logs in the remote machine and downloads the docker-compose file from the repository and launches it. Obviously, previous actions have been executed which have uploaded the docker images to the GitHub Packages repository.
diff --git a/README.md b/README.md
@@ -1,51 +1,55 @@
-# 🧠🤔 KiWiq 🥝❓📚
-Visit our page [here!!!](http://kiwiq.run.place/).
-
-WIQ is a quiz game project inspired by the engaging and thought-provoking show "Saber y Ganar." 
-We aim to create a platform that not only challenges your knowledge but also sparks curiosity and the thrill of discovery.
-
-
-## What Sets WIQ Apart
-🤔 Thoughtful Questions: Dive into a world of intriguing and diverse questions, all generated procedurally using WikiData.  
-🌐 Encourage to improve: WIQ lets you keep track of your score to see in which areas you need to improve. 
-
-😭 It works! after the final version final re-final (FINAL) true (final) (hotfix)
-
-## Features
-🏆 Adaptable  difficulty: You can adjust the difficulty to push your limits.  
-
-🌐 Multiplayer: Compete with friends and strangers to prove you are the best.
-
-🌐 Localized: Available in Spanish and English.
-
-## Contributors
-Contributor | Contact
--- | -- 
-Gonzalo Alonso Fernández | <a href="https://github.com/gony02"><img src="https://img.shields.io/badge/UO282104-Gonzalo Alonso-red"></a>
-Sergio Rodríguez García | <a href="https://github.com/sergiorodriguezgarcia"><img src="https://img.shields.io/badge/UO282598-Sergio Rodríguez-orange"></a>
-Jorge Joaquín Gancedo Fernández | <a href="https://github.com/jjgancfer"><img src="https://img.shields.io/badge/UO282161-Jorge Joaquín Gancedo-yellow"></a>
-Darío Gutiérrez Mori | <a href="https://github.com/Toto-hitori"><img src="https://img.shields.io/badge/UO282435-Darío Gutiérrez-green"></a>
-Sergio Quintana Fernández | <a href="https://github.com/sergioqfeg1"><img src="https://img.shields.io/badge/UO288090-Sergio Quintana-cyan"></a>
-Diego Villanueva Berros | <a href="https://github.com/UO283615"><img src="https://img.shields.io/badge/UO283615-Diego Villanueva-blue"></a>
-Gonzalo Suárez Losada | <a href="https://github.com/uo283928"><img src="https://img.shields.io/badge/UO283928-Gonzalo Suárez-pink"></a>
-
-***
-
-
-[![Deploy on release](https://github.com/Arquisoft/wiq_en2b/actions/workflows/release.yml/badge.svg)](https://github.com/Arquisoft/wiq_en2b/actions/workflows/release.yml)
-[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=Arquisoft_wiq_en2b&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=Arquisoft_wiq_en2b)
-[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=Arquisoft_wiq_en2b&metric=coverage)](https://sonarcloud.io/summary/new_code?id=Arquisoft_wiq_en2b)
-
-This is a repository for the [Software Architecture course](http://arquisoft.github.io/) in [2023/2024 edition](https://arquisoft.github.io/course2324.html).
-
-This repo is a basic application composed of several components.
-
-Component | Route | Description
--- | -- | --
-Backend/API | `api/` | The main backend service, implemented in Java SpringBoot. It serves all requests from the frontend, and it doubles as main API. It also has a JWT-based authentication system.
-Question generator | `questiongenerator/` | A SpringBoot-based service, ran alongside the main backend service, that generates questions and inserts them into the database
-Webapp | `webapp/` | Our own frontend to the backend. It is implemented in React 18.
-
-***
-
-Both the backend/API and the question generator use PostgreSQL.
+# 🧠🤔 KiWiq 🥝❓📚
+Visit our page [here!!!](http://kiwiq.run.place/).
+
+WIQ is a quiz game project inspired by the engaging and thought-provoking show "Saber y Ganar." 
+We aim to create a platform that not only challenges your knowledge but also sparks curiosity and the thrill of discovery.
+
+
+## What Sets WIQ Apart
+🤔 Thoughtful Questions: Dive into a world of intriguing and diverse questions, all generated procedurally using WikiData.  
+🌐 Encourage to improve: WIQ lets you keep track of your score to see in which areas you need to improve. 
+
+😭 It works! after the final version final re-final (FINAL) true (final) (hotfix)
+
+## Features
+🏆 Adaptable  difficulty: You can adjust the difficulty to push your limits.  
+
+🌐 Multiplayer: Compete with friends and strangers to prove you are the best.
+
+🌐 Localized: Available in Spanish and English.
+
+## Contributors
+Contributor | Contact
+-- | -- 
+Gonzalo Alonso Fernández | <a href="https://github.com/gony02"><img src="https://img.shields.io/badge/UO282104-Gonzalo Alonso-red"></a>
+Sergio Rodríguez García | <a href="https://github.com/sergiorodriguezgarcia"><img src="https://img.shields.io/badge/UO282598-Sergio Rodríguez-orange"></a>
+Jorge Joaquín Gancedo Fernández | <a href="https://github.com/jjgancfer"><img src="https://img.shields.io/badge/UO282161-Jorge Joaquín Gancedo-yellow"></a>
+Darío Gutiérrez Mori | <a href="https://github.com/Toto-hitori"><img src="https://img.shields.io/badge/UO282435-Darío Gutiérrez-green"></a>
+Sergio Quintana Fernández | <a href="https://github.com/sergioqfeg1"><img src="https://img.shields.io/badge/UO288090-Sergio Quintana-cyan"></a>
+Diego Villanueva Berros | <a href="https://github.com/UO283615"><img src="https://img.shields.io/badge/UO283615-Diego Villanueva-blue"></a>
+Gonzalo Suárez Losada | <a href="https://github.com/uo283928"><img src="https://img.shields.io/badge/UO283928-Gonzalo Suárez-pink"></a>
+
+***
+
+
+[![Deploy on release](https://github.com/Arquisoft/wiq_en2b/actions/workflows/release.yml/badge.svg)](https://github.com/Arquisoft/wiq_en2b/actions/workflows/release.yml)
+[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=Arquisoft_wiq_en2b&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=Arquisoft_wiq_en2b)
+[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=Arquisoft_wiq_en2b&metric=coverage)](https://sonarcloud.io/summary/new_code?id=Arquisoft_wiq_en2b)
+
+This is a repository for the [Software Architecture course](http://arquisoft.github.io/) in [2023/2024 edition](https://arquisoft.github.io/course2324.html).
+
+This repo is a basic application composed of several components.
+
+Component | Route | Description
+-- | -- | --
+Backend/API | `api/` | The main backend service, implemented in Java SpringBoot. It serves all requests from the frontend, and it doubles as main API. It also has a JWT-based authentication system.
+Question generator | `questiongenerator/` | A SpringBoot-based service, ran alongside the main backend service, that generates questions and inserts them into the database
+Webapp | `webapp/` | Our own frontend to the backend. It is implemented in React 18.
+
+***
+
+Both the backend/API and the question generator use PostgreSQL.
+
+## Deploying the application
+
+Want to deploy the application? Check out [our quickstart guide](./Quickstart.md).