The image builder template builds the following images and pushes them to any +Docker registry:
+Please add the following section to your .gitlab-ci.yml:
include:
+ - remote: https://raw.githubusercontent.com/DSD-DBS/capella-collab-manager/${CAPELLA_COLLABORATION_MANAGER_REVISION}/ci-templates/gitlab/image-builder.yml
+The build images are tagged with the revision they were build with (e.g., when
+running for main the tag would be :main) All characters matching the regex
+[^a-za-z0-9.] will be replaced with -.
You have to add the following environment variables on repository level. Make +sure to enable the "Expand variable reference" flag.
+PRIVATE_GPG_PATH: Path to the private GPG key used to decrypt the
+ secret.docker.json file (More about this file below)FRONTEND_IMAGE_NAME (defaults to capella/collab/frontend)BACKEND_IMAGE_NAME (default to capella/collab/backend)DOCS_IMAGE_NAME (defaults to capella/collab/docs)GUACAMOLE_IMAGE_NAME (defaults to capella/collab/guacamole)In addition you can adjust the following variables when running a pipeline:
+FRONTEND: Build the frontend image?BACKEND: Build the backend image?DOCS: Build the docs image?GUACAMOLE: Build the guacamole image?TARGET: The target for which you want to build the images (More information
+ why this is important below)This is the (minimal) configuration. For more advanced configuration options, +please refer to the +image-builder +Gitlab template.
+We make use of Mozilla SOPS files to store
+secrets used in the image builder template. Therefore you need to have a
+directory $TARGET for each target with a secret.docker.json inside. You can
+create the secret.docker.json by running the following command:
sops -e --output ./<target>/secret.docker.json input.json
+The input.json in this command is a placeholder for your own input file,
+which should have the following structure:
{
+ "registry_unencrypted": "<registry>",
+ "username_unencrypted": "<username>",
+ "password": "<unencrypted password>"
+}
+Verify that you can open the secret file with
+sops ./<target>/secret.docker.json. When it works, delete the input.json!
In addition, you will need a .sops.yaml at the root level having the
+following structure:
creation_rules:
+ - path_regex: .*
+ key_groups:
+ - pgp:
+ - <GPG fingerprint>
+Any time you update the .sops.yaml (i.e., adding or removing a fingerprint)
+you will have to run sops updatekeys ./<target>/secret.docker.json to ensure
+that only authorized persons can decrypt the secret file.
Lastly, please ensure that your Gitlab runners GPG fingerprint is present in
+the .sops.yaml such that it can use the secret values.
The Kubernetes deploy template is used to deploy the Capella Collaboration +Manager to a Kubernetes cluster using Helm.
+Please add the following section to your .gitlab-ci.yml:
include:
+ - remote: https://raw.githubusercontent.com/DSD-DBS/capella-collab-manager/${CAPELLA_COLLABORATION_MANAGER_REVISION}/ci-templates/gitlab/k8s-deploy.yml
+You have to add the following environment variables on repository level. Make +sure to enable the "Expand variable reference" flag.
+PRIVATE_GPG_PATH: Path to the private GPG key used to decrypt the
+ secret.k8s.json files.GRAFANA_HELM_CHART: (Optional) - This variable is used to set the URL for
+ the Grafana Helm chart. It is useful if your deployment environment has
+ limited access, so you can specify a URL that is accessible for you.In addition you can adjust the following variables when running a pipeline:
+TARGET: The target for which you want to build the images (More information
+ why this is important below)REVISION: The revision of the capella collab manager repository you want to
+ useFor the k8s-deploy.yml you need to have some secret sops files in place.
+First of all, you need a secret.docker.json file as described
+here. In addition, you need to have a secret.k8s.json in
+each target directory created by a json file having the following structure:
{
+ "server_unencrypted": "<k8s server>",
+ "namespace_unencrypted": "<namespace>",
+ "release_unencrypted": "<release>",
+ "username_unencrypted": "<username>",
+ "token": "<unencrypted token>"
+}
+In addition, you need to have a general.values.yaml containing all the
+values.yaml values that do not have to be encrypted and a
+secret.values.yaml only containing the values that should be encrypted
+(Please do not use YAML anchors in the secret.values.yaml file and do not use
+the _unencrypted suffix in the variable names).
Please delete the plain text files containing secrets directly after encrypting +them.
+The tree inside of your Gitlab repository should look like:
+├── .gitlab-ci.yml
+├── .sops.yaml
+├── environment.prod.ts
+├── favicon.ico
+├── target1
+│ ├── general.values.yaml
+│ ├── secret.values.yaml
+│ ├── secret.docker.json
+│ └── secret.k8s.json
+├── target2
+│ ├── general.values.yaml
+│ ├── secret.values.yaml
+│ ├── secret.docker.json
+│ └── secret.k8s.json
+└── ...
+This is the (minimal) configuration. For more advanced configuration options, +please refer to the +k8s-deploy +Gitlab template.
+ + + + + + + + + + + + + +The Collaboration Manager repository contains a few tools that may come in +handy when you're an administrator of a Collaboration Manager setup.
+The CLI (Command Line Interface) tool allows you to backup and restore user's +workspaces.
+For the tools to work you'll need access to the Kubernetes cluster the +Collaboration manager is running on. In particular the namespace used to spawn +sessions.
+In order to use the CLI tooling, you'll need to have a local copy of the +collab-manager application and Python 3.11 installed.
+git clone https://github.com/DSD-DBS/capella-collab-manager.git
+cd capella-collab-manager/backend
+python -m venv .venv
+source .venv/bin/activate
+pip install .
+Once your environment is set up, you can use the CLI tooling. The tooling is +located in a module:
+python -m capellacollab.cli --help
+This gives you the help information. The CLI tool currently has one subcommand:
+ws, short for workspace.
Usage: python -m capellacollab.cli [OPTIONS] COMMAND [ARGS]...
+
+Options:
+ --install-completion [bash|zsh|fish|powershell|pwsh]
+ Install completion for the specified shell.
+ --show-completion [bash|zsh|fish|powershell|pwsh]
+ Show completion for the specified shell, to
+ copy it or customize the installation.
+ --help Show this message and exit.
+
+Commands:
+ ws
+You can discover the CLI on your own by printing the help messages of the +subcommands
+python -m capellacollab.cli ws --help
+python -m capellacollab.cli ws backup --help
+This guide describes the steps to get started with the Capella Collaboration +Manager.
+Before you start, make sure you have a running environment. For instructions on +how to set up such an environment, please refer to the +Development installation guide.
+First open a browser and go to http://localhost:8080.
+You will be welcomed by a friendly screen and you can log in. The default setup +is running an OAuth mock service for authentication.
+
As username, provide the admin for the admin user. If you have changed the
+username or want to test another user, enter your custom username.
You'll be returned to the Collaboration manager. Now you can start a session. +Select Persistent Workspace and hit Request Session.
+
The system will now schedule and start a fresh workspace. Wait a bit for the +workspace to be available
+
Once the session is ready, click Connect to Session and a new tab should +open. After a few seconds you should see the Capella splash screen and a +workspace will be shown in your browser.
+
This introduction only scratches the surface of what's possible with the +Collaboration Manager.
+More advanced features include:
+