| Name | capella-model-explorer JSON |
| Version |
0.2.5
JSON |
| download |
| home_page | None |
| Summary | A webapp for exploring Capella models |
| upload_time | 2025-02-06 11:16:54 |
| maintainer | None |
| docs_url | None |
| author | DB InfraGO AG |
| requires_python | <3.14,>=3.11 |
| license | Apache-2.0 |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
<!--
~ Copyright DB InfraGO AG and contributors
~ SPDX-License-Identifier: Apache-2.0
-->
# Capella Model Explorer
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.
**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.
There are a few more use cases but we will reveal them a bit later.
# Quick start
Clone, then build and run locally with Docker:
```bash
docker build -t model-explorer:latest .
docker run --name=cme -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.
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 `make build-frontend`. This
is needed by the backend to have some statics to serve. Then run `make
dev-backend` in one terminal and `make dev-frontend` 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 `make dev-frontend`).
# Installation
You can install the latest released version directly from PyPI.
```sh
pip install capella-model-explorer
```
To set up a development environment, clone the project and install it into a
virtual environment.
```sh
git clone https://github.com/DSD-DBS/capella-model-explorer
cd capella-model-explorer
python -m venv .venv
source .venv/bin/activate.sh # for Linux / Mac
.venv\Scripts\activate # for Windows
pip install -U pip pre-commit
pip install -e '.[docs,test]'
pre-commit install
```
# Development
This repo contains a Makefile with recipes for a few commonly needed tasks
during development. Run `make help` for more details.
## Developing the frontend
To develop frontend components, run:
```bash
make storybook
```
To develop the app as a whole, run:
```bash
make dev-frontend
```
Note that this requires a running backend server, see the next section.
## Backend development
To run the backend, use the following command:
```bash
make run MODEL=../path/to/model.aird
```
This will start the API server on <http://localhost:8000>, where it will serve
the frontend in production mode. These static files can be rebuilt with `make
build-frontend`, although it is usually more convenient to run the frontend in
development mode with `make dev-frontend` (see above).
The MODEL parameter can be set to anything that
[`capellambse.loadcli`](https://dsd-dbs.github.io/py-capellambse/start/specifying-models.html)
understands, but some functionality requires a Git-backed model (e.g. using a
`git+https://` URL).
# 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:
stage: before
value: "{CAPELLACOLLAB_SESSION_PROVISIONING[0][path]}"
ROUTE_PREFIX: "{CAPELLACOLLAB_SESSIONS_BASE_PATH}"
connection:
methods:
- id: f51872a8-1a4f-4a4d-b4f4-b39cbd31a75b
type: http
name: Direct Browser connection
sharing:
enabled: true
ports:
metrics: 8000
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
persistent_workspaces:
mounting_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
use one generic version:
```yaml
name: "Generic"
config:
is_recommended: true
is_deprecated: false
sessions:
persistent:
image: 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.
When configured properly, users will be able to start read-only sessions for
the Capella Model Explorer. More information about read-only sessions is
available in the
[Capella Collaboration Manager documentation](https://dsd-dbs.github.io/capella-collab-manager/user/sessions/types/read-only/).
# Contributing
We'd love to see your bug reports and improvement suggestions! Please take a
look at our [guidelines for contributors](CONTRIBUTING.md) for details.
# Licenses
This project is compliant with the
[REUSE Specification Version 3.0](https://git.fsfe.org/reuse/docs/src/commit/d173a27231a36e1a2a3af07421f5e557ae0fec46/spec.md).
Copyright DB InfraGO AG, licensed under Apache 2.0 (see full text in
[LICENSES/Apache-2.0.txt](LICENSES/Apache-2.0.txt))
Dot-files are licensed under CC0-1.0 (see full text in
[LICENSES/CC0-1.0.txt](LICENSES/CC0-1.0.txt))
Raw data
{
"_id": null,
"home_page": null,
"name": "capella-model-explorer",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.14,>=3.11",
"maintainer_email": null,
"keywords": null,
"author": "DB InfraGO AG",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/c9/f5/d93b3828a7acbc5ba6ac33856b7ddc77da2d8dac40ca2759d207d0bce2b3/capella_model_explorer-0.2.5.tar.gz",
"platform": "any",
"description": "<!--\n ~ Copyright DB InfraGO AG and contributors\n ~ SPDX-License-Identifier: Apache-2.0\n -->\n\n# Capella Model Explorer\n\n\n\n\nA webapp for exploring Capella models through simple \"auto-generated\" textual\nand graphical views.\n\n**Longer story**:\n\nWe see a larger non-MBSE crowd struggling with the things hidden in the model.\nWith this app we expose model contents in an easy to review readable form with\nbasic graphical annotations. Under the hood it uses Jinja templates enabling\nthe tooling teams to support their users with model-derived documents of any\nshape and form.\n\n**Use cases**:\n\n- Provide insights into / \"spell-out\" the model for non-MBSE stakeholders via\n document-a-like dynamic views that describe model elements in a\n human-readable form.\n- Provide meaningful default views (that can be further customized) for the key\n elements to kickstart the model exploration.\n\nThere are a few more use cases but we will reveal them a bit later.\n\n# Quick start\n\nClone, then build and run locally with Docker:\n\n```bash\ndocker build -t model-explorer:latest .\ndocker run --name=cme -e ROUTE_PREFIX=\"\" \\\n -v /absolute/path/to/your/model/folder/on/host:/model \\\n -v \"$PWD/templates:/views\" -p 8000:8000 model-explorer\n```\n\nThen open your browser at `http://localhost:8000/views` and start exploring\nyour model.\n\nWhile the thing is running you can edit the templates in the `templates` folder\nand see the changes immediately in the browser.\n\n# Development (local)\n\nTo run the app in dev mode you'll need to first run `make build-frontend`. This\nis needed by the backend to have some statics to serve. Then run `make\ndev-backend` in one terminal and `make dev-frontend` in another terminal. The\nbackend and statically built frontend will be served at\n`http://localhost:8000`. The live frontend will be served by vite at\n`http://localhost:5173` (or similar, it will be printed in the terminal where\nyou ran `make dev-frontend`).\n\n# Installation\n\nYou can install the latest released version directly from PyPI.\n\n```sh\npip install capella-model-explorer\n```\n\nTo set up a development environment, clone the project and install it into a\nvirtual environment.\n\n```sh\ngit clone https://github.com/DSD-DBS/capella-model-explorer\ncd capella-model-explorer\npython -m venv .venv\n\nsource .venv/bin/activate.sh # for Linux / Mac\n.venv\\Scripts\\activate # for Windows\n\npip install -U pip pre-commit\npip install -e '.[docs,test]'\npre-commit install\n```\n\n# Development\n\nThis repo contains a Makefile with recipes for a few commonly needed tasks\nduring development. Run `make help` for more details.\n\n## Developing the frontend\n\nTo develop frontend components, run:\n\n```bash\nmake storybook\n```\n\nTo develop the app as a whole, run:\n\n```bash\nmake dev-frontend\n```\n\nNote that this requires a running backend server, see the next section.\n\n## Backend development\n\nTo run the backend, use the following command:\n\n```bash\nmake run MODEL=../path/to/model.aird\n```\n\nThis will start the API server on <http://localhost:8000>, where it will serve\nthe frontend in production mode. These static files can be rebuilt with `make\nbuild-frontend`, although it is usually more convenient to run the frontend in\ndevelopment mode with `make dev-frontend` (see above).\n\nThe MODEL parameter can be set to anything that\n[`capellambse.loadcli`](https://dsd-dbs.github.io/py-capellambse/start/specifying-models.html)\nunderstands, but some functionality requires a Git-backed model (e.g. using a\n`git+https://` URL).\n\n# Integration in the Capella Collaboration Manager\n\nThe Capella Model Explorer can be integrated into the\n[Capella Collaboration Manager](https://github.com/DSD-DBS/capella-collab-manager).\n\nTo do so, you need a running instance of the Capella Collaboration Manager.\nNavigate to `Menu` > `Settings` > `Tools` > `Add a new tool` and fill in the\nfollowing configuration:\n\n```yaml\nname: \"Capella model explorer\"\nintegrations:\n t4c: false\n pure_variants: false\n jupyter: false\nconfig:\n resources:\n cpu:\n requests: 0.4\n limits: 2\n memory:\n requests: 1.6Gi\n limits: 6Gi\n environment:\n MODEL_ENTRYPOINT:\n stage: before\n value: \"{CAPELLACOLLAB_SESSION_PROVISIONING[0][path]}\"\n ROUTE_PREFIX: \"{CAPELLACOLLAB_SESSIONS_BASE_PATH}\"\n connection:\n methods:\n - id: f51872a8-1a4f-4a4d-b4f4-b39cbd31a75b\n type: http\n name: Direct Browser connection\n sharing:\n enabled: true\n ports:\n metrics: 8000\n http: 8000\n redirect_url: \"{CAPELLACOLLAB_SESSIONS_SCHEME}://{CAPELLACOLLAB_SESSIONS_HOST}:{CAPELLACOLLAB_SESSIONS_PORT}{CAPELLACOLLAB_SESSIONS_BASE_PATH}/\"\n monitoring:\n prometheus:\n path: /metrics\n provisioning:\n directory: /models\n max_number_of_models: 1\n persistent_workspaces:\n mounting_enabled: false\n```\n\nYou can tune the resources according to your needs.\n\nAfter saving the configuration, you have to add a version for the new tool.\nSince the Capella Model Explorer can load different Capella versions, we can\nuse one generic version:\n\n```yaml\nname: \"Generic\"\nconfig:\n is_recommended: true\n is_deprecated: false\n sessions:\n persistent:\n image: ghcr.io/dsd-dbs/capella-model-explorer/model-explorer:latest\n backups:\n image: null\n compatible_versions: [1, 2, 3, 4]\n```\n\nReplace the numbers in `compatible_versions` with the version IDs for the\nversions you want to support.\n\nWhen configured properly, users will be able to start read-only sessions for\nthe Capella Model Explorer. More information about read-only sessions is\navailable in the\n[Capella Collaboration Manager documentation](https://dsd-dbs.github.io/capella-collab-manager/user/sessions/types/read-only/).\n\n# Contributing\n\nWe'd love to see your bug reports and improvement suggestions! Please take a\nlook at our [guidelines for contributors](CONTRIBUTING.md) for details.\n\n# Licenses\n\nThis project is compliant with the\n[REUSE Specification Version 3.0](https://git.fsfe.org/reuse/docs/src/commit/d173a27231a36e1a2a3af07421f5e557ae0fec46/spec.md).\n\nCopyright DB InfraGO AG, licensed under Apache 2.0 (see full text in\n[LICENSES/Apache-2.0.txt](LICENSES/Apache-2.0.txt))\n\nDot-files are licensed under CC0-1.0 (see full text in\n[LICENSES/CC0-1.0.txt](LICENSES/CC0-1.0.txt))\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "A webapp for exploring Capella models",
"version": "0.2.5",
"project_urls": {
"Documentation": "https://dsd-dbs.github.io/capella-model-explorer",
"Homepage": "https://github.com/DSD-DBS/capella-model-explorer"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "d86e94d4301fcbd8ac57307b0384f8e9eacb5395db40b33b33363cdd9dba33d5",
"md5": "c053f03aadd389c71337afb61788ac35",
"sha256": "25d1e0c80ff0ae9b04a8e60fd288198f6d14386181407e306c7979f78ea99664"
},
"downloads": -1,
"filename": "capella_model_explorer-0.2.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c053f03aadd389c71337afb61788ac35",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.14,>=3.11",
"size": 15067,
"upload_time": "2025-02-06T11:16:52",
"upload_time_iso_8601": "2025-02-06T11:16:52.450997Z",
"url": "https://files.pythonhosted.org/packages/d8/6e/94d4301fcbd8ac57307b0384f8e9eacb5395db40b33b33363cdd9dba33d5/capella_model_explorer-0.2.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "c9f5d93b3828a7acbc5ba6ac33856b7ddc77da2d8dac40ca2759d207d0bce2b3",
"md5": "3180e4926998762072b04ab615cad3b3",
"sha256": "09c335123f569ad21486c62431bf17460ebbc570e519621f7789883359526da5"
},
"downloads": -1,
"filename": "capella_model_explorer-0.2.5.tar.gz",
"has_sig": false,
"md5_digest": "3180e4926998762072b04ab615cad3b3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.14,>=3.11",
"size": 142860,
"upload_time": "2025-02-06T11:16:54",
"upload_time_iso_8601": "2025-02-06T11:16:54.415643Z",
"url": "https://files.pythonhosted.org/packages/c9/f5/d93b3828a7acbc5ba6ac33856b7ddc77da2d8dac40ca2759d207d0bce2b3/capella_model_explorer-0.2.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-06 11:16:54",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "DSD-DBS",
"github_project": "capella-model-explorer",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "capella-model-explorer"
}
