operations guide - version 8.1.2-r054 · 2019. 12. 4. · operations guide version 8.1.2-r054...

ACTICO Platform - Model Hub

Operations Guide

Version 8.1.2-R054

ACTICO GmbH

www.actico.com

Operations Guide: Version 8.1.2-R054

Operations Guide

Copyright © ACTICO GmbH iii

Table of Contents

1. About this document ........................................................................................................ 1

1.1. Audience ........................................................................................................................... 1

1.2. Content ............................................................................................................................. 1

1.3. Conventions ...................................................................................................................... 1

2. Introduction ........................................................................................................................ 2

3. System Overview, Links and Authentication ............................................................... 3

3.1. System Overview Diagram ................................................................................................. 3

3.2. Web User Interface ........................................................................................................... 33.2.1. Demo Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

3.3. Modeler Endpoint ............................................................................................................. 3

3.4. Git Endpoint ..................................................................................................................... 4

3.5. REST Endpoint .................................................................................................................. 4

4. Installation and Configuration ....................................................................................... 5

4.1. Unpack ............................................................................................................................. 5

4.2. Java Runtime .................................................................................................................... 5

4.3. License File ...................................................................................................................... 5

4.4. Configuration ................................................................................................................... 5

4.5. Users ............................................................................................................................... 64.5.1. Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64.5.2. Default Administrators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64.5.3. Super Administrators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64.5.4. Internal Technical User . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

4.6. Authentication ................................................................................................................. 64.6.1. Active Directory / LDAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

4.6.1.1. External Active Directory / LDAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74.6.1.2. Embedded LDAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

4.6.2. Open ID Connect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

4.7. Database .......................................................................................................................... 84.7.1. Roles and Permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84.7.2. Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84.7.3. Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84.7.4. Schema Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

4.7.4.1. Automatic Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94.7.4.2. Manual Deployment with sqldump . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

4.8. Server .............................................................................................................................. 94.8.1. Common Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Operations Guide

Copyright © ACTICO GmbH iv

4.8.2. SSL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104.8.3. Connection Pool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

4.9. Running behind Reverse Proxy ........................................................................................ 11

4.10. Script Environment ........................................................................................................ 114.10.1. Startup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114.10.2. Shutdown . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124.10.3. Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124.10.4. Install as Windows Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

4.11. Clustering ...................................................................................................................... 13

5. Operations and Maintenance ....................................................................................... 14

5.1. Temporary directories ..................................................................................................... 14

5.2. Backup and Restore ........................................................................................................ 145.2.1. Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145.2.2. File system folders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

5.3. Logging ........................................................................................................................... 145.3.1. Log Levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

5.3.1.1. Custom log4j2 configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

5.4. Monitoring ...................................................................................................................... 155.4.1. Endpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

A. Migrations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17A.1. Migration from Team Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

A.1.1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17A.1.2. Migration Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

B. Example Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19B.1. Using Keycloak as external OpenID Connect authentication provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

B.1.1. Setup Keycloak . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19B.2. Using LDAP as Authentication Provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

B.2.1. Prepare Password Policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19B.2.2. Prepare User Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20B.2.3. Start LDAP Demo Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

B.3. Using MySQL as external database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21C. Example Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

C.1. Listing of Example Datasource Configuration Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23C.1.1. Oracle Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23C.1.2. Microsoft SQL Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23C.1.3. MySql . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Chapter 1. About this document

Copyright © ACTICO GmbH 1

Chapter 1. About this documentThis document describes the installation and operation of ACTICO Model Hub.

1.1. Audience

This document is intended for

• System Administrators

• Database Administrators

1.2. Content

This document considers the following topics

• Installation

• Configuration

• Operation

• Maintenance

• Migration from Team Server

1.3. Conventions

The following text conventions are used in this document:

Table 1.1. Conventions

Convention Meaning

boldface Used for elements, labels and terms from the userinterface.

monospace Used for filenames or URLs.

Chapter 2. Introduction


Chapter 2. IntroductionACTICO Model Hub provides versioning capability for model projects created with ACTICO Modeler.

Main features are:

• Versioning of model projects

• Export and import functionality

• Security and access control

• Auditing of all events within the system

Note for users familiar with Team Server:

• Model Hub is the fully modernized successor of Team Server.

• Modeler connects to the Model Hub just like to a Team Server before.

• Users of Modeler use the known 'Team Server Explorer' and 'Team Server Activities' views to retrieve andpublish their model changes.

• Repositories in Model Hub are now Git repositories and it provides the APIs to allow standard Git tooling toclone, checkout, commit and push changes. This facilitates integration into IT processes and tools.

• Locking of resources to prevent conflicting changes in Modeler is still available.

Chapter 3. System Overview, Links and Authentication



3.1. System Overview Diagram

