From d728b5837b9cae55fbbf474db7b9faaa8ce35463 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?R=C3=A9mi=20PAILHAREY?= <rpailharey@grandlyon.com>
Date: Fri, 22 Sep 2023 13:47:03 +0000
Subject: [PATCH] feat: better backoffice local config
---
docs/ecolyo-agent/technical/api_routes.md | 4 -
docs/ecolyo-agent/technical/deploy.md | 63 ---------
.../ecolyo-agent/technical/getting_started.md | 133 +++++++++---------
docs/ecolyo-agent/technical/handle_assets.md | 10 +-
.../technical/swagger_documentation.md | 13 ++
mkdocs.yml | 16 +--
6 files changed, 94 insertions(+), 145 deletions(-)
delete mode 100644 docs/ecolyo-agent/technical/api_routes.md
create mode 100644 docs/ecolyo-agent/technical/swagger_documentation.md
diff --git a/docs/ecolyo-agent/technical/api_routes.md b/docs/ecolyo-agent/technical/api_routes.md
deleted file mode 100644
index 82daf7f..0000000
--- a/docs/ecolyo-agent/technical/api_routes.md
+++ /dev/null
@@ -1,4 +0,0 @@
-# API Routes
-
-The different routes exposed by the backend are described by Swagger documentation in local env. The documentation is NOT exposed in REC or PROD.
-Once the client is deployed, the documentation is accessible at <https://localhost/doc/>
diff --git a/docs/ecolyo-agent/technical/deploy.md b/docs/ecolyo-agent/technical/deploy.md
index f050fa5..f368ac6 100644
--- a/docs/ecolyo-agent/technical/deploy.md
+++ b/docs/ecolyo-agent/technical/deploy.md
@@ -7,66 +7,3 @@ This app is deployed on an Openshift cluster provided by Synaaps, all instructio
This app has a gitlab CI/CD pipeline you can find in the .gitlab-ci.yml file.
On the dev branch and on merge requests, the pipeline will run a build stage and a quality stage.
On dev and master branches, the pipeline will run a docker image build that you can find in the GitLab container registry.
-
-
-## Alpha usage
-
-In order to test the app on alpha you can do the following steps:
-
-- Build locally your docker image for the client and/or the server
-
-```sh
-docker build . -t registry.forge.grandlyon.com/web-et-numerique/factory/llle_project/backoffice-<server/client>:your-tag
-```
-
-- Push the image
-
-```sh
-docker push registry.forge.grandlyon.com/web-et-numerique/factory/llle_project/backoffice-<server/client>:your-tag
-```
-
-- Connect to alpha in ssh, go to ecolyo-agent > docker-compose.yml and change the image tag for client and/or server
-
-- Then launch the app, it will pull automatically the new images
-
-```sh
-docker-compose up -d
-```
-
-- If you have access denied issue, try to docker login
-
-```sh
-docker login registry.forge.grandlyon.com/web-et-numerique/factory/llle_project/
-```
-
-- If you want to update alpha using the same image tag with edited image, just pull manually your new image and rebuild the concerned image
-
-```sh
-docker pull registry.forge.grandlyon.com/web-et-numerique/factory/llle_project/backoffice-<server/client>:your-tag
-
-docker-compose up -d
-```
-
-If you need to work with prices on alpha, you will need to init the prices database.
-
-- First get the mysql container id
-
-```sh
-docker ps
-```
-
-- Then get into the container
-
-```sh
-docker exec -it <container-id> bash
-```
-
-- Then execute the mysql script that imports all the prices in DB
-
-```sh
-mysql --local-infile=1 -uroot -p backoffice < /dbinit/dbinit.sql
-```
-
-You will be prompted for the admin password, use the db password set in the .env file.
-
-Now you're ready to edit your prices on alpha !
diff --git a/docs/ecolyo-agent/technical/getting_started.md b/docs/ecolyo-agent/technical/getting_started.md
index 18e468e..1eb9a52 100644
--- a/docs/ecolyo-agent/technical/getting_started.md
+++ b/docs/ecolyo-agent/technical/getting_started.md
@@ -15,110 +15,107 @@ This project is split between a backend and frontend, each project has its own r
## Local usage
-!!! note
- Before launching the application, ensure you've properly filled the `.env` file according to the template. If needed please refer to a team member. The template contains
-
- - `IMAGE_FOLDER`: this variable specify the folder where ecogestures images are located. By default, you can place this folder at the same level as your project for a local usage. (not inside the project). For alpha, rec/prod environment, make sure the path indicated in docker-compose volumes correspond with the location of the image file on the server.
- - `MOCK_OAUTH2`: Set this variable to true while in local, so the OAuth2 dance will be mocked by backend and you will be able to login to your application.
- - `USERINFO_URL`: Set this variable to configure the user role
- - `http://localhost:8090/admininfo` to log in with admin role
- - `http://localhost:8090/animatorinfo` to log in with animator role
+### Ecolyo Agent - Server
-First, build the server image with :
+Here will be listed all steps to run Ecolyo Agent backend locally for development purposes.
-```sh
-docker build . -t backoffice-server
-```
+#### Config folder
-You can then launch the client with :
+If you run the backend for the first time you need to setup some folders.
-```bash
-yarn local-up
-```
+At the repository root, run `mkdir -p mnt mnt/configs`
-This command will launch the app from the `docker-compose.local.yml`` file, which will launch 4 images and start the react app with _yarn start_
+The `mnt/configs` folder will contain a `tokenskey.json` file, generated when the server starts for the first time.
-- The backend Go app, from the image located on its Gitlab repository
-- A mySQL database, from the DockerHub image
-- A phpMyAdmin to browse the database, from the DockerHub image
-- The Nginx server with a local configuration located in nginx/site.conf
+With assets imported (see [this page](../handle_assets/#local-setup) for more information) the `mnt` folder should look like this :
-???note "Nginx info"
- The nginx server redirects https requests from front-end to the backend on port 1443.
+```bash
+mnt
+└───configs
+│ tokenskey.json
+└───image-lib
+ │ ...all email assets
+ └───ecogesture
+ │ ...all ecogesture images
+```
- It has two configuration files :
+#### Launch database
- - `nginx/site.conf`, used for local development
- - `nginx/site.prod.conf`, used for production
+The backend needs a database to store data, to start it, run `docker compose up -d`
- The nginx server needs local ssl certificates in order to run an interact with backend, these certificates are present in the project.
+This will serve a mySQL database on port `3306` and a phpMyAdmin instance, accessible on <http://localhost:8008> (login / password correspond to `DATABASE_USER` and `DATABASE_PASSWORD` variables in the `.env` file) to browse data more easily.
-### Fluid prices initialisation
+#### Initialize fluid prices
-To initialize the database with fluid prices, run the following commands :
+The backend contains prices evolution for each fluids. These prices need to be initialized.
-```shell
-cd scripts
-./init-fluidprices.sh
-```
+To do so, make sure the database container is up and running and run `./scripts/init-fluidprices.sh`
-To stop it properly use
+#### Launch server
-```bash
-yarn local-down
-```
+!!! note
+ Before launching the application, ensure you've properly filled the `.env` file according to the template. If needed please refer to a team member. The template contains
-??? note "for windows users"
- :warning: **If you are launching the project from a Windows OS** : Make sure to comment the 'extra_hosts' lines in the docker-compose.local file. Otherwise, you you won't be able to access your machine's localhost from the docker container.
+ - `IMAGE_FOLDER`: this variable specify the folder where ecogestures images are located. By default, it should be `mnt/image-lib`.
+ - `MOCK_OAUTH2`: Set this variable to true while in local, so the OAuth2 dance will be mocked by backend and you will be able to login to your application.
+ - `USERINFO_URL`: Set this variable to configure the user role
+ - `http://localhost:8090/admininfo` to log in with admin role
+ - `http://localhost:8090/animatorinfo` to log in with animator role
-To check if the application starts successfully, launch the command
+Now, you can run the backend with VS Code, check `Run and Debug` tab and click the `Start` icon on `Launch Backoffice Server`.
-```bash
-docker logs backoffice-client_backend_1
-```
+You can also press the F5 key as a shortcut.
-You should obtain the following messages:
+The server is up, you should obtain the following messages in the `Debug Console`:
> --- Server is starting ---
> Token signing key set
> Mock OAuth2 server Listening on: <http://localhost:8090>
-Once the application is started, you can access it at <https://localhost>
+Hot reload could not be set up to work 100% correctly, but you can click the Restart icon (or press Ctrl+Shift+F5) in VS Code after you made some modifications to restart the server.
-!!! tip
- This app runs in https, such as the backend, to access it go on <https://localhost/>
- Also make sure you have HTTPS env variable set to true.
- **Do not** use the app with the port 3000, you won't be able to login.
+#### Stop backend
+
+In VS Code, press the Stop icon (or press Shift+F5) to stop backend.
+
+Then run `docker-compose down` to stop database and phpMyAdmin containers
+
+### Ecolyo Agent - Client
-Once an animator/admin is connected, he must call the /whoAmI route to access his XSRF-TOKEN and add it in a header named "XSRF-TOKEN" for all requests going to the backend.
+#### Launch client
-## Ecolyo Agent - Server
+In the frontend repository, you can launch the client with :
-### Features
+```bash
+yarn local-up
+```
-- Authentification using OAuth2
-- Connected admins can use an API to edit and save different sections of the newsletters that will be sent to Ecolyo users
-- Exposes a public route to get the sections of a specific or the last newsletter
+??? warning "for windows users"
+ Make sure to comment the 'extra_hosts' lines in the docker-compose.local file. Otherwise, you you won't be able to access your machine's localhost from the docker container.
-### Setup
+This command will launch the app from the `docker-compose.local.yml` file, which will launch an Nginx server with a local configuration located in nginx/site.local.conf and start the react app with _yarn start_
-This backend should be deployed with the frontend using [local command](#local-usage)
+???note "Nginx info"
+ The nginx server redirects https requests from front-end to the backend on port 1443.
-However this backend can be run in standalone :
+ It has two configuration files :
-- Set a .env file at the root and add all variables declared in the template.env
-- (Optional) Create new certificates by running cd dev_certificates && ./generate-certificates.sh
-- Run `docker-compose up -d`
+ - `nginx/site.local.conf`, used for local development
+ - `nginx/site.prod.conf`, used for production
-Once deployed, you can access to a Swagger documentation of the API on <https://${HOSTNAME}/swagger/index.html>
+ The nginx server needs local ssl certificates in order to run an interact with backend, these certificates are present in the project.
-### Launch locally
+Once the application is started, you can access it at <https://localhost>
-Launch all necessary services :
+!!! tip
+ This app runs in https, such as the backend, to access it go on <https://localhost/>
+ Also make sure you have HTTPS env variable set to true.
+ **Do not** use the app with the port 3000, you won't be able to login.
-Run `docker-compose up -d`
+#### Stop client
-In local you can access phpmyadmin interface to manage the database : <http://localhost:8008>
-Launch the server by pressing F5 on vscode, you will see the logs on the debug console.
+To stop it properly use
-All API routes are available on <https://localhost:1443>
+```bash
+yarn local-down
+```
diff --git a/docs/ecolyo-agent/technical/handle_assets.md b/docs/ecolyo-agent/technical/handle_assets.md
index f17b310..67a268d 100644
--- a/docs/ecolyo-agent/technical/handle_assets.md
+++ b/docs/ecolyo-agent/technical/handle_assets.md
@@ -1,8 +1,14 @@
# Handle email assets
-This section will allow you to import the assets used in the newsletter from Ecolyo
+In the newsletter section, the user can select an image for the monthly info. They are imported from the ecolyo assets repository but they need to be converted from `.svg` to `.png` and stored inside `mnt/image-lib` folder.
-## Import assets
+## Local setup
+
+!!! warning "To run the following script you need to install inkscape (currently 1.3) to convert SVG to PNG. Follow the steps on the official website <https://inkscape.org/release/inkscape-1.3>"
+
+To do so, run `./scripts/import-convert-assets.sh`
+
+## REC/PROD setup
When email or ecogesture assets changes in Ecolyo project, you need to update them in the backoffice's server.
diff --git a/docs/ecolyo-agent/technical/swagger_documentation.md b/docs/ecolyo-agent/technical/swagger_documentation.md
new file mode 100644
index 0000000..c05e3ba
--- /dev/null
+++ b/docs/ecolyo-agent/technical/swagger_documentation.md
@@ -0,0 +1,13 @@
+# Swagger documentation
+
+The different routes exposed by the backend are described by Swagger documentation in local env. The documentation is NOT exposed in REC or PROD.
+Once the client is deployed, the documentation is accessible at <https://localhost/doc/>
+
+To build Swagger documentation :
+
+- Make sure you installed swag by running : `go install github.com/swaggo/swag/cmd/swag@latest`
+!!! tip
+ If "command not found: swag" or "No such file or directory", run `export PATH=$PATH:$(go env GOPATH)/bin`
+- go to server repository and run `./scripts/init-swagger-doc.sh`
+
+This will update `docs/swagger.json` and `docs/swagger.yaml` based on the annotations written above exposed methods.
diff --git a/mkdocs.yml b/mkdocs.yml
index b55d755..0125eff 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -1,14 +1,14 @@
site_name: Self-Data Grandlyon - Technical Docs
site_description: A Collection of Technical Documentations Related to the Self-Data Grandlyon Projects.
site_author: Métropole de Lyon
-repo_name: 'Forge'
-repo_url: 'https://forge.grandlyon.com/web-et-numerique/factory/llle_project/self-data-technical-doc'
-edit_uri: 'https://forge.grandlyon.com/web-et-numerique/factory/llle_project/self-data-technical-doc/-/blob/master/docs/'
+repo_name: "Forge"
+repo_url: "https://forge.grandlyon.com/web-et-numerique/factory/llle_project/self-data-technical-doc"
+edit_uri: "https://forge.grandlyon.com/web-et-numerique/factory/llle_project/self-data-technical-doc/-/blob/master/docs/"
theme:
- name: 'material'
- logo: 'img/self_data_grdlyon.png'
- favicon: 'img/self_data_grdlyon.png'
+ name: "material"
+ logo: "img/self_data_grdlyon.png"
+ favicon: "img/self_data_grdlyon.png"
palette:
scheme: dracula
primary: white
@@ -39,7 +39,7 @@ markdown_extensions:
alternate_style: true
extra_css:
- - 'stylesheets/extra.css'
+ - "stylesheets/extra.css"
plugins:
- search
@@ -101,7 +101,7 @@ nav:
- Technical:
- Getting started: ecolyo-agent/technical/getting_started.md
- Deploy: ecolyo-agent/technical/deploy.md
- - API Routes: ecolyo-agent/technical/api_routes.md
+ - Swagger documentation: ecolyo-agent/technical/swagger_documentation.md
- Handle assets: ecolyo-agent/technical/handle_assets.md
- Backup: ecolyo-agent/technical/backup.md
- Libraries: ecolyo-agent/technical/libraries.md
--
GitLab