Obeo Designer Team Administration Server: User Guide

This guide explains how to configure the administration server for Obeo Designer Team Server. In this guide, we consider you already configured your Obeo Designer Team Server.

1. Activate the administration server of Obeo Designer Team Server

This section explains how to activate the administration server.

In order, to activate the web services to manage the repositories of the Team Server, you will need to copy the folder ./server-configuration-examples/serverconfig-default-admin/fr.obeo.dsl.viewpoint.collab.server.admin and its content into the ./configuration folder or add the VM argument "-Dadmin.server.configuration.path=PATH/TO/DIRECTORY" in the ObeoDesignerTeamServer.ini. The path can be absolute or relative to the launcher.

The referenced directory must contain one files: admin-server.properties.
You can use this file to configure the administration server.

The first time the server is launched, a default "admin" user and its associated default token are created in the Eclipse secure-storage of the user that started the CDO server. The "admin" credentials are stored in a dedicated node used by the server. The token is hashed and encrypted.
A secret.txt file, containing the token, is created in the same folder as admin-server.properties file. It can be used in third party application to be authenticated with the admin server. Remember to remove this file as soon as you can.

1.1. Administration server configuration

The administration server for Obeo Designer Team Server is a simple jetty server started and stopped when the Team Server is started and stopped. You can configure the administration server by editing the admin-server.properties file located in the ./configuration/fr.obeo.dsl.viewpoint.collab.server.admin/, or in the folder specified by the VM argument -Dadmin.server.configuration.path. To access to the web service, you will also need to define users see Credentials management section.

1.1.1. admin-server.properties configuration file

The admin-server.properties file handles the configuration of the jetty server and other options to customize the administration server:

# Note: The path '.' is the directory containing the executable.
# Note: If user wants to reference the directory of this file he can use ${currentDir}.

#
# Jetty configuration
#

admin.server.jetty.http.enabled=true
admin.server.jetty.http.host=0.0.0.0
admin.server.jetty.port=8080

admin.server.jetty.https.enabled=false
# The next four properties will be needed if the 'admin.server.jetty.https.enabled' option is set to true.
#admin.server.jetty.ssl.host=0.0.0.0
#admin.server.jetty.ssl.port=8443
#admin.server.jetty.ssl.keystore.path=${currentDir}/keystore
#admin.server.jetty.ssl.keystore.passphrase=password
# Client side configuration for https:// and wss:// access might need adjustments to be able to contact your server deployed in https if your certificate is not trusted
# or if you need to configure the security checks:
#      - SSL Context properties (see Jetty documentation and org.eclipse.jetty.util.ssl.SslContextFactory for expected values):
#         - trust any certificate (self-signed for example): -Dfr.obeo.dsl.viewpoint.collab.https.jetty.ssl.context.trustall=true
#         - endpointIdentificationAlgorithm: -Dfr.obeo.dsl.viewpoint.collab.https.jetty.ssl.context.endpointIdentificationAlgorithm
#         - trustStore passphrase: -Dfr.obeo.dsl.viewpoint.collab.https.jetty.ssl.context.passphrase
#         - trustStore uri: -Dfr.obeo.dsl.viewpoint.collab.https.jetty.ssl.context.trust
#         - trustStore type: -Dfr.obeo.dsl.viewpoint.collab.https.jetty.ssl.context.trust.type
#         - trust manager factory algorithm: -Dfr.obeo.dsl.viewpoint.collab.https.jetty.ssl.context.trust.manager.factory.algorithm

#
# Admin Servlets
#

# The property 'admin.server.jetty.admin.servlets.enabled' allows to enable or disable the CDO Server admin servlets (see available services in openapi).
admin.server.jetty.admin.servlets.enabled=true
# The property 'admin.server.jetty.servlets.admin.docandopenapi.enabled' allows to enable or disable the documentation (/doc and openapi servlets).
admin.server.jetty.servlets.admin.docandopenapi.enabled=true
# See ODTS Admin Configuration section at the end of this file for additional properties

#
# OpenID Connect
#

# The property 'admin.server.jetty.auth.openidconnect.enabled' allows to enable the servlets related to openid connect.
admin.server.jetty.auth.openidconnect.enabled=false

#
# Net4J WebSocket Transport
#