The following diagram shows Model Hub and the involved systems:

3.2. Web User Interface

The Model Hub Web User Interface is available at: http://localhost:8080.

If SSL is configured the link is: https://localhost:8443.

The server port may be configured to another value. Use the corresponding valid server name.

3.2.1. Demo Users

If Model Hub is installed with demo data, the following users are available:

User Name User Id Password Assigned User Groups

Administrator Admin Admin Administrators &Standard Users

John John John Standard Users

Mary Mary Mary Standard Users

3.3. Modeler Endpoint

The URL to use Model Hub for model versioning is: http://localhost:8080/teamserver.

http://localhost:8080https://localhost:8443http://localhost:8080/teamserver



Use this URL in ACTICO Modeler to specify a connection to Model Hub. For authentication choose Model Huband enter data for a valid user account with appropriate permissions.

3.4. Git Endpoint

Model versioning repositories in Model Hub are Git repositories and they provide the APIs to allow standard Gittooling to clone, checkout, commit and push changes. This facilitates integration into IT processes and tools.

In order to access a repository via Git use this URL: http://localhost:8080/git/teamserver/.git

Basic Authentication is used and the user needs to have the permission 'Access Git repository'.

Hints and warnings:

• It is recommended to prefer the Model Hub provided interfaces before using the Git endpoint. Use the GitEndpoint for push (write) operations at own risk, as Model Hub relies on some conventions.

• Modeler does show revision information for folders. When creating a new folder using this endpoint, a file.tsfoldermeta is required next to the folder. Best is to use the Modeler for this.

• Modeler accesses tags by a timestamp and branch information. When creating a new tag using thisendpoint, you must add a Git note with necessary information to the tag. Best is to use the Modeler for this.

• Modeler can only handle certain entries in its own order for .gitignore files. Do not edit this file yourself.

• Some files can not be merged using a textual merge, as those might get invalid. Those can only be mergedusing the Modeler. In order to prevent a textual merge, those files are marked as binary.

• Adapt the git config settings "user.name" and "user.email" to Model Hub conventions

3.5. REST Endpoint

REST calls require authentication using OAuth 2.0 with Access Token. The token can be generated e.g. with thePostman Application.

Table 3.1. Required values for the Postman Dialog "Get new access token"

Property Value

Token Name

Grant Type Password Credentials

Access Token URL https://localhost:8080/security/oauth/token

Username

Password

Client ID actico-model-hub

Client Secret (empty)

Scope openid profile email

Client Authentication Send Basic Auth header

http://localhost:8080/git/teamserver/.githttp://localhost:8080/git/teamserver/.githttps://www.getpostman.com/https://localhost:8080/security/oauth/token

Chapter 4. Installation and Configuration



4.1. Unpack

Unzip the file model-hub-application.zip.

The app folder contains:

• the binary file of the application

The config folder contains:

• the application-model-hub.properties file that is used to store configuration settings

• the log4j2.xml file that is used to configure the logging

• the actico.keys properties file containing private keys (must be kept confidential!). It is created when theapplication starts the first time.

The bin folder contains preconfigured start and stop scripts.

The data, logs and work folders are created when the application starts. They contain dynamic content.

All resources in the config folder are automatically on the classpath of the application. Placeadditional files, like JDBC driver JAR files, in the config/lib directory.

4.2. Java Runtime

Model Hub requires a Java runtime to be available in the java folder of the installation. If this folder is emptyand the Model Hub installation is part of an ACTICO Platform installation, the Java runtime defined for theACTICO Platform is used. If the java folder of the installation is empty and no ACTICO Platform Java installationwas found the environment variable JAVA_HOME is used.

Make sure the Java version matches with the System Requirements

4.3. License File

Copy your obtained license file to one of the following folders:

• /.actico/license

• config/license

In case you like to rename the license file, make sure the filename starts with license.

4.4. Configuration

The file config/application-model-hub.properties is used to configure the Model Hub. The specificconfiguration settings are described in the next chapters. If changes to the files are done a restart of ModelHub is necessary in order to become effective.



4.5. Users

4.5.1. Users

Each user is assigned by default to a user group. This user group can be configured using the following setting:

# Default user group name assigned to users that login the first timeactico.permission-management.default-user-group=Standard Users

4.5.2. Default Administrators

In order to initially setup the Model Hub installation, at least one User with administrative privileges isnecessary. At startup Model Hub creates a default admin user group which will include all permissions.Additionally, all default admin users are assigned to this user group.

# Default administrator user group containing all permissions

actico.permission-management.default-admin-user-group=Administrators 1

# Subjects of default admin users (comma separated). Use id of created keycloak users if Open ID Connect is used.# These users are automatically assigned to the user group 'default-admin-user-group'.

