Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: Fix broken links in README #1322

Merged
merged 1 commit into from
Feb 6, 2024
Merged

docs: Fix broken links in README #1322

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
112 changes: 65 additions & 47 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,31 +12,39 @@
![push](https://github.com/DSD-DBS/capella-collab-manager/actions/workflows/push.yml/badge.svg)
[![codecov](https://codecov.io/github/DSD-DBS/capella-collab-manager/branch/main/graph/badge.svg?token=1UZHL2H54F)](https://codecov.io/github/DSD-DBS/capella-collab-manager)

A web platform for collaboration on MBSE and [Capella](https://www.eclipse.org/capella/) projects.

**Copyright 2021 - 2024 [DB InfraGO AG](https://fahrweg.dbinfrago.com/fahrweg-de),
licensed under Apache 2.0 License (see full text [here](./LICENSES/Apache-2.0.txt))**

Turn your local MBSE and Capella experience into a browser-based collaboration platform for
model-based projects. Designed to enable co-working across multiple organizations.
Here are some of the key features:

- Run MBSE related tools (Capella, Papyrus, Eclipse, pure::variants, Jupyter, etc.) in a browser
- Supports both Git and [Team for Capella](https://www.obeosoft.com/en/team-for-capella)
co-working models
A web platform for collaboration on MBSE and
[Capella](https://www.eclipse.org/capella/) projects.

**Copyright 2021 - 2024
[DB InfraGO AG](https://fahrweg.dbinfrago.com/fahrweg-de), licensed under
Apache 2.0 License (see full text [here](./LICENSES/Apache-2.0.txt))**

Turn your local MBSE and Capella experience into a browser-based collaboration
platform for model-based projects. Designed to enable co-working across
multiple organizations. Here are some of the key features:

- Run MBSE related tools (Capella, Papyrus, Eclipse, pure::variants, Jupyter,
etc.) in a browser
- Supports both Git and
[Team for Capella](https://www.obeosoft.com/en/team-for-capella) co-working
models
- Single sign-on (SSO) via [OAuth2](https://oauth.net/2/)
- No need to install or maintain local Capella clients - clients are made on demand in
an underlaying [Kubernetes](https://kubernetes.io/) cluster
- Access to projects and models is self-managed by project leads, model owners or
delegates
- Within a project a user could have read or read & write access. Read-only users don't
consume licenses in Team for Capella projects.
- Integration with Git repository management for backup and workflow automation around
the models.
- Diagram cache integration: Display Capella diagrams in the browser within seconds.
- Model badge integration: Each model displays an automatically generated model complexity badge.
- Automatic "garbage collection": Unused sessions are terminated to free up resources and reduce cost.
- Jupyter integration to talk to Capella models from the workspace and to automate tasks.
- No need to install or maintain local Capella clients - clients are made on
demand in an underlaying [Kubernetes](https://kubernetes.io/) cluster
- Access to projects and models is self-managed by project leads, model owners
or delegates
- Within a project a user could have read or read & write access. Read-only
users don't consume licenses in Team for Capella projects.
- Integration with Git repository management for backup and workflow automation
around the models.
- Diagram cache integration: Display Capella diagrams in the browser within
seconds.
- Model badge integration: Each model displays an automatically generated model
complexity badge.
- Automatic "garbage collection": Unused sessions are terminated to free up
resources and reduce cost.
- Jupyter integration to talk to Capella models from the workspace and to
automate tasks.

In addition, we have integrated commercial products:

Expand All @@ -45,7 +53,8 @@ In addition, we have integrated commercial products:
- Automatic repository monitoring
- UI to create and delete models
- Automatic license injection into sessions.
- Nightly synchronization from TeamForCapella repositories to Git repositories
- Nightly synchronization from TeamForCapella repositories to Git
repositories
- Automatic access management via session tokens.

- [pure::variants](https://www.pure-systems.com/purevariants)
Expand All @@ -61,16 +70,18 @@ In addition, we have integrated commercial products:
To deploy the application you need:

- [Docker](https://docs.docker.com/engine/install/ubuntu/) >= 20.10.X
- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl-linux/) >= 1.24 (Stargazer)
- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl-linux/) >=
1.24 (Stargazer)
- [helm](https://helm.sh/docs/intro/install/) >= 3.9.X
- [Make](https://www.gnu.org/software/make/manual/make.html) >= 3.82, recommended 4.X
- [Make](https://www.gnu.org/software/make/manual/make.html) >= 3.82,
recommended 4.X
- [Python](https://www.python.org/downloads/) >= 3.10

If you'd like to run it locally, these tools are additionally required:

- [k3d](https://k3d.io/) - a lightweight k8s cluster simulator
- On some systems: `nss-myhostname` to access the local container registry
(on Ubuntu you can get it via `sudo apt install libnss-myhostname`)
- On some systems: `nss-myhostname` to access the local container registry (on
Ubuntu you can get it via `sudo apt install libnss-myhostname`)

When you have all that installed you can do the following:

Expand All @@ -82,8 +93,7 @@ cd capella-collab-manager
make create-cluster
```

Then, choose one of the three options and run the
corresponding command:
Then, choose one of the three options and run the corresponding command:

1. Fetch Capella images from Github (without initial TeamForCapella support)

Expand All @@ -92,9 +102,9 @@ corresponding command:
```

2. Build Capella images locally (without initial TeamForCapella support) \
To reduce the build time, the default configutation only builds images for Capella 6.0.0.
If you want to build more images for different versions, set the environment variable `CAPELLA_VERSIONS`
with a space-separated list of semantic Capella versions.
To reduce the build time, the default configutation only builds images for Capella
6.0.0. If you want to build more images for different versions, set the environment
variable `CAPELLA_VERSIONS` with a space-separated list of semantic Capella versions.

```
export CAPELLA_VERSIONS="6.0.0 6.1.0"
Expand All @@ -106,22 +116,26 @@ corresponding command:
DEVELOPMENT_MODE=1 make deploy
```

3. Build Capella and TeamForCapella images locally (with initial TeamForCapella support)
3. Build Capella and TeamForCapella images locally (with initial TeamForCapella
support)

Read and execute the preparation in the Capella Docker images documentation: [TeamForCapella client base](https://dsd-dbs.github.io/capella-dockerimages/capella/t4c/base/#preparation).
Read and execute the preparation in the Capella Docker images documentation:
[TeamForCapella client base](https://dsd-dbs.github.io/capella-dockerimages/capella/t4c/base/#preparation).

Then, run the following command:

```
DEVELOPMENT_MODE=1 make deploy-t4c
```

It can take a long time to run, but shouldn't take more than 5 minutes.
Please wait until all services are in the "Running" state.
It can take a long time to run, but shouldn't take more than 5 minutes. Please
wait until all services are in the "Running" state.

If all goes well, you should find Capella Collaboration Manager running on <http://localhost:8080/>.
If all goes well, you should find Capella Collaboration Manager running on
<http://localhost:8080/>.

If you want to see the individual services in the web-based Kubernetes dashboard, you can run the following command:
If you want to see the individual services in the web-based Kubernetes
dashboard, you can run the following command:

```zsh
make dashboard
Expand All @@ -138,21 +152,24 @@ k3d registry delete k3d-myregistry.localhost

#### Starting a Session

Once the cluster is installed and all services are running (`kubectl get pods`), you can
get started. Follow our [Getting started guide](docs/getting_started/getting_started.md) and be up and
running in a few minutes.
Once the cluster is installed and all services are running
(`kubectl get pods`), you can get started. Follow our
[Getting started guide](https://dsd-dbs.github.io/capella-collab-manager/admin/getting_started/getting_started/)
and be up and running in a few minutes.

### Deployment

You can find the installation guide for the deployment in the [general documentation](https://capella-collaboration-manager.readthedocs.io/en/latest/installation/).
You can find the installation guide for a production deployment in the
[general documentation](https://dsd-dbs.github.io/capella-collab-manager/admin/installation/).

## How it Works

The Capella Collaboration Manager consists of a couple of components:

- A frontend - what you see in the browser
- A backend service - for managing projects, users and sessions
- [Guacamole](https://guacamole.apache.org/), to expose the sessions via the browser
- [Guacamole](https://guacamole.apache.org/), to expose the sessions via the
browser
- Databases, for state persistence
- Prometheus for session monitoring
- Grafana Loki for logs management
Expand All @@ -165,6 +182,7 @@ External software can also be linked. These parts can be installed separately:

## Contributing

We'd love to see your bug reports and improvement suggestions! Please take a look at
[guidelines for contributors](CONTRIBUTING.md).
We'd love to see your bug reports and improvement suggestions! Please take a
look at our
[developer documentation](https://dsd-dbs.github.io/capella-collab-manager/development/).
You'll also find instructions on how to set up a local development environment.
Loading