Merge pull request #1392 from openkfw/1380-improve-operator-documenta…

…tion

Improve operator documentation

docker-compose/.env_example

@@ -50,7 +50,7 @@ API_HOST=api
 
 # frontend
 FRONTEND_LOG_LEVEL=info
-FRONTEND_PORT=3001
+FRONTEND_PORT=3000
 INLINE_RUNTIME_CHUNK=false
 REACT_APP_VERSION=$npm_package_version
 

docker-compose/README.md

@@ -36,7 +36,7 @@ Make sure your are in the `docker-compose` folder and use following command to m
 Copy .env_example to .env to use the default configuration
 
 ```
-cp.env_example .env
+cp .env_example .env
 ```
 
 Deploy TruBudget
@@ -45,6 +45,12 @@ Deploy TruBudget
 docker-compose --project-directory . -f blockchain/docker-compose.alphanode.yml -f api/docker-compose.yml -f frontend/docker-compose.yml up
 ```
 
+When the setup has completed, you can open these URLs in the browser:
+
+Frontend: http://localhost:3000/
+
+API: http://localhost:8080/api/documentation/static/index.html
+
 Uninstall TruBudget
 
 ```

docs/operation-administration/architecture.md

@@ -0,0 +1,42 @@
+# Architecture in TruBudget
+
+## Core TruBudget
+A core TruBudget node consists of minimal components needed to function, namely a UI, an API and a Blockchain. However additional services are available to extend the capabilities of a core TruBudget node. These services are explained under [Additional Services](#additional-services).
+
+Following diagram shows the tech stack of the core TruBudget:
+
+![core-trubudget-architecture](./img/core-trubudget.png)
+
+## Additional Services
+TruBudget offers additional services, that enhance the core TruBudget experience through additional features. These services are:
+
+- [Provisioning Service](../../provisioning/README.md) - Used for populating TruBudget with test data
+- [Email Notification Service](../../email-notification-service/README.md) - Used to enable the email-notification feature
+- [Export Service](../../excel-export-service/README.md) - Used for exporting TruBudget data in an excel file.
+- [Storage Service](../../storage-service/README.md) - Used to enable users to attach documents to workflowitems, which are then stored in a separate storage.
+
+> Each service can be activated and deactivated individually.
+
+> Starting with TruBudget 2.x, usage of the document storage is needed in order to enable the use of documents in TruBudget.
+
+![trubudget-services](./img/trubudget-services.png)
+
+## Communication protocols in a TruBudget network
+In a TruBudget network there are two different protocols used for communication:
+- P2P (Multichain Protocol) - Used between nodes
+- HTTP/HTTPS - Used between components
+
+The following diagram shows the exact communication protocols used between each TruBudget component in a network.
+
+![trubudget-communication](./img/trubudget-communication.png)
+
+## Data Storage
+In TruBudget two types of data storage are used:
+- On-Chain - Most of the persistent data such as events is stored on the blockchain using [Multichain](https://www.multichain.com/).
+- Off-Chain - [Minio](https://min.io/) is used as blob storage for documents, and [Postgres](https://www.postgresql.org/) is used for emails. 
+
+## Multiple nodes architecture
+Following architecture diagram shows a network with 3 nodes from 3 different organizations including the tech stack and communication protocols.
+Organizations can decide which additional TruBudget features they want to add or if they want to connect their own (external) system via TruBudget's API.
+
+![trubudget-architecture](./img/Trubudget-architecture-diagram.PNG)

docs/operation-administration/debugging.md

@@ -0,0 +1,12 @@
+# Debugging TruBudget
+
+This guide should offer some information on how to debug the TruBudget application and deployments, if any issue appears and you are not sure where to start. This might not cover every possible scenario, so if you tried the following steps and are stuck, you could open a new issue and we will try to help.
+
+
+- **Everything is running:** Make sure all your components are up and running. Depending on your setup, please check that all TruBudget components haven't crashed. 
+- **Logs:** Check the logs of the TruBudget components that are affected. If you're not sure which component is affected start with the api (as most TruBudget logic happens there) and check components one by one. The logs should tell you exactly what went wrong, by showing an error message.
+- **Configuration:** Make sure the components are configured properly. Common configurations to check are: same environment variables in all components (e.g. the `api` and the `blockchain` need the same `MULTICHAIN_RPC_PASSWORD`), all mandatory environment variables are set, and others.
+- **Communication between components:** Make sure the communication between components is working properly, and the correct environment variables are set to enable the communication (especially IPs and ports in this case). 
+- **Insufficient resources:** Make sure the components are not failing due to insufficient resources. Especially if the node you are using has a lot of data stored, the blockchain and api components (at least) might need more resources (CPU, RAM and storage)
+- **Always use the latest version:** Check that you are using the latest available stable version of TruBudget. The issue you are experiencing might have already been addressed and fixed in the newest version.
+- **Bugs:** If no other option until now applied to your case and you think there is a problem with the TruBudget software, please open a [bug request](https://github.com/openkfw/TruBudget/issues/new?assignees=&labels=bug&projects=&template=1.bug.md) in our repository and we will get back to you.

docs/operation-administration/installation/README.md

@@ -1,6 +1,16 @@
 # Introduction
 
-This guide offers tutorials on some key features of TruBudget, like creating a new network, connecting to an existing network or updating the TruBudget instance. If for some reason you can't use docker and docker compose, you can follow the bare-metal guidelines.
+This guide offers tutorials on some key features of TruBudget, such as creating a new network, connecting to an existing network or updating the TruBudget instance. 
+
+In order to deploy and operate TruBudget, you have a few options. The most suitable option depends on the underlying infrastructure as well as what resources and technologies are available to you. The following options have been tested.
+
+### Kubernetes
+The most modern option is to deploy TruBudget on a Kubernetes cluster. We recommend using this option as it offers different benefits such as a high availability and fault tolerance (due to the existence of replica sets), as well as scalability and resource optimization. To set up TruBudget on a k8s cluster we offer helm charts and instructions in a [separate documentation file](https://github.com/openkfw/TruBudget/tree/main/helm). 
+
+### Docker-Compose
+Another option commonly used to set up TruBudget is using our docker-compose setup. This way, each TruBudget component will be started as a separate docker container and the persisted data will be stored using volumes.
+
+If for some reason you can't use docker and docker compose, you can follow the bare-metal guidelines.
 
 ## Table of Contents
 
@@ -14,4 +24,3 @@ This guide offers tutorials on some key features of TruBudget, like creating a n
   - [Docker](./connect-to-an-existing-network/docker.md) (recommended)
   - [Bare-Metal](./connect-to-an-existing-network/bare-metal.md)
 
-- [Update TruBudget](./../update-trubudget.md)