actico.permission-management.default-admin-users=Admin 2

1

defines the default admin user groups name2

defines the users which are created and assigned to this group

These users and user groups will be created at each startup, if they do not yet exist! This meansif you 'lock out' your administrative users by unassigning user groups or permissions, a restart ofthe application will re-privilege your default admin users.

4.5.3. Super Administrators

Users with super administrative privilege have automatically all permissions and can access all data. Togrant a user super administrative privilege, add it to the following setting in config/application-model-hub.properties:

# List of users, who get super-admin privileges (comma separated)actico.security.authorization.super-admins=SuperAdmin

If the rare case may arise that an user cannot access an entity and no other user can assignpermissions to this user in order to access the entity, a common solution is to add anadministrator user temporarily to the super administrator list to assign the privilege. Afterwardsthe administrator should be removed from the list. The application needs to be restarted forthese changes to take effect.

4.5.4. Internal Technical User

The Model Hub uses for some tasks an internal technical user with id System. The System user is not allowedto login and does not need to be configured in external authentication providers.

4.6. Authentication

Authentication can be done against a LDAP Server, Active Directory or any Open ID Connect authenticationsystem.



A user is registered within Model Hub in one of the following cases:

• user logs in

4.6.1. Active Directory / LDAP

Steps:

• Add the following properties to config/application-model-hub.properties

• Change values specific to your environment

# The authentication provider typeactico.security.authentication.provider-type=LDAP

# configure User handling## The LDAP filter used to search for users. For example "(uid={0})" or "(sAMAccountName={0})".actico.security.authentication.ldap.user-search-filter=(uid={0})## Search base for user searches.actico.security.authentication.ldap.user-search-base=

## User Attribute Mapping (optional)## The user ID mapping. For example "uid" or "sAMAccountName".#actico.security.authentication.ldap.user-attribute-mapping.userId=uid#actico.security.authentication.ldap.user-attribute-mapping.fullName=cn#actico.security.authentication.ldap.user-attribute-mapping.familyName=sn#actico.security.authentication.ldap.user-attribute-mapping.givenName=givenName#actico.security.authentication.ldap.user-attribute-mapping.preferredUsername=displayName#actico.security.authentication.ldap.user-attribute-mapping.email=mail

# JWT Token Configurationactico.security.authentication.jwt.access-token-validity-seconds=600actico.security.authentication.jwt.refresh-token-validity-seconds=1800

Additionally, an external Active Directory / LDAP Server or an Embedded LDAP Server must be configured asdescribed in the following chapters.

4.6.1.1. External Active Directory / LDAP

Steps:



actico.security.authentication.ldap.manager-dn=cn=admin,dc=actico,dc=comactico.security.authentication.ldap.manager-password=actico.security.authentication.ldap.url=ldap://localhost:389/dc=actico,dc=com

4.6.1.2. Embedded LDAP

In order to use an included embedded LDAP server follow these steps:



actico.security.authentication.ldap.base-dn=dc=actico,dc=comactico.security.authentication.ldap.ldif=classpath:embedded-ldap-demo.ldif

• Change the embedded-ldap-demo.ldif file to your needs. It is stored in the config folder.



Be aware that passwords can only be changed by editing this file.

Be aware that passwords are stored in clear text when using the embedded LDAP.

Be aware that advanced password policies like maximum login retries are not supported.

4.6.2. Open ID Connect

Steps:



actico.security.authentication.provider-type=EXTERNAL_OIDCspring.security.oauth2.resourceserver.jwt.issuer-uri=actico.security.authentication.oauth2.access-token-uri=${spring.security.oauth2.resourceserver.jwt.issuer-uri}/protocol/openid-connect/token

## User Attribute Mapping for provider-type=EXTERNAL_OIDC (optional)#actico.security.authentication.external-oidc.user-attribute-mapping.userId=preferred_username#actico.security.authentication.external-oidc.user-attribute-mapping.preferredUsername=name#actico.security.authentication.external-oidc.user-attribute-mapping.fullName=name#actico.security.authentication.external-oidc.user-attribute-mapping.familyName=family_name#actico.security.authentication.external-oidc.user-attribute-mapping.givenName=given_name#actico.security.authentication.external-oidc.user-attribute-mapping.email=email

4.7. Database

4.7.1. Roles and Permissions

Model Hub uses database tables, indexes, unique constraints and foreign key constraints. Technical row IDsare calculated using Identity column types.

Ensure that a database user with sufficient roles and privileges is available in order to create these databasestructures. Since Model Hub includes an automatic Schema update feature, the configured database user musthave sufficient roles and privileges to execute DDL statements.

4.7.2. Restrictions

Microsoft SQL Server needs to be configured with case insensitive collation (CI) and IsolationLevel READ_COMMITTED_SNAPSHOT.

