From 4c9aacb134a7fef5f3f1dd717833d3221ce40a0b Mon Sep 17 00:00:00 2001 From: MoritzWeber Date: Thu, 25 Apr 2024 15:38:15 +0200 Subject: [PATCH] feat: Add Collaboration Manager integration Adds documentation for the integration and adds support for non-root contexts. --- Dockerfile | 8 +++ README.md | 104 +++++++++++++++++++++++++++++++--- frontend/public/static/env.js | 2 +- 3 files changed, 104 insertions(+), 10 deletions(-) diff --git a/Dockerfile b/Dockerfile index 5ba7f75..afef193 100644 --- a/Dockerfile +++ b/Dockerfile @@ -38,9 +38,17 @@ EXPOSE 8000 COPY ./templates /views +# Cache directory has to be writable +RUN chmod -R 777 /home +ENV HOME=/home + COPY entrypoint.sh /entrypoint.sh RUN chmod +x /entrypoint.sh ENV MODEL_ENTRYPOINT=/model RUN chmod -R 777 ./frontend/dist/ +# Run as non-root user per default +USER 1001 + + ENTRYPOINT ["/entrypoint.sh"] diff --git a/README.md b/README.md index 2cd5ac5..2b959f5 100644 --- a/README.md +++ b/README.md @@ -8,16 +8,24 @@ ![image](https://github.com/DSD-DBS/capella-model-explorer/actions/workflows/build-test-publish.yml/badge.svg) ![image](https://github.com/DSD-DBS/capella-model-explorer/actions/workflows/lint.yml/badge.svg) -A webapp for exploring Capella models through simple "auto-generated" textual and graphical views. +A webapp for exploring Capella models through simple "auto-generated" textual +and graphical views. **Longer story**: -We see a larger non-MBSE crowd struggling with the things hidden in the model. With this app we expose model contents in an easy to review readable form with basic graphical annotations. Under the hood it uses Jinja templates enabling the tooling teams to support their users with model-derived documents of any shape and form. +We see a larger non-MBSE crowd struggling with the things hidden in the model. +With this app we expose model contents in an easy to review readable form with +basic graphical annotations. Under the hood it uses Jinja templates enabling +the tooling teams to support their users with model-derived documents of any +shape and form. **Use cases**: -- Provide insights into / "spell-out" the model for non-MBSE stakeholders via document-a-like dynamic views that describe model elements in a human-readable form. -- Provide meaningful default views (that can be further customized) for the key elements to kickstart the model exploration. +- Provide insights into / "spell-out" the model for non-MBSE stakeholders via + document-a-like dynamic views that describe model elements in a + human-readable form. +- Provide meaningful default views (that can be further customized) for the key + elements to kickstart the model exploration. There are a few more use cases but we will reveal them a bit later. @@ -30,17 +38,27 @@ docker build -t model-explorer:latest . docker run -e ROUTE_PREFIX="" -v /absolute/path/to/your/model/folder/on/host:/model -v $(pwd)/templates:/views -p 8000:8000 model-explorer ``` -Then open your browser at `http://localhost:8000/views` and start exploring your model. +Then open your browser at `http://localhost:8000/views` and start exploring +your model. -While the thing is running you can edit the templates in the `templates` folder and see the changes immediately in the browser. +While the thing is running you can edit the templates in the `templates` folder +and see the changes immediately in the browser. # Development (local) -To run the app in dev mode you'll need to first run `npm run build` - this is needed by the backend to have some statics to serve. Then run `npm run dev` in a terminal and `python -m capella_model_explorer.backend path_to_model path_to_templates` in another terminal. The backend and statically built frontend will be served at `http://localhost:8000`. The live frontend will be served by vite at `http://localhost:5173`(or similar, it will be printed in the terminal where you ran `npm run dev`). +To run the app in dev mode you'll need to first run `npm run build` - this is +needed by the backend to have some statics to serve. Then run `npm run dev` in +a terminal and +`python -m capella_model_explorer.backend path_to_model path_to_templates` in +another terminal. The backend and statically built frontend will be served at +`http://localhost:8000`. The live frontend will be served by vite at +`http://localhost:5173`(or similar, it will be printed in the terminal where +you ran `npm run dev`). # Documentation -Read the [full documentation on Github pages](https://dsd-dbs.github.io/capella-model-explorer). +Read the +[full documentation on Github pages](https://dsd-dbs.github.io/capella-model-explorer). # Installation @@ -75,7 +93,75 @@ cd frontend npm install ``` -then, to develop components `npm run storybook` and to develop the whole app `npm run dev` +then, to develop components `npm run storybook` and to develop the whole app +`npm run dev` + +# Integration in the Capella Collaboration Manager + +The Capella Model Explorer can be integrated into the +[Capella Collaboration Manager](https://github.com/DSD-DBS/capella-collab-manager). + +To do so, you need a running instance of the Capella Collaboration Manager. +Navigate to `Menu` > `Settings` > `Tools` > `Add a new tool` and fill in the +following configuration: + +```yaml +name: 'Capella model explorer' +integrations: + t4c: false + pure_variants: false + jupyter: false +config: + resources: + cpu: + requests: 0.4 + limits: 2 + memory: + requests: 1.6Gi + limits: 6Gi + environment: + MODEL_ENTRYPOINT: '{CAPELLACOLLAB_SESSION_PROVISIONING[0][path]}' + ROUTE_PREFIX: '{CAPELLACOLLAB_SESSIONS_BASE_PATH}' + connection: + methods: + - id: f51872a8-1a4f-4a4d-b4f4-b39cbd31a75b + type: http + name: default + ports: + metrics: 9118 + http: 8000 + redirect_url: '{CAPELLACOLLAB_SESSIONS_SCHEME}://{CAPELLACOLLAB_SESSIONS_HOST}:{CAPELLACOLLAB_SESSIONS_PORT}{CAPELLACOLLAB_SESSIONS_BASE_PATH}/' + monitoring: + prometheus: + path: /metrics + provisioning: + directory: /models + max_number_of_models: 1 + workspaces: + enabled: false +``` + +You can tune the resources according to your needs. + +After saving the configuration, you have to add a version for the new tool. +Since the Capella Model Explorer can load different Capella versions, we can +one generic version: + +```yaml +name: 'Generic' +config: + is_recommended: true + is_deprecated: false + sessions: + persistent: + image: https://ghcr.io/dsd-dbs/capella-model-explorer/model-explorer:latest + backups: + image: null + compatible_versions: [1, 2, 3, 4] +``` + +Replace the numbers in `compatible_versions` with the version IDs for the +versions you want to support. # Contributing diff --git a/frontend/public/static/env.js b/frontend/public/static/env.js index de09a67..83ba5c4 100644 --- a/frontend/public/static/env.js +++ b/frontend/public/static/env.js @@ -5,5 +5,5 @@ window.env = { ROUTE_PREFIX: "__ROUTE_PREFIX__", - API_BASE_URL: "http://localhost:8000__ROUTE_PREFIX__/api", + API_BASE_URL: "__ROUTE_PREFIX__/api", };