From 19b48598b33c94e1a0e8fc264dd748aeefe66ae6 Mon Sep 17 00:00:00 2001 From: esteinig Date: Fri, 26 Jan 2024 10:22:27 +1100 Subject: [PATCH 1/2] docs(readme): deployment and development --- README.md | 81 ++++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 68 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index c553c66..1021269 100644 --- a/README.md +++ b/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 From e054d63a7495cdf9a7eb69c19deb5d5be90aa48d Mon Sep 17 00:00:00 2001 From: esteinig Date: Fri, 26 Jan 2024 10:23:16 +1100 Subject: [PATCH 2/2] fix(stack): agnostic domain templates --- docker/docker-compose.web.yml | 8 ++++---- docker/traefik/web/dynamic.yml | 2 +- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docker/docker-compose.web.yml b/docker/docker-compose.web.yml index 0c555be..b30e3cb 100644 --- a/docker/docker-compose.web.yml +++ b/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" diff --git a/docker/traefik/web/dynamic.yml b/docker/traefik/web/dynamic.yml index 2dac73e..d4cad17 100644 --- a/docker/traefik/web/dynamic.yml +++ b/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"