Team for Capella - Advanced installation and configuration sample procedure

1. Summary

This procedure adapts the default Team for Capella installation procedure for an offline deployment with wss:// and https:// for all components.

Installation steps are listed, sorted, adapted or referenced from Team for Capella installation guide, Team for Capella documentation and Jenkins offline installation procedure for Team for Capella.

For context on the execution of this procedure, please refer to the following documents:

2. Prerequisites

Several items will need to be know at installation time:

  • IP address or DNS name of the Server VM needs to be transmitted to Obeo

    • required to generate the client connection key and the token pool for the license server

  • FQDN of the server

    • needed to generate the https certificates

    • needed on identity provider side to redirect url

  • Certificate(s) for the chosen FQDN

    • can be self-signed

    • needed for https configuration for the T4C Server, License server and Jenkins

To complete this procedure, you will need:

  • a computer with internet access to prepare the resources for the Jenkins offline installation

  • access to the Server VM with the possibility to upload the needed artifacts

  • access to the Client VM with the possibility to transfer the prepared client from the Server VM to the Client VM.

Before the installation, you will need to download/get:

The target host should have a tool to extract a zip archive such as 7-zip to avoid "long path issues" during extraction of Capella and its plugins.

The target host should have an advanced text editor such as Notepad++ (or an equivalent) to help editing of multi- ine configuration files.

Details and tips to generate keystores can be found at Jetty Operations Guide - Configuring SSL/TLS KeyStores

3. Procedure

TEAMFORCAPELLA_APP_HOME: This variable contains the absolute path of the T4C and Capella installation folder (which contains the folders capella, lic-server, samples, server, tools, updateSite, etc.). Example: C:\T4C\

3.1. Step 1: Team for Capella installation

  1. Follow section Installation of the Team for Capella installation guide but use the Capella bundle instead of the open-source bundle.

  2. Follow section Administration features installation of the Team for Capella installation guide.

3.2. Step 2: "Jenkins offline installation" preparation step

Follow Step 1: Check of prerequisites and Step 2: Download assets from "Jenkins offline installation and configuration procedure". Pay attention to the modified plugins list note for 7.0.

3.3. Step 3: Specific Team for Capella configuration

3.3.1. Server

Activation of the wss:// instead of plain text tcp communications requires to change several configuration files of the Team for Capella server to enable WS/WSS transport and deploy the Jetty server in https instead of https:

  1. TEAMFORCAPELLA_APP_HOME\server\configuration\fr.obeo.dsl.viewpoint.collab.server.admin\admin-server.properties

    • disable http

      • line 10: admin.server.jetty.http.enabled=false

    • enable https:

      • line 14: admin.server.jetty.https.enabled=true

      • uncomment line 16 to 19

        admin.server.jetty.ssl.host=0.0.0.0
admin.server.jetty.ssl.port=8443
#admin.server.jetty.ssl.keystore.path=${currentDir}/keystore (1)
admin.server.jetty.ssl.keystore.path=../certs/keystore (2)
admin.server.jetty.ssl.keystore.passphrase=secret
        1 keystore file, named keystore, located in the same folder than admin-server.properties
        2 keystore file, named keystore, located in TEAMFORCAPELLA_APP_HOME\certs

    • enable websocket transport:

      • line 52: admin.server.jetty.net4j.enabled=true

  2. TEAMFORCAPELLA_APP_HOME\server\configuration\cdo-server.xml

    • comment line 3

    • line 4, add: <acceptor type="ws"/>

Keystore management tips:

3.3.2. Tools adaptations

Admin server properties need to be replaced in tools properties:

  • From:

    -httpHost localhost ^
-httpPort 8080 ^
-httpsConnection false ^

  • To:

    -httpHost T4C_SERVER_FQDN ^ (1)
-httpPort 8443 ^
-httpsConnection false ^
    1 T4C_SERVER_FQDN must be replaced with the chosen FQDN