# The property 'admin.server.jetty.net4j.enabled' allows to enable the Net4J Websocket-based transport by deploying the corresponding servlet.
admin.server.jetty.net4j.enabled=false
# An additional step is needed in the cdo-server.xml:
#   - a specific acceptor must be added in the cdo-server.xml with type 'ws' or 'wss'.
#   - <acceptor type="ws"/> is the simplest and default WebSocket-based acceptor. Additional configurations are explained below.
#   - It can be used to replace the default acceptor (<acceptor type="tcp" listenAddr="0.0.0.0" port="2036"></acceptor>) or as an additional one.
# The move from a Websocket-based transport to a 'SecuredWebsocket-based' transport can be done through Jetty configuration by enabling https,
# or with the use of an HTTPS reverse proxy server (Nginx or Apache for example).

# The next two properties allow to customize the path of the websocket and the need of authentication.
#admin.server.jetty.net4j.path=net4j
#admin.server.jetty.net4j.remove.public.constraint=false

# The client side configuration will depend on the global deployment of the current server and the use of the WS and WSS connection types.
# Then a user will have to use the following  parameters to connect to the repository:
#   - Repository Host: localhost or ip/url of the server,
#   - Port Number: 8080 (value of admin.server.jetty.port or admin.server.jetty.ssl.port if https is enabled, or specific proxy port if T4C is deployed behind a proxy)
#   - Repository Name: designer-server
#   - Connection type: WS (WSS if Jetty has been deployed in https or is behind an https proxy)
#
# Here is a list of optional settings which will impact both server and clients configurations:
#      - change the acceptor name to be specific to your product: from ws://1.2.3.4:8080/net4j/@default to ws://1.2.3.4:8080/net4j/@YourAcceptorName
#         - server: change the acceptor tag in the cdo-server.xml to be  <acceptor type="ws" name="YourAcceptorName" />
#         - client: -Dfr.obeo.dsl.viewpoint.collab.net4j.ws.acceptor=YourAcceptorName  (same value than name attribute of the acceptor tag used on the server side).
#      - change the HTTP REST endpoint from the default value (/net4j) to the path of your choice: from ws://1.2.3.4:8080/net4j/ to ws://1.2.3.4:8080/your/path/
#         - server: set admin.server.jetty.net4j.path=your/path
#         - client: -Dfr.obeo.dsl.viewpoint.collab.net4j.ws.path=your/path
#      - have basic authentication on the Net4J servlet (same credentials than the one used for the other servlets, see openapi/):
#         - for tests purpose only: login passwords might be available from the installation details of the eclipse platform and in the executable companion .ini file.
#         - server: admin.server.jetty.net4j.remove.public.constraint=true
#         - client:
#            - declare the login:  -Dorg.eclipse.net4j.internal.ws.WSClientConnector.clientBasicAuth.login=sampleuser
#            - declare the password: -Dorg.eclipse.net4j.internal.ws.WSClientConnector.clientBasicAuth.password=samplepassword

# See also SSL Context properties at the beginning of this file for additional properties to configure SSL context required for wss:// on client side.

#
# ODTS Admin Configuration
#

## The path to a ldap trust store.
## This property will be used as default value if no 'trustStorePath' is given to the repository creation API.
admin.server.ldap.truststore.path=.

## The path to the folder 'repositories' in which repositories created from the admin-server will be stored.
admin.server.repositories.directory.path=.

## The path to the folder 'exports' in which the xml exports of repositories will be stored.
admin.server.repositories.export.directory.path=.

## This property will be used to configure the db adapter used by repositories created from the admin-server (default value: h2).
admin.server.h2.db.adapter.name=h2

## This property will be used to configure the java process Xmx launched by the H2 Server extension when an H2 server is needed.
admin.server.h2.server.xmx=2G

## The path to the folder 'openapi' in which the Swagger UI doc page hosted by the server will look for odts-admin-ws.yaml.
## If the property is commented it will serve the file packaged in the plugins.
#admin.server.openapi.directory.path=.

## The path to the folder 'doc' in which the server will look for index.html and all files served on /doc.
## If the property is commented it will serve the files packaged in the plugins.
#admin.server.doc.directory.path=.

## Project Import/Export/Delete enablement:
admin.server.api.project.get.enabled=false
admin.server.api.project.post.enabled=false
admin.server.api.project.delete.enabled=false