4.7.3. Connection

Steps:

• Download JDBC database driver from vendor’s website

• Copy JDBC database driver to config/lib





spring.datasource.url=jdbc:...spring.datasource.username=spring.datasource.password=spring.datasource.driver-class-name=

In case of MySQL, also add the following property to config/application-model-hub.properties:

spring.jpa.properties.hibernate.dialect=org.hibernate.dialect.MySQL55Dialect

Make sure the database version matches with the System Requirements

A complete listing of example configuration settings for supported databases can be found in theappendix.

4.7.4. Schema Deployment

4.7.4.1. Automatic Deployment

On startup the application will automatically install or upgrade the database schema.

Please ensure that the configured data user has sufficient roles and privileges to perform DDLoperations for used database resources.

4.7.4.2. Manual Deployment with sqldump

If it is necessary to manually initialize or upgrade a database schema, the sqldump command can be used.Running

start-app sqldump --file=

will dump the SQL statements into the specified file. Executing them will deploy a schema the same way theautomatic deployment would.

The sqldump needs to connect to the database in order to detect the changes that are necessary.

4.8. Server

Model Hub uses an embedded web server to host the web application, Git Endpoints and REST Endpoints.Settings are already preconfigured, but may be needs to be adjusted.

To configure the embedded web server to your needs add settings starting with server.tomcat to theconfig/application-model-hub.properties file. A complete list of settings can be found at Spring BootApplication Properties.

4.8.1. Common Settings

Common configuration settings are:

https://docs.spring.io/spring-boot/docs/current/reference/html/common-application-properties.htmlhttps://docs.spring.io/spring-boot/docs/current/reference/html/common-application-properties.html



# Limits the size of http post requests to a maximum number of bytesserver.tomcat.max-http-post-size=104857600

Add these settings to config/application-model-hub.properties if necessary and configure theirvalues.

Model Hub does not support custom context roots. See also chapter Running behind ReverseProxy setup.

4.8.2. SSL

By default HTTP is enabled and the server uses port 8080.

In order to use HTTPS instead of HTTP a keystore with a SSL certificate is required. For a test and productionenvironment a SSL certificate issued by an official authority is recommended. For a development or demoenvironment a self signed SSL certificate may be sufficient.

The following command line uses the Java keytool and creates a keystore with filename keystore.p12 with aPKCS12 SSL certificate having a validity of 10 years.

keytool -genkey -alias model-hub -storetype PKCS12 -keyalg RSA -keysize 2048 -keystore keystore.p12 -validity 3650

Steps:

• Create keystore with SSL certificate

• Place keystore file in the config folder

• Add the following SSL related properties to config/application-model-hub.properties andconfigure them accordingly

Configure SSL related properties:

# SSL Connector portserver.port=8443# Allow only HTTPS requestssecurity.require-ssl=true

# Whether to enable SSL supportserver.ssl.enabled=true# Alias that identifies the key in the key storeserver.ssl.key-alias=model-hub# Password used to access the key in the key storeserver.ssl.key-password=# Path to the key store that holds the SSL certificate (typically a PKCS12 file)server.ssl.key-store=classpath:keystore.p12# Password used to access the key storeserver.ssl.key-store-password=# Type of the key store (JKS/PKCS12)server.ssl.key-store-type=PKCS12

4.8.3. Connection Pool

By default the Hikari Connection Pool is included in Model Hub and used with default settings. To configurethe Hikari Connection Pool specific to your needs add settings starting with spring.datasource.hikari tothe config/application-model-hub.properties file. A complete list of settings can be found at HikariConfiguration.

Common Hikari configuration settings are:

https://github.com/brettwooldridge/HikariCP#configuration-knobs-babyhttps://github.com/brettwooldridge/HikariCP#configuration-knobs-baby



# Maximum number of milliseconds that a client will wait for a connectionspring.datasource.hikari.connectionTimeout=30000# Maximum amount of time in milliseconds that a connection is allowed to sit idle in the poolspring.datasource.hikari.idleTimeout=600000# Maximum lifetime in milliseconds of a connectionspring.datasource.hikari.maxLifetime=1800000# Minimum number of idle connectionsspring.datasource.hikari.minimumIdle=10# Maximum size of connections (idle plus in-use connections)spring.datasource.hikari.maximumPoolSize=10

4.9. Running behind Reverse Proxy

To be able to run Model Hub behind a reverse proxy you need to configure the proxy to set some headers andconfigure Model Hub to accept these headers.

• Configure the reverse proxy, to set the following http headers

Table 4.1. Supported forward Headers

Header Description

X-Forwarded-Host recommended

X-Forwarded-Proto recommended

X-Forwarded-Port recommended