This needs to be done in:

  • TEAMFORCAPELLA_APP_HOME\tools\command.bat

  • TEAMFORCAPELLA_APP_HOME\tools\exporter.bat

  • TEAMFORCAPELLA_APP_HOME\tools\importer.bat

  • TEAMFORCAPELLA_APP_HOME\tools\maintenance.bat

Once jobs are deployed in Jenkins, Server - Start Repository will need to be updated: remove -httpPort, -httpsConnection - httpHost arguments from the executed command)

3.3.3. Client adaptations

Some configuration needs to be changed on the client properties:

  1. TEAMFORCAPELLA_APP_HOME\capella\pluginCustomization.ini

    #fr.obeo.dsl.viewpoint.collab/PREF_DEFAULT_REPOSITORY_LOCATION=localhost
fr.obeo.dsl.viewpoint.collab/PREF_DEFAULT_REPOSITORY_LOCATION=T4C_SERVER_FQDN (1)
fr.obeo.dsl.viewpoint.collab/PREF_DEFAULT_REPOSITORY_PORT=8443
fr.obeo.dsl.viewpoint.collab/PREF_DEFAULT_CONNECTION_TYPE=WSS
    1 T4C_SERVER_FQDN must be replaced with the chosen FQDN

  2. TEAMFORCAPELLA_APP_HOME\capella\capella.ini

    • if self-signed certificates are used

      • trust all certificate (self-signed), complete the -vmargs section with:

        -Dfr.obeo.dsl.viewpoint.collab.https.jetty.ssl.context.trustall=true

      • or install certificate in jre trustore:

        keytool -import -cacerts  -alias <aDifferentAliasForEachCertFile> -file <pathToTheCerFile> (1)
        1 Default password for cacerts is changeit or empty, -cacerts is equivalent to -keystore ../lib/security/cacerts, it is also possible to pass the store pass on the command line with -storepass.

3.4. Step 4: Jenkins installation

The section Jenkins scheduler installation redirects to System Administrator Guide > Jenkins Installation which requires internet access.

This section requires the result from Step 2: "Jenkins offline installation" preparation step

If Jenkins has already been installed, skip the first sub step of section Step 3: Deploy offline Jenkins.

  1. Run Step 3: Deploy offline Jenkins from the Jenkins offline installation and configuration procedure.

    • use port 443

  2. Run Step 4: Prepare plugins installation from the Jenkins offline installation and configuration procedure.

    • This step corresponds to the beginning of the Jenkins plugins and jobs required for Team for Capella - Automatic installation section

  3. Run the latest steps of the System Administrator Guide > Jenkins Installation > Install Jenkins plugins and jobs required for Team for Capella > Automatic installation section

    • Declare the TEAMFORCAPELLA_APP_HOME environment variable

    • Change the number of executors, the locale, the default view and the markup formatter

  4. Configure Jenkins with https:

    • Edit the jenkins.xml file (installed into %PROGRAMFILES{x86)%/Jenkins/jenkins.xml by default on Windows) and change the following arguments being passed to java when launching jenkins:

--httpPort=-1
--httpsPort=443
--httpsKeyStore=*TEAMFORCAPELLA_APP_HOME*\certs\keystore (1)
--httpsKeyStorePassword="<cleartext-password-to-keystore>"
1 Could also reference its own keystore with --httpsKeyStore="%JENKINS_HOME%\jenkins.example.com.jks"

Database - Backup needs a fix to create its workspace at the expected location, replace $WORKSPACE with %WORKSPACE% in its build step.

Jenkins configuration with OpenId Connect is not part of this procedure.

3.5. Step 5: Licenses installation

  1. Follow sections License server installation and Client configuration of the Team for Capella installation guide.

    • OLS.zip and connection-key.txt are required at this step.

  2. In the Scheduler (Jenkins), enable the License Server - Run job.

  3. Change its configuration to enable https on port 9443

    eclipsec.exe --launcher.ini lic-server.ini -verbose -consoleLog -keys ./OLS -httpPort 9443 -useHttps

  4. Complete License server -vmargs section to reference the keystore, in . TEAMFORCAPELLA_APP_HOME\lic-server\lic-server.ini

    eclipsec.exe --launcher.ini lic-server.ini -verbose -consoleLog -keys ./OLS -httpPort 9443 -useHttps
