add some documentations (digital-peaks#116)

* add backup document
* refactor README

Makefile

@@ -1,7 +1,3 @@
-serve:
-	docker-compose pull frontend
-	docker-compose up --build
-
 migrate:
 	docker-compose run --rm migration
 
@@ -10,8 +6,13 @@ clean-db:
 	docker-compose rm -f mongodb
 	rm -rf ./mongo/volume
 
+dev-run:
+	docker-compose down
+	docker-compose pull
+	docker-compose --env-file .env up --no-build
+
 prod-pull-run:
-	sudo docker-compose down
+	docker-compose down
 	git pull
-	sudo docker-compose pull
-	sudo docker-compose --env-file .env.production up --no-build -d
+	docker-compose pull
+	docker-compose --env-file .env.production up --no-build -d

README.md

@@ -1,5 +1,50 @@
 # Web AOA
 
+## Getting started
+
+> Make sure you are using Docker 20.x and Docker Compose 1.29.x
+
+1. Run the services without building the docker containers:
+   ```sh
+   make dev-run
+   ```
+   > This will pull all docker images from DockerHub.
+2. The following services should be available:
+   - Frontend: http://localhost/
+   - API: http://localhost/api
+   - API Swagger Documentation: http://localhost/api/docs
+3. Migrate a dummy user (for local usage only)
+   ```sh
+   make migrate
+   ```
+   User credentials:  
+   Email: [email protected]  
+   Password: cycling8
+4. Login and run a job: http://localhost/
+
+> **Clean you local data:** Sometimes it's useful to reset all local data (troubleshoots). With `make clean-db` the whole MongoDB will be deleted. And all files in the `./job` folder needs to be removed.
+
+## Useful documents
+
+- [R Script](./docs/r_script.md)
+- [Manage users](./docs/users.md)
+- [Production Deployment](./docs/deployment.md)
+- [Backup](./docs/backup.md)
+
+## Development
+
+```sh
+docker-compose up
+```
+
+Or add the build flag to make sure, that everything is up to date.
+
+```sh
+docker-compose up --build
+```
+
+> All changes in `src` will be reloaded after the code (file) is changed. No need to restart the docker container.
+
 ## Configuration
 
 There are a few environment variables (see `.env`) that can be set to configure the services dynamically.
@@ -28,37 +73,3 @@ The following environment variables are required for the first start. It's not p
 | `MONGO_INITDB_API_PASSWORD`  | `-`     | MongoDB API password.  |
 
 > Please make sure you're using the right credentials (`MONGO_INITDB_API_*`) for `MONGODB_CONNECTION_STRING`.
-
-## Development
-
-```sh
-docker-compose up
-```
-
-Or add the build flag to make sure, that everything is up to date.
-
-```sh
-docker-compose up --build
-```
-
-> All changes in `src` will be reloaded after the code (file) is changed. No need to restart the docker container.
-
-## Production
-
-All relevant commands will be run with the following build command. For more information see the `Makefile`.
-
-```sh
-make prod-pull-run
-```
-
-> Please use the `.env` for your `.env.production` and change the credentials!
-> For more information about the environment variables see the section [Configuration](#configuration).
-
-### Prepare certificate for Haproxy
-
-```
-sudo cat "/etc/letsencrypt/live/domain.com/fullchain.pem" \
-    "/etc/letsencrypt/live/domain.com/privkey.pem" > "/etc/ssl/domain.com.pem"
-```
-
-The path `/etc/ssl/domain.com.pem` should be mounted via `HAPROXY_CERT`.

docs/backup.md

@@ -0,0 +1,13 @@
+# Create backups
+
+All relevant data will be saved in a [MongoDB](https://www.mongodb.com) (NoSQL database) and on the hard drive.
+
+## Backup MongoDB
+
+The simplest way to backup the MongoDB data is to use `rsync` or `cp`. The `docker-compose.yaml` creates a volume in the folder `./mongo/volume`. The whole folder is relevant for the backup.
+
+More information MongoDB backup strategies: [MongoDB Backup Methods](https://docs.mongodb.com/manual/core/backups/)
+
+## Backup job files
+
+By default all job files will be saved under `./jobs`. The whole folder needs to copied by `rsync` or `cp`.

docs/deployment.md

@@ -0,0 +1,20 @@
+# Production Deployment
+
+All relevant commands will be run with the following build command. For more information see the `Makefile`.
+
+```sh
+make prod-pull-run
+```
+
+> Please use the `.env` for your `.env.production` and change the credentials!
+
+> For more information about the environment variables see the section [Configuration](../README.md#configuration).
+
+### Prepare certificate for HAProxy
+
+```
+sudo cat "/etc/letsencrypt/live/domain.com/fullchain.pem" \
+    "/etc/letsencrypt/live/domain.com/privkey.pem" > "/etc/ssl/domain.com.pem"
+```
+
+The path `/etc/ssl/domain.com.pem` should be mounted via `HAPROXY_CERT`.

docs/users.md

@@ -1,4 +1,4 @@
-# Users
+# Manage Users
 
 The following endpoints are protected with a `X-API-KEY` header: