Enhancement/documentation

infra/README.md

@@ -2,12 +2,63 @@
 
 This folder stores various contents related to Basegun deployment.
 
-## Scripts
+## Full infrastructure of the project
+![](./img/full-infra.jpg)
 
-* `init.yaml` : file to prepare instance for terraform (update and install dependencies, add security settings)
-* `deploy.sh` : script launched at prod server start which downloads github repository archive and lauches the app
-* `docker-push.sh` : script for pushing docker images to [ghcr.io](https://github.com/orgs/datalab-mi/packages?repo_name=Basegun) which is our storage system for Basegun docker images
-* `test-alive.sh` : script for verifying Basegun website is available on the Internet
+1. Using Github actions, we trigger either the [*preprod* deployment](../.github/workflows/develop.yml) or the [*prod* deployment](../.github/workflows/release.yml).
+2. For both of them, the [workflow calls Terraform](../.github/workflows/deploy.yml) using specific env variables to differentiate preprod from prod, to start a VM on OVH public cloud.
+3. On the VM, we always have [3 containers](../docker-compose-prod.yml) :
+* 1 for Basegun frontend (Vue.js website)
+* 1 for Basegun backend (Python API)
+* 1 for the log collector (Filebeat )  
+The frontend communicates with the backend using HTTP requests on the API. On prod, the OVH service SSL Gateway puts itself as intermediary to provide HTTPS connection to the user (+ some benefits like load balancing, protection to DDoS...). We could only use 1 DNS for this service so for preprod we set up an additional container for Traefik which replaces the SSL Gateway to provide HTTPS for the user.
+4. The backend and Filebeat share a common volume on the VM, so that when the backend writes logs on the VM, Filebeat can collect them and send them to the OVH public cloud service Log Data Platform.
+5. The images uploaded in the frontend of Basegun are sent as blob data to the backend, which then uploads them directly to OVH public cloud object storage service using Python Swift API.
+
+
+
+## Terraform explanation
+
+Terraform is an open-source infrastructure as code (IaC) on Openstack project. It reads all files with a `.tf` extension. We separated the Terraform code in several files for better understandability but they are read by TF as one whole block.
+<img src="./img/terraform.jpg" width="700px" />
+
+### Classic conf files
+- `backend.tf` : the remote state (in Swift container), where current state is stored.
+- `provider.tf` : select provider (OVH)
+- `output.tf`
+- `version.tf` : version for terraform init
+
+### Variables
+We add TF variables in 2 different ways.
+- Variables related to **the instance** configuration are directly passed as env variables to Terraform using the prefix `TF_VAR`.
+The variables related to the instance are the following:
+    - fixed_ip: fixed ip for VM (populated with github secret `PREPROD_SERVER_IP` or `PROD_SERVER_IP`)
+    - flavor: code for VM size on OVH
+    - volume_size: size in GB of instance
+
+- Variables related to **Basegun product** are passed via `terraform apply --varfile="deployenv.tfvars"`. This `deployenv.tfvars` file is created by replacing the env variables from the CD in the file `env.tfvars`.
+The variables related to Basegun website are the folowing:
+    - API_OVH_TOKEN : credential token for logs (see Logging section)
+    - OS_USERNAME : username of cloud provider
+    - OS_PASSWORD : password for this user
+    - OS_PROJECT_NAME : value from `openrc.sh` (find on horizon platform)
+    - OS_PROJECT_ID : value from `openrc.sh` (find on horizon platform)
+    - WORKSPACE : preprod or prod
+    - X_OVH_TOKEN : token for logs (see Logging section)
+For practical reasons, we encapsulate all these variables in one large dictionary variable called `deploy_env`.
+
+> Regardless of how they are passed to Terraform, all variables must be declared in `variables.tf` file.
+
+### Instance deployment
+<img src="./img/openstack.png" width="300px" />
+
+The file `instance.tf` contains all details related to instance deployment.
+* VM size
+* VM base image (Debian)
+* IP (declared via network object)
+* SSH connexion configuration (keypair and port)
+
+The file `template.tf` decribes the files which must be rendered during deployment. Here we render 2 scripts, `init.yaml` as a cloud-init file (lauched at VM start), which installs dependencies and add security settings, and `deploy.sh` as a regular script file (therefore launched when VM is ready), which downloads github repository archive and launches the app.
 
 ## Logging
 ### Requirements
@@ -25,31 +76,6 @@ The logs are sent from the server to the endpoint using Filebeat. A Filebeat Doc
 
 In OVH Log Data Platform, we use Kibana to visualize the logs and make queries to extract valuable information from them.
 
-## Terraform deployment
-
-Terraform is an open-source infrastructure as code (IaC) on Openstack project.
-
-![](https://github.com/datalab-mi/Basegun/blob/develop/.github/img/openstack.png)
-
-### Configuration
-Add the following Github secrets:
-- OS_USERNAME : username of cloud provider
-- OS_PASSWORD : password for this user
-- OS_PROJECT_NAME : value from `openrc.sh` (find on horizon platform)
-- OS_PROJECT_ID : value from `openrc.sh` (find on horizon platform)
-- PERSO_ACCESS_TOKEN : github access token for publishing / deleting packages
-- PREPROD_SERVER_IP : fixed ip for preprod server
-
-### Terraform
-
-- `backend.tf` : the remote state (in Swift container), where current state is stored.
-- `instance.tf` : the desirated instance (image, flavor, volume size, network and address, security group)
-- `output.tf` : show ips output
-- `provider.tf` : select provider (OVH)
-- `template.tf` : prepare cloud init and deployment script
-- `variable.tf` : availables variables
-- `version.tf` : version for terraform init
-