---
-vmargs
#Https_monitoring:
#-Dorg.eclipse.jetty.ssl.keystore.path=keystore
-Dorg.eclipse.jetty.ssl.keystore.path=../certs/keystore
#Https_monitoring_optional_parameters:
-Dorg.eclipse.jetty.ssl.password=secret
#-Dorg.eclipse.jetty.ssl.keypassword=KEY_MANAGER_PASSWORD
#-Dorg.eclipse.jetty.ssl.keystore.type=JKS
#-Dorg.eclipse.jetty.ssl.protocol=TLS

3.6. Step 6: Client installation

  1. Zip the capella and samples plugins from TeamForCapella_InstallationFolder

  2. Upload this bundle on the client VM

  3. Extract to the chosen TeamForCapella_ClientInstallationFolder

  4. Perform the multi-user configuration:

    • On a multi-user client installation, with workspace store in location not readable by other users, configuration and p2 folders must also be re-located.

    • See Strategy 2: Shared installation

    • Several possible options:

      • in case of a custom launch script: change workspace and configuration area

      • or in TeamForCapella_ClientInstallationFolder\capella\capella.ini: -Dosgi.configuration.area=@user.home/xxx/capella/configuration

      • or in TeamForCapella_ClientInstallationFolder\capella\configuration.ini\config.ini: osgi.configuration.area=@user.home/TeamForCapella_7.0.0/configuration

        • force the worskpace (equivalent to -data): osgi.instance.area=@user.home/TeamForCapella_7.0/workspace

        • also force the default workspace path: in osgi.instance.area.default=@user.home/TeamForCapella_7.0/workspace

3.7. Step 7: Installation verification

  1. Restart Jenkins service

  2. Check that the Server - Run and the License Server - Run jobs are running

  3. Launch two Capella clients from the client VM, from two different Citrix sessions

  4. User 1: export one project to Team for Capella repository, and connect to it

  5. User 2: connect to the share project.

  6. User 1 / USer 2: perform some modifications, save, take locks, …​

  7. Admin: check the license server monitoring

  8. Admin: check that the Backup - Database, Project - Import, Server - Start repository, Server - Stop repository, Server - Stop jobs are working fine

  9. Admin:

    • stop the server with Server - Stop

    • delete TEAMFORCAPELLA_APP_HOME\server\db-auditng

    • start the server with Server - Run

3.8. Step 8: OpenID Connect

The user registration is by default a user manager which stores the accepted users and their credentials in TEAMFORCAPELLA_APP_HOME\server\configuration\users.properties.
To enable the use of OpenID Connect, there are two options:

  • the authentication only can be delegated to the identity provider but the list of users is still managed per Team for Capella repositories

    • uncomment and configure the OpenID Connect properties in TEAMFORCAPELLA_APP_HOME\server\configuration\usermanager-config.properties

    • User registrations by editing the user.properties to add authorized logins or via the User Management view in Capella

  • or the authentication and registration are both delegated to the identity provider:

    • in TEAMFORCAPELLA_APP_HOME\server\configuration\cdo-server.xml

      • comment the userManager element

      • uncomment the <authenticator type="openidconnect" element

    • configure the OpenID Connect properties in TEAMFORCAPELLA_APP_HOME\server\configuration\openid-config.properties

The authentication servlet must also been enabled in TEAMFORCAPELLA_APP_HOME\server\configuration\fr.obeo.dsl.viewpoint.collab.server.admin\admin-server.properties:

  • line 45: admin.server.jetty.auth.openidconnect.enabled=true

Configuration details are described in System Administrator Guide > Server Configuration > Activate OpenID Connect authentication

3.9. Step 9: Installation verification

Rerun step 7. Some technical users might be required regarding the configuration of the tool. They will be defined in TeamForCapella_InstallationFolder\server\configuration\technicalUsers.properties.