Skip to content

Capella base

Info

The Docker image name for this image is capella/base

The Capella base image installs a selected Capella client version. The Capella client can be downloaded and can optionally be customised prior to building the Docker image or can be downloaded automatically in the Docker image.

The images are meant to have a containerised Capella (with or without a Team for Capella client) that can be run headless (as command line interface).

Info

The functionality for running capella as a command-line app used to be part of the capella/cli image. An image with this name is no longer built. Use capella/base instead.

Use the prebuilt image

docker run ghcr.io/dsd-dbs/capella-dockerimages/capella/base:$TAG

where $TAG is the Docker tag. For more information, have a look at our tagging schema.

Please check the Run the container section for more information about the usage.

Build it yourself

Preparation

Optional: Download Capella manually

Download a Capella Linux binary zip or tar.gz archive. You can get a release directly from Eclipse. Visit https://github.com/eclipse/capella/releases, select a version and follow the hyperlink labelled Product to find a binary release for Linux.

Place the downloaded archive in the subdirectory capella/versions/$CAPELLA_VERSION/$ARCHITECTURE of the present repository and ensure that the end result is either

  • capella/versions/$CAPELLA_VERSION/$ARCHITECTURE/capella.tar.gz or
  • capella/versions/$CAPELLA_VERSION/$ARCHITECTURE/capella.zip.

Check that the archive has a structure similar to the following coming with a top level directory named capella and several sub directories and files in it.

For Capella 5.0.0 the structure is illustrated below:

$ tree -L 1 capella
capella
├── artifacts.xml
├── capella
├── capella.ini
├── configuration
├── dropins
├── epl-v10.html
├── features
├── jre
├── notice.html
├── p2
├── plugins
└── readme

Install dropins

Automatic installation

The image builder can automatically download dropins for Capella and inject them into the Capella client.

You have to pass a comma-separated list of dropin names as CAPELLA_DROPINS build argument to the docker build command:

--build-arg CAPELLA_DROPINS="ModelsImporter,CapellaXHTMLDocGen,DiagramStyler,PVMT,Filtering,Requirements,SubsystemTransition"

Supported dropins are:

The dropins are registered in the capella/versions/$CAPELLA_VERSION/dropins.yml file. If you're missing a dropin in the list, feel free to open a PR.

Manual installation

If you want to install dropins manually, you can place the dropins in the capella/versions/$CAPELLA_VERSION/dropins directory. The dropins will be copied into the dropins directory of the Capella client without any further processing.

Optional: Workaround of pinned library versions to remove incompatibilities

Note: This workaround is normally handled in the Dockerfile and it is only necessary to download below libraries if there are restrictions on your network that block an access to these libraries when the Docker image is being built.

In some Capella versions, there are incompatiblities with certain versions of the following libraries:

  • libjavascriptcoregtk-4.0-18 (version 2.32.4)
  • libwebkit2gtk-4.0-37 (version 2.32.4)

The workaround is to use version 2.28.1 for both libraries in the container.

So if your build environment restricts access to the latest versions you need to manually download the packages with the command apt download and inject them into the container.

For more information refer to Download older packages manually.

Info

You have to add --build-arg INJECT_PACKAGES=true to the docker build command if you want to use the previously downloaded packages.

Build it manually with Docker

Automatic download of Capella

If you want to download the Capella archive automatically, use the following command. It does only work for supported Capella versions.

docker build -t capella/base capella --build-arg BUILD_TYPE=online --build-arg CAPELLA_VERSION=$CAPELLA_VERSION

You can further customize the mirror to download the Capella archive from. If you don't want to use the default mirror, choose another mirror from this list.

Then, append /{} to the mirror URL and pass it as a build argument to the above command, e.g.:

--build-arg CAPELLA_DOWNLOAD_URL="https://mirror.umd.edu/eclipse/capella/core/products/releases/{}"`

Build with pre-downloaded version of Capella

If you've downloaded the Capella archive manually before, use this command:

docker build -t capella/base capella --build-arg CAPELLA_VERSION=$CAPELLA_VERSION

With this method, you can customize the Capella client before running the above command:

  1. Extract the downloaded archive,
  2. Apply any modifications (e.g., installation of plugins and/ or dropins) to it, and
  3. Compress the modified folder capella to get a capella.zip or capella.tar.gz again.

Miscellaneous

Download older debian packages manually

Unfortunately the version 2.28.1 of libwebkit2gtk-4.0-37 is no longer available in the stable Debian registry, but it is still available in the Ubuntu focal repository (https://packages.ubuntu.com/focal/libwebkit2gtk-4.0-37).

First of all, you have to add the source to your apt-sources and add the apt keys.

Recommendation: Spawn a debian:bookworm Docker container and execute the steps inside the container.

apt update && apt install -y gnupg
echo "deb http://security.ubuntu.com/ubuntu focal-security main" >> /etc/apt/sources.list.d/focal.list
apt-key adv --keyserver keyserver.ubuntu.com --recv-keys "3B4FE6ACC0B21F32"
apt-key adv --keyserver keyserver.ubuntu.com --recv-keys "871920D1991BC93C"
apt update

Please download all packages and place the files in the folder capella/libs:

  • libicu66_66.1-2ubuntu2_amd64.deb
    (Run apt download libicu66=66.1-2ubuntu2)

  • libjavascriptcoregtk-4.0-18_2.28.1-1_amd64.deb
    (Run apt download libjavascriptcoregtk-4.0-18=2.28.1-1)

  • libjpeg-turbo8_2.0.3-0ubuntu1_amd64.deb
    (Run apt download libjpeg-turbo8=2.0.3-0ubuntu1)

  • libjpeg8_8c-2ubuntu8_amd64.deb
    (Run apt download libjpeg8=8c-2ubuntu8)

  • libwebkit2gtk-4.0-37_2.28.1-1_amd64.deb
    (Run apt download libwebkit2gtk-4.0-37=2.28.1-1)

  • libwebp6_0.6.1-2ubuntu0.20.04.2_amd64.deb
    (Run apt download libwebp6=0.6.1-2ubuntu0.20.04.2)

Run the container

Configuration Options

There are a few configuration options that can be passed to the container.

Semantic Browser Auto-refresh

One performance recommendation of the Capella team is to disable the semantic browser auto-refresh.

The semantic browser synchronization is disabled by default in our containers. To follow a more streamlined approach, it will also be disabled if actively changed in the UI / workspace.

To disable this behaviour and just keep the option as it is, pass the following flag to the docker run command:

--env CAPELLA_DISABLE_SEMANTIC_BROWSER_AUTO_REFRESH=0

Locally on X11 systems

If you don't need remote access, have a local X11 server running and just want to run Capella locally, this may be the best option for you.

On some systems, you have to whitelist connections to the X-Server with:

xhost +local

It allows all local programs to connect to your X server. You can further restrict the access to the X server. Please read the documentation of xhost for more details.

The container can be started with the following command. The DISPLAY environment has to be passed to the container.

docker run -d \
    -v /tmp/.X11-unix:/tmp/.X11-unix \
    -e DISPLAY=$(DISPLAY) \
    capella/base

Capella should start after a few seconds.

In a remote container

Please follow the instructions on the remote page. When running the image, add the following variables to the docker run command:

    -e AUTOSTART_CAPELLA=$AUTOSTART_CAPELLA \
    -e RESTART_CAPELLA=$RESTART_CAPELLA \

Please replace the followings variables:

  • AUTOSTART_CAPELLA defines the autostart behaviour of Capella. When set to 1 (default), Capella will be started as soon as an RDP connection has been established to the running container.
  • RESTART_CAPELLA defines the restart behaviour of Capella. When set to 1 (default) and when AUTOSTART_CAPELLA=1, Capella will be re-started as soon as it has been exited (after clean quits as well as crashs).

If you want to configure the JVM memory options, have a look at Eclipse memory options.

Example to export representations (diagrams) as SVG images

Replace /path/to/model and <PROJECT_NAME> to pass any local Capella model. Set the project name so that it fits your Capella project name for the model as it is given in the file /path/to/model/.project.

Exported diagrams will appear on the host machine at /path/to/model/diagrams.

docker run --rm -it \
  -v /path/to/model:/model \
  capella/base \
  -nosplash \
  -consolelog \
  -application org.polarsys.capella.core.commandline.core \
  -appid org.polarsys.capella.exportRepresentations \
  -data /workspace \
  -import /model \
  -input "/all" \
  -imageFormat SVG \
  -exportDecorations \
  -outputfolder /<PROJECT_NAME>/diagrams \
  -forceoutputfoldercreation