## Importer application parameters (GET Projects):
admin.server.api.project.get.impl.config.exe = ../ObeoDesigner-Team/obeodesigner
admin.server.api.project.get.impl.config.application = fr.obeo.dsl.viewpoint.collab.importer
admin.server.api.project.get.impl.config.data=tools/Importer/workspace
admin.server.api.project.get.impl.config.logFolder=tools/Importer/logs
admin.server.api.project.get.impl.config.outputFolder=tools/Importer/output
admin.server.api.project.get.impl.config.archiveProject=true
admin.server.api.project.get.impl.config.httpHost=localhost
admin.server.api.project.get.impl.config.httpPort=8080
admin.server.api.project.get.impl.config.httpsConnection=false
#admin.server.api.project.get.impl.config.httpCredentials=tools/httpCredentials.properties
admin.server.api.project.get.impl.config.repositoryCredentials=tools/repositoryCredentials.properties
admin.server.api.project.get.impl.config.checksize=-1
admin.server.api.project.get.impl.config.checkSession=true
admin.server.api.project.get.impl.config.overrideExistingProject=false
admin.server.api.project.get.impl.config.importCommitHistoryAsText=false
admin.server.api.project.get.impl.config.vm.args.0=-Xms1000m
admin.server.api.project.get.impl.config.vm.args.1=-Xmx3000m
admin.server.api.project.get.impl.config.vm.args.2=-Dorg.eclipse.net4j.util.om.trace.disable=true
admin.server.api.project.get.impl.config.vm.args.3=-Dosgi.requiredJavaVersion=11

## Exporter application parameters: (POST and DELETE projects)
admin.server.api.project.post.impl.config.exe = ../ObeoDesigner-Team/obeodesigner
admin.server.api.project.post.impl.config.application = fr.obeo.dsl.viewpoint.collab.exporter
admin.server.api.project.post.impl.config.data=tools/Exporter/workspace
admin.server.api.project.post.impl.config.logFolder=tools/Exporter/logs
admin.server.api.project.post.impl.config.httpHost=localhost
admin.server.api.project.post.impl.config.httpPort=8080
admin.server.api.project.post.impl.config.httpsConnection=false
#admin.server.api.project.post.impl.config.httpCredentials=tools/httpCredentials.properties
admin.server.api.project.post.impl.config.repositoryCredentials=tools/repositoryCredentials.properties
admin.server.api.project.post.impl.config.overrideExistingImage=false
admin.server.api.project.post.impl.config.overrideExistingProject=false
admin.server.api.project.post.impl.config.vm.args.0=-Xms1000m
admin.server.api.project.post.impl.config.vm.args.1=-Xmx3000m
admin.server.api.project.post.impl.config.vm.args.2=-Dorg.eclipse.net4j.util.om.trace.disable=true
admin.server.api.project.post.impl.config.vm.args.3=-Dosgi.requiredJavaVersion=11

This example of configuration will allow you to access our web services using HTTP, which means the communication is not encrypted. This configuration can be used if you already have a security system that encrypts communications. If you don’t have such a security system and want to encrypt the communication between you and the jetty server, you will have to set the admin.server.jetty.https.enable to true and uncomment the four properties admin.server.jetty.ssl.host, admin.server.jetty.ssl.port, admin.server.jetty.ssl.keystore.path and admin.server.jetty.ssl.keystore.passphrase.

The admin.server.jetty.ssl.keystore.path properties must refer to a keystore path which can be generated by following those instructions.

In some cases, your network is protected by a proxy server. If you are in this configuration, all you need is to activate http and set admin.server.jetty.http.host and admin.server.jetty.port to the host and port of your proxy server.

The admin.server.h2.db.adapter.name property is used to define the db adapter name that will be used to initialize repositories during their creation by the corresponding service.

The admin.server.h2.server.xmx property is used to define the Xmx default value that will be used to initialize the h2 server java process created when a repository which uses an h2 server does not exist.

The admin.server.openapi.directory.path property is used to define the path to find an alternate openapi folder. This allows you to complete the default OpenAPI definition with the description of your extensions. You can download the default odts-admin-ws.yaml on /doc when the administration server is deployed.

The admin.server.doc.directory.path property is used to define the path to find an alternate doc folder. This allows you to replace the default documentation provided by ODTS available on /doc.

As you noticed, it is possible to use a relative path using '.' and ${currentDir}. The '.' path is the directory that contains the Obeo Designer Team Server launcher, and the ${currentDir} is the directory that contains the admin-server.properties file.

1.1.2. Credentials Management

The first time the server is launched, a default "admin" user and its associated default token are created in the Eclipse secure-storage of the user that started the CDO server. The "admin" credentials are stored in a dedicated node used by the server. The token is hashed and encrypted.
A secret.txt file, containing the token, is created in the same folder than admin-server.properties file. It can be used in third party application to be authenticated with the admin server. Remember to remove this file as soon as you can.

Moreover, the admin credentials are also added in the secure storage for the application needs (importer, exporter, etc.) in a dedicated node. The credentials are encrypted.

This way once the server has been started the first time, there is no additional step. The applications can automatically be used, being authenticated with the admin server with the "admin" user.

Nevertheless, it is possible to manage the user and the user token with the Credentials application.