X-Forwarded-Prefix optional, depend on your setup

X-Forwarded-Ssl optional

Forwarded alternative to all above, see RFC

• add to config/application-model-hub.properties

actico.server.use-forward-headers=true

Model Hub application needs to run with root context. Reverse proxy might have another contextthat is mapped to the root context (e.g. /myapp will be mapped to /)

4.10. Script Environment

Model Hub comes with a preconfigured set of shell scripts that can be used to configure, start, stop, install anduninstall the server.

4.10.1. Startup

On a Windows system use the start-app.bat and stop-app.bat scripts for this purpose. On a Linux systemuse the start-app.sh and stop-app.sh scripts.

In a production environment it is recommended to install the application as a system service. On a Windowssystem use the install-service.bat file to install Model Hub as a service and use start-service.bator any operating system mechanism to start the service.

All scripts must be started from their respective folder. For Windows use bin\windows and forLinux bin/unix. Use these folders as working directory.



4.10.2. Shutdown

Always properly shutdown Model Hub. This is important for files to be closed. If the application was startedwith start-app.bat or start-app.sh it should be stopped with stopapp.bat or stop-app.sh.

If the Model Hub was installed as a Windows service, the stop-service.bat file or any operating systemmechanism to stop a service normally can be used.

Background Information:

• Model Hub is looking for a stop file actico.jvm.stop that is created in the work folder with aconfigured filename. If the file is detected, the application will initiate the shutdown process and willterminate. The stop flag file is configured using the --actico.stopfile command line argument.The --actico.stopfile.initsleep command line argument can be used in order to specify asleep time in seconds. The application waits for this duration until it looks for a stop flag file. Usethis argument to prevent a shutdown during the startup phase of the application. Finally the --actico.stopfile.jvmshutdown command line argument can be used to simply create the stop flag file,that signals an already running JVM to terminate.

• Use the --actico.stopfile and --actico.stopfile.initsleep command line arguments for theModel Hub itself.

• Use the --actico.stopfile and --actico.stopfile.jvmshutdown command line argumentsto initiate the termination of an already running Model Hub. Note that the stop flag file handling ispreconfigured in all provided scripts.

4.10.3. Configuration

If specific configuration is necessary, create a file config.bat or config.sh in the config folder. Use thisfile in order to overwrite environment variables defined by the bin\windows\config.bat or bin\unix\config.sh file. It will be evaluated after the config.bat file in the bin folder.

A custom config.bat file is also used during the installation as Windows Service.

Example additional config-debug.bat file, enabling debugging:

@echo offrem Environment configuration file for mode "debug".set "JVM_OPTIONS_APP=%JVM_OPTIONS_APP%;-Xdebug;-Xrunjdwp:server=y,transport=dt_socket,address=8778,suspend=n"exit /B 0

Example additional config-debug.sh file, enabling debugging:

#!/bin/bash# Environment configuration file for mode "debug".JVM_OPTIONS_APP="$JVM_OPTIONS_APP;-Xdebug;-Xrunjdwp:server=y,transport=dt_socket,address=8778,suspend=n"

The script environment supports additional configuration modes for the application. A configuration modeadds additional settings to environment variables that were preconfigured by the config.bat or config.shscript. To add a new configuration mode create a new file with the following filename schema: config-.bat. Configure the settings inside the created file. The file will be executed automatically if youpass as a command line argument for a script file (e.g. start-app ). Note that thismechanism works for start and stop scripts of the application.

4.10.4. Install as Windows Service

Model Hub also contains preconfigured scripts to install, start, stop and uninstall the application as a Windowsservice. Use the install-service.bat, start-service.bat, stop-service.bat and uninstall-service.bat scripts for this purposes. The Windows Service can also be started and stopped using anyoperating system mechanism.



4.11. Clustering

Clustering of multiple Model Hub instances is not supported.

Chapter 5. Operations and Maintenance



5.1. Temporary directories

The following temporary directories are used:

• the logs folder contains log files.

• the work folder contains temporary files of the embedded web server.

5.2. Backup and Restore

A backup must contain both data from the database and from the file system.

Backing up and restoring the database and file system should be closely spaced in time to keep them in sync.Reason is e.g. when creating a new repository, an entry is stored in the database and a git repository is createdwithin the file system.

It is recommended that backups be made either by previously shutting down the server or during a more orless inactive period. This will ensure that most file handles for the git repository are closed and that all data isincluded in the backup.

5.2.1. Database

Please refer to the user manual of the database provider.

5.2.2. File system folders

The data folder contains mainly the model versioning repositories that require to be included in a backup.

Also the config folder needs to be included in the backup as it may contain specific configuration files andspecific configuration settings.

5.3. Logging

