diff --git a/backend/README.md b/backend/README.md index a64e0ddaa..51c5f25e4 100644 --- a/backend/README.md +++ b/backend/README.md @@ -1,12 +1,12 @@ # Flotilla backend -The backend of flotilla is created using ASP.NET. +The backend of flotilla is created using ASP.NET. Useful documentation of concepts and features in the .NET frameworks can be found [here](https://docs.microsoft.com/en-us/dotnet/fundamentals/). ## Setup -To set up the backend on **Windows/Mac**, install visual studio and include the "ASP.NET and web development" workload during install. +To set up the backend on **Windows/Mac**, install visual studio and include the "ASP.NET and web development" workload during install. If you already have visual studio installed, you can open the "Visual Studio Installer" and modify your install to add the workload. To set up the backend on **Linux**, install .NET for linux @@ -35,7 +35,7 @@ dotnet run --project api ``` To change the ports of the application and various other launch settings (such as the Environment), this can be modified in -[launchSettings.json](api/Properties/launchSettings.json). +[launchSettings.json](api/Properties/launchSettings.json). Read more about the `launchSettings.json` file [here](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/environments?view=aspnetcore-6.0&preserve-view=true&viewFallbackFrom=aspnetcore-2.2#lsj) @@ -66,14 +66,14 @@ dotnet test The MQTT client is implemented in [MqttService.cs](api/MQTT/MqttService.cs) and runs as an ASP.NET -[BackgroundService](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/host/hosted-services?view=aspnetcore-6.0&tabs=visual-studio#backgroundservice-base-class). -Each MQTT message has its own class representation, and is linked to its respective topic pattern in [MqttTopics.cs](api/MQTT/MqttTopics.cs). +[BackgroundService](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/host/hosted-services?view=aspnetcore-6.0&tabs=visual-studio#backgroundservice-base-class). +Each MQTT message has its own class representation, and is linked to its respective topic pattern in [MqttTopics.cs](api/MQTT/MqttTopics.cs). To match incoming topic messages against the topic patterns we use helper functions to convert from the [MQTT wildcards](https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html#_Toc3901242) to regEx wildcards for the dictionnary lookup. Each topic then has it's respective [event](https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/events/) -which is triggered whenever a new message arrives in that topic. +which is triggered whenever a new message arrives in that topic. The list of topics being subscribe to is defined as an array in [appsettings.Development.json](api/appsettings.Development.json). @@ -83,13 +83,13 @@ An example of the subscriber pattern for an MQTT event is implemented in ## Configuration The project has two [appsettings](https://docs.microsoft.com/en-us/iis-administration/configuration/appsettings.json) -files. +files. The base `appsettings.json` file is for common variables across all environments, while the `appsetings.Development.json` file is for variables specific to the Dev environments, such as the client ID's for the various app registrations used in development. -The configuration will also read from a configured azure keyvault, which can then be accessed the same way as any other config variables. -For this to work you will need to have the client secret stored locally in the secret manager as described below. +The configuration will also read from a configured azure keyvault, which can then be accessed the same way as any other config variables. +For this to work you will need to have the client secret stored locally in the secret manager as described below. The client secret (and mqtt password if not connected to keyvault) should be in the following format: ``` diff --git a/broker/README.md b/broker/README.md index 918ffce29..baff5b3a7 100644 --- a/broker/README.md +++ b/broker/README.md @@ -2,8 +2,8 @@ ## Set up the broker -The broker expects a private key for its server x509 certificate used for TLS. -This must be provided through an environment variable called `FLOTILLA_BROKER_SERVER_KEY`. +The broker expects a private key for its server x509 certificate used for TLS. +This must be provided through an environment variable called `FLOTILLA_BROKER_SERVER_KEY`. This is a secret, and should be treated as such. It can be found in our keyvault. ### Automatic environment setup @@ -12,7 +12,7 @@ See [Flotilla readme](../README.md#automatic-environment-setup) ### Manual environment setup -The best way to pass this is to store it in a `.env` file in the root of flotilla, and docker compose loads this by default on startup. +The best way to pass this is to store it in a `.env` file in the root of flotilla, and docker compose loads this by default on startup. See [Using the “--env-file” option](https://docs.docker.com/compose/environment-variables/#using-the---env-file--option) for more information. ## Running the broker @@ -25,7 +25,7 @@ docker-compose up --build broker ## Authentication -The broker has been setup with role based authentication. +The broker has been setup with role based authentication. The current roles with their permissions per topic are described in the table below. | | read | write | @@ -43,7 +43,7 @@ They are defined in the [access_control file](./mosquitto/config/access_control) ## Installing broker outside of docker -To test the dockerized broker, the functions `mosquitto_sub` and `mosquitto_pub` are useful. +To test the dockerized broker, the functions `mosquitto_sub` and `mosquitto_pub` are useful. To gain access to them on your machine you will need to install the mosquitto broker. ### Linux installation @@ -67,7 +67,7 @@ Then add the installation folder to your PATH variable for the commands to be av ### Start non-docker broker If running the broker outside docker, you will need to manually create the `server-key.pem` file, containing the secret server key -mentioned in the [setup section](#set-up-the-broker). +mentioned in the [setup section](#set-up-the-broker). The mosquitto config file expects this file to be stored in the [mosquitto/config/certs](./mosquitto/config/certs) folder. The broker may then be started with @@ -78,8 +78,8 @@ mosquitto -p 1883 -c mosquitto/config/mosquitto.conf ## Testing the broker -To test that the broker functions as expected the `mosquitto_sub` and `mosquitto_pub` tools that are wrapped in the installation may be used. -For access to all topics, you need to use the admin user. +To test that the broker functions as expected the `mosquitto_sub` and `mosquitto_pub` tools that are wrapped in the installation may be used. +For access to all topics, you need to use the admin user. The password for the admin can be found in our keyvault. For the TLS encryption, you will need to reference the CA certificate. This is not a secret and can be found in [mosquitto/config/certs](./mosquitto/config/certs). diff --git a/frontend/README.md b/frontend/README.md index 1cbb54c4c..0de112c9b 100644 --- a/frontend/README.md +++ b/frontend/README.md @@ -56,7 +56,7 @@ This can be updated by cloning the [flotilla-openapi](https://github.com/equinor ## Formatting -We use prettier for formatting. +We use prettier for formatting. To test the formatting locally, run ``` @@ -64,10 +64,10 @@ npm run prettier_check ``` We recommend to install the [prettier extension for vs code](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) -and set the `format on save` option for vs code to true. +and set the `format on save` option for vs code to true. You can do this by going to `File` -> `Preferences` -> `Settings` and then searching for "Format On Save" and tick the box. ## Config -The application reads custom environment variables from the `.env` file on startup. The files need to be prefixed `REACT_APP_` to be included in the application. +The application reads custom environment variables from the `.env` file on startup. The files need to be prefixed `REACT_APP_` to be included in the application. These are parsed and defined in [config.ts](./src/config.ts).