By default, the secure storage is created or retrieved from the home of the system user currently executing the application:

Windows:
- %USERPROFILE%\.eclipse\org.eclipse.equinox.security\secure_storage
- C:\Users\USERNAME\.eclipse\org.eclipse.equinox.security\secure_storage
Linux:
- ~/.eclipse/org.eclipse.equinox.security/secure_storage
- /home/USERNAME/.eclipse/org.eclipse.equinox.security/secure_storage
macOS:
- ~/.eclipse/org.eclipse.equinox.security/secure_storage
- /Users/USERNAME/.eclipse/org.eclipse.equinox.security/secure_storage
Location can depend on the configuration of your operating system.

It is also possible to change the location of the secure storage with the use of the -eclipse.keyring program argument in the .ini file. For example, to use a fixed secure storage located next to your executable:

-eclipse.keyring
./secure_storage

1.2. REST Admin API

The admin web server provides a whole set of services to manage the projects, the models and the users. The documentation is available at the URL http(s)://<admin server IP>:<admin server port>/doc

Swagger documentation is available at the URL http(s)://<admin server IP>:<admin server port>/openapi. It can be enabled or disabled with the admin.server.jetty.servlets.admin.docandopenapi.enabled property

2. Contribute to the administration server

This section describes how to contribute to the administration server of Obeo Designer Team Server. You are able to contribute new web services and new customization for repository management.

2.1. Contribute new web services

It is possible to contribute new web services to the administration server of Obeo Designer Team Server by using the extension point fr.obeo.dsl.viewpoint.collab.server.admin.servletExtension with an implementation of fr.obeo.dsl.viewpoint.collab.server.admin.api.IAdminServlet. Your service must also extend javax.servlet.http.HttpServlet at least. It will allow you to benefit from the default behavior of HttpServlet. In some cases, you may want to use a CDOTransaction in your web service. You can extend fr.obeo.dsl.viewpoint.collab.server.admin.api.AbstractServletWithCDOTransaction which sub-class javax.servlet.http.HttpServlet and provides you a CDOTransaction. The CDOTransaction provided to your servlet will be opened, and it will be closed when your service ends. You will still need to commit your modification as well as you will have to handle errors.

Remark: As we did not configure specific lock management/strategy, you must handle locks by yourself. We encourage you to only use the CDOTransaction in order to initialize new projects or resources and do not use it to modify models or resources which might be already shared among other users.

2.2. Customize repository management

It is possible to customize the configuration of repositories by using the extension point fr.obeo.dsl.viewpoint.collab.server.admin.repositoryManagerExtension with an implementation of fr.obeo.dsl.viewpoint.collab.server.admin.api.IRepositoryManager and by defining a key that will identify your implementation. Your implementation can extend fr.obeo.dsl.viewpoint.collab.server.admin.api.AbstractRepositoryManager in order to let you implement only what you want to customize. We use the value of the authenticationType and datasourceType parameters given at the repository creation to call the registered extensions.

By contributing to the repository management extension, you will be able to customize the configuration of the authentication as well as the configuration of your database. In both cases, you will be able to use the repository manager life cycle hooks that provide visibility into different key life moments and the ability to act when they occur. Those life cycle hooks are called before and after a repository has started and stopped, after a remote project has created and also before a cdo export of a repository.

You will also be able to customize how to retrieve the list of users of a repository as well as to create or delete users.

3. Miscellaneous server customizations

3.1. Customize commit description length

The system property fr.obeo.dsl.viewpoint.collab.common.commit.description.max.length can modify the length of the commit message. By default the value is 255. Default value can be modified by products even if the system property is not set in the product .ini file. This property needs to be set to the same value on the client and the server.

This default 255 limit is due to the default org.eclipse.net4j.db.h2.H2Adapter that consider the commit comment as a VARCHAR. Increasing the value of this property requires a db adapter that handles that DBField with a type for longer text (like CLOB). If the commit description is longer than the accepted max length, it will be truncated before commit to match the max length in core wizards, actions and session save operations. For components extending the collaborative layer, if they directly call setCommitComment() and commit() methods on the CDO transaction, they can use fr.obeo.dsl.viewpoint.collab.common.internal.commit.CommitCommentUtil.fitCommitDescriptionLength(String) to fit their commit comment. -1 can be used to remove the limitation. Otherwise only values greater than or equals to 10 are accepted. "Xxxxxxxxxx" will become "Xxxx […]". If the property value if -1, it will take the system dependent SWT widget Text.LIMIT length.

4. Disclaimer

Only repositories created with our web services can be handled by our web services. The old repositories cannot be handled.