ACTICO products use Apache Log4j 2 by default and come with a default log4j2 configuration available in theconfig directory.

The default configuration has been designed for production usage and provides the following settings:

• Log to console AND file

• Log errors to separate error log file

• Maximum size for log files: 10MB

• Maximum number of roll-over files: 20

• Files exceeding 10MB are zipped and placed in a archive directory next to the log file

• Maximum amount of zipped files to be kept: 20

These setting result in a maximum usage of about 70MB of disk-space consumed for log files.

5.3.1. Log Levels

Log levels can be configured in config/application-model-hub.properties (restart of server required)OR in config/log4j2.xml

https://logging.apache.org/log4j/2.x/



Examples configuring log levels in application properties.

# Log level configuration# Example to enable debug logging for a part of the applicationlogging.level.com.actico.repository=DEBUG

Examples configuring log levels in config/log4j2.xml.

...

5.3.1.1. Custom log4j2 configuration

Custom log4j2 configurations should only be considered, when the default logging appenders are not sufficientor required to be changed.

If a custom log4j2 configuration is desired, for example to configure custom appenders, create your ownlogging file by copying the existing log4j2.xml and place it in the config directory of the product andactivate the config in config/application-model-hub.properties:

The following config shows how to activate a custom log4j2-custom.xml for logging.

# Enable log4j2 custom configuration, if required. See operations guide for details.logging.config=${actico.component.home}/config/log4j2-custom.xml

Configuring your own log4j2 configuration can affect the standard behavior of the product andimpede maintenance and support.

5.4. Monitoring

To monitor the application, Spring Boot’s Actuator Web API is enabled. The actuator endpoints can be accessedat http://localhost:8080/actuator/.

Please check the Spring Boot Actuator Web API documentation for further information.

5.4.1. Endpoints

All actuator endpoints are enabled, here is a short list of some of them. The complete list can be seen at SpringBoot Actuator Endpoints documentation.

• info - Display application name and version

• health - Display health status of application (database, disk space)

• env - Display property environment configuration

• configprops - Display configuration settings

• threaddump - Display current thread dump

• metrics - Display application metrics

• logfile - Display the log file

• prometheus - Data source for the Prometheus monitoring solution

http://localhost:8080/actuator/https://docs.spring.io/spring-boot/docs/current/reference/html/production-ready-endpoints.htmlhttps://docs.spring.io/spring-boot/docs/current/reference/html/production-ready-endpoints.htmlhttp://prometheus.io



The endpoints require authentication. Either basic authentication, or OAuth2 token based authentication. Anauthenticated user must also have the configured authority (default: application.metrics). The authoritycan be configured with the `actico.security.rest.actuator-endpoints-authority`property.

See Chapter "REST Endpoints" how to authenticate using token based authentication.

The endpoints actuator/info and actuator/health do not require authentication orauthorization by default and therefore are suited best to be used for monitoring.

Appendix A. Migrations



A.1. Migration from Team Server

A.1.1. Introduction

Supported Team Server versions for the migration are 6.7 and 6.8.

Be aware about naming and other changes during migration. Changes are:

• Some characters in tags and branches are replaced:

• Spaces will be replaced with underscore (e.g. My Branch → My_Branch)

• German umlauts will be replaced (e.g. Ä → Ae)

• Branch HEAD will be named master

• Empty branches will not be migrated

• Emtpy tags will not be migrated

A.1.2. Migration Steps

1. Export and download the requested repository from Team Server (see Team Server documentation)

2. Generate user mapping

a. Export users from Identity Management (IM) by executing the following URL in the browser and savethe XML file.

http://:/im-server/1/rest/users?offset=0&limit=200

or the following URL, depending on the configuration

http://:/im/1/rest/users?offset=0&limit=200

The downloaded XML file contains an entry . If this number exceeds 200 (themaximum number of users to be downloaded at once), the offset needs to be increased by 200 untilall users are downloaded. Store all downloaded files in one folder.

Examples (local installation):

i. 1st set http://localhost:8087/im/1/rest/users?offset=0&limit=200

ii. 2nd set http://localhost:8087/im/1/rest/users?offset=200&limit=200

iii. 3rd set http://localhost:8087/im/1/rest/users?offset=400&limit=200

b. Create a mapping file with users referenced in the export

Make sure there is no Model Hub application running that was started with the samestart-app.bat script. Otherwise there might be conflicts in log files and otherresources. Recommendation is to use a separate installation.

start-app.bat ts6-usermapping --im-user-mapping-directory=C:\mymigrations\im-users --archive-file=C:\mymigrations\.zip --output-directory=C:\mymigrations

The --im-user-mapping-directory is the folder containg all downloaded users XML files. Thesecond parameter --archive-file is the Team Server export file. --output-directory specifiesthe location where the user mapping file mappings.csv is created.

