Merge pull request #33 from esteinig/docs/readme-patch-1

docs(readme): add deployment and development sections

README.md

@@ -6,9 +6,22 @@
 
 `BRICK` is under active development. Please note there is currently no guarantee for data persistence in the web application or backwards compatabiltity until major version release. 
 
-## Stack deployment
+## Web service (convenient)
 
-`BRICK` is fairly easy to deploy on your local machine (desktop/laptop) if you have `Docker` installed. You can run a preconfigured local production stack of the latest release like this:
+At the moment, the most convenient way to get started is by using our web application ([https://brick.ink](https://brick.ink)).
+
+In the current iteration of the web application, note that:
+
+* File uploads and session data in the web application are automatically deleted seven days after creation
+* You can navigate away at any time and come back to the session page (unique identifier)
+* You can share your (editable) session with colleagues using the session page URL
+* Download your session data from the application to persist your visualization data
+
+Please note there is currently no guarantee for backwards compatability until major version release.
+
+## Local application (easy)
+
+You can run a pre-configured local production stack of the latest release with `Docker`:
 
 ```bash
 # Clone latest stable release on main
@@ -20,31 +33,73 @@ docker compose --profile prod up
 # Application available in your browser at: http://localhost:5173/ 
 ```
 
-The production stack comes with a database cleaner that removes sessions and session working directories in the `work` volume. 
+Some minor unit tests can be run with the `tests` service:
 
 ```bash
-docker compose --profile prod --profile server up 
+docker compose run tests
 ```
 
-Default interval (every day) and expiration time (7 days) can be changed in `docker-compose.yml`.
+Update to the latest stable version onm `main`:
 
-```yml
-command: brick utils clean --expire-days 7 --day-of-week "*" --time-of-day '04:00' --log /tmp/brick-cleaner.log
+```bash
+git pull # update main
+docker compose --profile prod up --build 
 ```
 
-Some minor unit tests can be run with the `tests` service:
+## Server application (advanced)
+
+See the `docker` subdirectory for reverse-proxy and alternative service configurations using `Traefik`. 
+
+If you are hosting your own instance of the application on the web, my assumption is that know what you are doing and have enough background knowledge to modify `docker/traefik/web/dynamic.yml` and `docker/docker-compose.web.yml`. Please ensure proper attribution if you are running your own web-instance, it helps to keep our main server running :heart:  
+
+In this example, we are using the pre-configured `localhost` reverse-proxy to test deployment on a local machine (`http://brick.localhost/`), assuming you have no other reverse-proxy service running:
 
 ```bash
-docker compose run tests
+# Create the external `proxy` network which 
+# connects your stack with the reverse-proxy
+docker network create proxy
+
+# Link the localhost stack and traefik service
+# into the current repository
+ln -s docker/docker-compose.localhost.yml .
+ln -s docker/docker-compose.traefik.localhost.yml .
+
+# Create a secrets directory captured in `.gitignore` 
+# and copy the default secret files for the stack database
+mkdir .secrets
+cp docker/mongodb/* .secrets/
+
+# Modify the secret files, one line per file, line endings are stripped 
+# automatically on server start in case you use `nano` or other editors
+# that introduce them by default
+
+# Up the reverse proxy service
+docker compose -f docker-compose.traefik.localhost.yml up -d
+
+# Up the production stack
+docker compose -f docker-compose.localhost.yml up
+
+# Application available in your browser at: http://brick.localhost/
 ```
 
-To update to the latest stable release version:
+The production stack comes with an (optional) database cleaner that safely removes sessions and session working directories in the `work` volume, which can be activated using the `--profile server` flag:
 
 ```bash
-git pull # update
-docker compose --profile prod up --build 
+docker compose --profile prod --profile server up 
 ```
 
+Default interval (every day) and expiration time (7 days) can be changed in `docker-compose.yml`:
+
+```yml
+command: brick utils clean --expire-days 7 --day-of-week "*" --time-of-day '04:00' --log /tmp/brick-cleaner.log
+```
+
+If you are running a web-instance through `Cloudflare` you need to set your SSL configuration to `strict`. 
+
+## Development
+
+Any and all questions, suggestions for improvement, bug reports, pull requests and ideas you would like to see implemented are welcome! Please open an [issue](https://github.com/esteinig/brick/issues) in this repository. Development and pull requests can be made on the [`dev`](https://github.com/esteinig/brick/tree/dev) branch.
+
 ## Dependencies
 
 `BRICK` would not be possible without the amazing work of bioinformaticians and researchers who make their software available open-source. 
@@ -75,4 +130,4 @@ Similarly, the stack would not be possible without the following amazing tools:
 
 ## Contributors
 
-Eike Steinig - @esteinig
+* Eike Steinig - @esteinig

docker/docker-compose.web.yml

@@ -23,7 +23,7 @@ services:
     env_file: docker/brick.env
     environment:
       NODE_ENV: production
-      ORIGIN: https://brick.ink
+      ORIGIN: https://{{{ traefik.web.domain }}}
       PRIVATE_DOCKER_API_URL: http://api:8080
     depends_on:
       - api
@@ -33,7 +33,7 @@ services:
     labels:
       traefik.enable: "true"
       traefik.docker.network: "proxy"
-      traefik.http.routers.app.rule: "Host(`brick.ink`)"
+      traefik.http.routers.app.rule: "Host(`{{{ traefik.web.domain }}}`)"
       traefik.http.routers.app.entrypoints: "https"
       traefik.http.routers.app.middlewares: "default@file"
       traefik.http.routers.app.tls.certresolver: "letsEncrypt"
@@ -59,7 +59,7 @@ services:
     env_file: docker/brick.env
     environment:
       NODE_ENV: development
-      ORIGIN: https://dev.brick.ink
+      ORIGIN: https://{{{ traefik.web.domain_dev }}}
       PRIVATE_DOCKER_API_URL: http://api-dev:8080
     depends_on:
       - api-dev
@@ -69,7 +69,7 @@ services:
     labels:
       traefik.enable: "true"
       traefik.docker.network: "proxy"
-      traefik.http.routers.app.rule: "Host(`dev.brick.ink`)"
+      traefik.http.routers.app.rule: "Host(`{{{ traefik.web.domain_dev }}}`)"
       traefik.http.routers.app.entrypoints: "https"
       traefik.http.routers.app.middlewares: "default@file"
       traefik.http.routers.app.tls.certresolver: "letsEncrypt"

docker/traefik/web/dynamic.yml

@@ -32,7 +32,7 @@ http:
   routers:
     # Traefik dashboard router
     traefik:
-      rule: "Host(`traefik.brick.ink`)"
+      rule: "Host(`traefik.{{{ traefik.web.domain }}}`)"
       service: "api@internal"
       entrypoints: 
         - "https"