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 considers you already configured your Obeo Designer Team Server.

  1. Activate the administration server of Obeo Designer Team Server
    1. Administration server configuration
      1. admin-server.properties configuration file
      2. realm.properties file
  2. Contribute to the administration server
    1. Contribute new web services
    2. Customize repository management
  3. Disclaimer

Activate the administration server of Obeo Designer Team Server

This section explains how to activate the adminstration 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 two files: admin-server.properties and realm.properties.
You can use those files to configure the administration server.

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 and roles in the realm.properties file located in the same folder.

admin-server.properties configuration file

The admin-server.properties file handles the configuration of the jetty server and others 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.https.enabled=false

# The next three line 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

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

# 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=.

This example of configuration will allow 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 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 the instructions from the Keystore Generation section of the Collaborative Modeling Administrator guide available in the integrated help of Obeo Designer Team Edition.


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 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 to replace the default documentation provided by ODTS available on /doc.


As you noticed, it is possible to use 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.

realm.properties file

The realm.properties file is used to defined users who will be allowed to access to web services and theirs roles:

#login=password,role
# admin is the only supported role
#user1=user1password,admin
#user2=MD5:202cb962ac59075b964b07152d234b70,admin
sampleuser=samplepassword,admin


A MD5 value can be generated with echo -n password | md5sum.


For now, only the admin role can be used to allow a user to access to our web services.
Users who will use our web services will need to set the Authorization header with basic authentication in theirs requests headers.

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.

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 extends 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 will end. You will still need to commit your modification as well as you will have to handle errors.

Remark: As we did not configured 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 others users.

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 case 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.

Disclaimer

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