http://:/im-server/1/rest/users?offset=0&limit=200http://:/im/1/rest/users?offset=0&limit=200http://localhost:8087/im/1/rest/users?offset=0&limit=200http://localhost:8087/im/1/rest/users?offset=200&limit=200http://localhost:8087/im/1/rest/users?offset=400&limit=200



c. Open the generated mappings.csv and edit if required. The users full name and the E-Mailaddress will be used in the commit history of the Model Hub Git repository. The first column hasthe ID used by Team Server. If no mapping like E-Mail or full name is given, this ID (e.g. d30cf610-ffab-11e4-9f76-0242ac1102b3) is used.

3. Start the migration itself

Make sure there is no Model Hub application running that was started with the samestart-app.bat script. Otherwise there might be conflicts in log files and other resources.Recommendation is to use a separate installation.

start-app.bat ts6-migration --user-mapping-file=C:\mymigrations\mapping.csv --archive-file=C:\mymigrations\.zip --output-directory=C:\mymigrations

The --user-mapping-file is the file with the user information, just create in the previous step. Thesecond parameter --archive-file is the Team Server export file. --output-directory specifies thelocation where the migrated repository is created.

4. Rename the folder --output-directory/.git if you wish a different name.

5. Verify the migration by switching to the directory --output-directory/.git. Execute e.g. git log (git needs to be installed locally) to check thecommit history and verify if the user mapping is as expected.

6. Once the repository migration was successful, copy the migrated repository to the directory data\model-versioning\teamserver.

7. Within your browser, navigate to Repositories and press the button New Repository. Enter the nameof the migrated repository (without suffix .git). The migrated repository is now linked and can be used.Don’t forget to assign permissions to other users if required.

Appendix B. Example Servers



B.1. Using Keycloak as external OpenID Connect authentication provider

These installation instruction is for demo usage only.

B.1.1. Setup Keycloak

• Start the jboss/keycloak docker container

docker run -d --name -p 8091:8080 -p 8082:8081 -p 9091:9090 -e KEYCLOAK_USER= -e KEYCLOAK_PASSWORD= jboss/keycloak

• Configure the Model Hub client

• Login as keycloak_admin_username at http://localhost:8091

• (optional) Create a new Realm and switch to that Realm

• Create a client at clients → create with name actico-model-hub and client protocol openid-connect

• Access Type: public

• Valid redirect URIs: http://localhost:8080/*

• Web Origins: +

• Create a new user at Users → Add user

• Set the user’s credentials at tab Credentials

• Navigate to Realm Settings and open the OpenId Endpoint Configuration and note the issuervalue

• In Realm Settings select the Security Defenses tab. Click on Brute Force Detection andenable it. Set the Max Login Failures to 5. Set Permanent Lockout to ON

B.2. Using LDAP as Authentication Provider


B.2.1. Prepare Password Policy

• Create a password-policy.ldif file in a directory of your choice, e.g. c:\temp\password-policy.ldif

• Paste the following content into that file

http://localhost:8091http://localhost:8080/*



# Load ppolicy moduledn: cn=module{0},cn=configchangetype: modifyadd: olcModuleLoadolcModuleLoad: {0}ppolicy

# Configure password policy moduledn: olcOverlay=ppolicy,olcDatabase={1}{{ LDAP_BACKEND }},cn=configchangetype: addobjectClass: olcPPolicyConfigobjectClass: olcOverlayConfigolcOverlay: ppolicyolcPPolicyDefault: cn=default,ou=pwpolicies,{{ LDAP_BASE_DN }}olcPPolicyHashCleartext: TRUEolcPPolicyUseLockout: TRUE

B.2.2. Prepare User Data

• Create a openldap-demo.ldif file in a directory of your choice, e.g. c:\temp\openldap-demo.ldif

• Paste the following content into that file



# create the people organizational unitdn: ou=people,dc=actico,dc=comobjectclass: topobjectclass: organizationalUnitou: people

# create the admin userdn: uid=admin,ou=people,dc=actico,dc=comobjectclass: topobjectclass: personobjectclass: organizationalPersonobjectclass: inetOrgPersoncn: AdministratordisplayName: Administratormail:[email protected]: Adminuid: AdminuserPassword: Admin

# create demo userdn: uid=davaar01,ou=people,dc=actico,dc=comobjectclass: topobjectclass: personobjectclass: organizationalPersonobjectclass: inetOrgPersoncn: David AaronsdisplayName: David Aaronsmail:[email protected]: Aaronsuid: davaar01userPassword: davaar01

# create the password policy nodedn: ou=pwpolicies,dc=actico,dc=comobjectClass: organizationalUnitobjectClass: topou: pwpolicies

# configure the password policydn: cn=default,ou=pwpolicies,dc=actico,dc=comobjectClass: topobjectClass: deviceobjectClass: pwdPolicycn: defaultpwdAttribute: userPasswordpwdLockout: TRUEpwdLockoutDuration: 0pwdMaxFailure: 5

B.2.3. Start LDAP Demo Server

Start the LDAP server using the following docker command. Change the location of the ldif file in case you didnot use c:\temp. This example assumes you run it on Windows.

docker run -d -p 389:389 -p 636:636 --name actico-openldap --env LDAP_ORGANISATION="Actico GmbH" --env LDAP_DOMAIN="actico.com" -v C:\temp\password-policy.ldif:/container/service/slapd/assets/config/bootstrap/ldif/password-policy.ldif -v C:\temp\openldap-demo.ldif:/container/service/slapd/assets/config/bootstrap/ldif/custom/openldap-demo.ldif osixia/openldap:1.2.5 --copy-service

B.3. Using MySQL as external database




docker run -p 3306:3306 --name model-hub-mysql -e MYSQL_ROOT_PASSWORD=pw123 -e MYSQL_DATABASE=modelhub81 -e MYSQL_USER=testuser -e MYSQL_PASSWORD=my-secret-pw -d mysql:5.7.26

Appendix C. Example Files


Appendix C. Example Files

C.1. Listing of Example Datasource Configuration Settings

Configure the settings corresponding to your specific environment.

C.1.1. Oracle Database

# Oraclespring.datasource.url=jdbc:oracle:thin:@:1521:ORCLspring.datasource.username=spring.datasource.password=spring.datasource.driver-class-name=oracle.jdbc.OracleDriver# Remove dialectspring.jpa.properties.hibernate.dialect=

C.1.2. Microsoft SQL Server

# MS SQLServerspring.datasource.url=jdbc:sqlserver://:1433;databaseName=testspring.datasource.username=spring.datasource.password=spring.datasource.driver-class-name=com.microsoft.sqlserver.jdbc.SQLServerDriver# Remove dialectspring.jpa.properties.hibernate.dialect=

C.1.3. MySql

# MySqlspring.datasource.url=jdbc:mysql://:3306/testspring.datasource.username=spring.datasource.password=spring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver# Configure dialectspring.jpa.properties.hibernate.dialect=org.hibernate.dialect.MySQL55Dialect

Operations GuideTable of ContentsChapter 1. About this document1.1. Audience1.2. Content1.3. Conventions

Chapter 2. IntroductionChapter 3. System Overview, Links and Authentication3.1. System Overview Diagram3.2. Web User Interface3.2.1. Demo Users

3.3. Modeler Endpoint3.4. Git Endpoint3.5. REST Endpoint

Chapter 4. Installation and Configuration4.1. Unpack4.2. Java Runtime4.3. License File4.4. Configuration4.5. Users4.5.1. Users4.5.2. Default Administrators4.5.3. Super Administrators4.5.4. Internal Technical User

4.6. Authentication4.6.1. Active Directory / LDAP4.6.1.1. External Active Directory / LDAP4.6.1.2. Embedded LDAP

4.6.2. Open ID Connect

4.7. Database4.7.1. Roles and Permissions4.7.2. Restrictions4.7.3. Connection4.7.4. Schema Deployment4.7.4.1. Automatic Deployment4.7.4.2. Manual Deployment with sqldump

4.8. Server4.8.1. Common Settings4.8.2. SSL4.8.3. Connection Pool

4.9. Running behind Reverse Proxy4.10. Script Environment4.10.1. Startup4.10.2. Shutdown4.10.3. Configuration4.10.4. Install as Windows Service

4.11. Clustering

Chapter 5. Operations and Maintenance5.1. Temporary directories5.2. Backup and Restore5.2.1. Database5.2.2. File system folders

5.3. Logging5.3.1. Log Levels5.3.1.1. Custom log4j2 configuration

5.4. Monitoring5.4.1. Endpoints

Appendix A. MigrationsA.1. Migration from Team ServerA.1.1. IntroductionA.1.2. Migration Steps

Appendix B. Example ServersB.1. Using Keycloak as external OpenID Connect authentication providerB.1.1. Setup Keycloak

B.2. Using LDAP as Authentication ProviderB.2.1. Prepare Password PolicyB.2.2. Prepare User DataB.2.3. Start LDAP Demo Server

B.3. Using MySQL as external database

Appendix C. Example FilesC.1. Listing of Example Datasource Configuration SettingsC.1.1. Oracle DatabaseC.1.2. Microsoft SQL ServerC.1.3. MySql

operations guide - version 8.1.2-r054 · 2019. 12. 4. · operations guide version 8.1.2-r054...

Documents