Introduction Petals Cockpit is a web interface to administrate a set of Petals ESB topologies. It is a Java standalone server application running as backend, which serves over HTTPS an Angular 6 frontend application that will run in the browser. From the web interface, users can connect to running instances of Petals containers and then administrate and deploy artifacts on them. The backend uses a database to hold all persistent informations, like users and workspaces. Petals Cockpit 0.22.0 works with Petals ESB 5.2.0, but may also work in degraded mode with previous versions.

Table of contents Introduction Installing Petals Cockpit Requirements Installing from .zip file Building and running from docker Building and running from sources Installation directory Configuring Petals Cockpit Configuration file Application connector Artifact server Database Logging Using LDAP SSL/TLS encryption (https) Example of a reverse proxy setup Configuring SSL in cockpit Launching Petals Cockpit Using parameters Using commands Adding user and workspace Managing users Logging in Adding the first admin with token Administrating users Adding a new user Managing existing users Using user preferences Changing theme Managing workspace The workspace perspective Creating the first workspace Adding a new workspace Selecting workspace Adding a description Managing workspace users Removing workspace Navigating between workspaces Working with buses Managing buses Importing a bus Managing import in progress Deleting a bus Visiting bus overview Working with containers Container views Container overview Container operations Deploying a component Overriding required shared libraries of a component Deploying a service assembly Deploying a shared library Working with components Component views Component overview About component Component shared libraries Service units Component operations Deploying a service unit Working with service units Service unit overview Contributors No contributors found for: authors on selected page(s)

Installing Petals Cockpit

Requirements

Petals Cockpit needs Java 8 to run the backend. If you have more than one JDK available, set the environment variable JAVA_HOME with the path of the JDK you want to use.

The H2 Database used by the backend is automatically handled. It can be changed from configuration files but, for now, no other than H2 were tested.

The supported browsers are Chrome and Chromium variants (Cockpit v1.x requires Chrome/Chromium v73.x at least). While not officially supported, the frontend is highly compatible with Firefox.

Installing from .zip file

1. Get latest compiled version from Petals Cockpit project page or directly from this link
2. Unpack it and go into the directory
3. On POSIX systems, if needed, set the execute bit on petals-cockpit.sh
4. Run Petals Cockpit script and follow instructions :

   $ ./petals-cockpit.sh
   

Building and running from docker

A pre-built Petals Cockpit docker image is hosted on its docker hub public repository.
Docker must be properly installed on your system for these commands to function.

1. Download the image:

   $ docker pull petals/petals-cockpit:latest
   

2. Start in detached mode

   $ docker run -d -p 8484:8484 --name petals-cockpit petals/petals-cockpit:latest
   

By default, an user with admin as username and password will be created.
For exhaustive information about building and running a docker image of Petals Cockpit, see the Github docker-petals-cockpit project page.

Building and running from sources

1. Build the frontend

   $ cd frontend && yarn run build:product && cd ..
   

2. Build Petals Cockpit (it will also build the backend)

   $ mvn -s ci/settings.xml clean verify antrun:run@build-product-dist
   

3. The final distribution directory (as found in the .zip version) will be in cockpit/target/dist. On POSIX systems, if needed, set the execute bit on petals-cockpit.sh
4. From there, run the script:

   $ ./petals-cockpit.sh
   

For exhaustive information about building and running Petals Cockpit from its sources, see the Gitlab Petals Cockpit project page.

Installation directory

The installation directory from ZIP archive and compiled sources contains :

• conf directory which contains the config.yml server configuration file
• db directory which contains the generated cockpit.mv.db and cockpit.trace.db database files.
• lib directory which contains the petals-cockpit-X.X.X-capsule.jar application jarfile.
• logs directory which contains the log files generated at runtime.
• third-party directory which contains:
  • licenses directory which contains backend licenses
  • third-party-backend-licenses.xml linking dependencies to their license
• petals-cockpit.sh run script.
• README.txt helper file.
• LICENSE.md Petals Cockpit license file.
• COPYRIGHT Petals Cockpit copyright file.
• THIRD-PARTY-BACKEND lists backend dependecies licenses
• THIRD-PARTY-FRONTEND lists backend frontend licenses

Configuring Petals Cockpit

Configuration file

The configuration file: ./conf/config.yml allows you to configure cockpit server.

The server is based on Dropwizard, you should find more informations about configuration on their website.

Application connector

Here you can modify the port on which the frontend application will be served :

server:
  applicationConnectors:
    - type: http
      port: 8080
      bindHost: 56.158.30.50

bindHost will set your default connector host IP. If not overridden in artifactServer section, it will also be used by the artifact server. It is optional and will be localhost (127.0.0.1) by default.

Artifact server

This section configures the artifact server, which is responsible of serving artifacts (from cockpit backend to Petals containers) while deployed using cockpit interface.

artifactServer:
  temporaryPath: /tmp/petals-cockpit-artifacts
  externalHost: 56.158.30.10

temporaryPath: Local file location while artifact is served. (Default "{java.io.tmpdir}/petals-cockpit-artifacts")

externalHost: This host overrides bindHost in the address sent to petals to download artifacts. Thus default is server.applicationConnectors.bindHost.

Database

This section allows you to choose which database the backend will use.

You can specify the adress, driver and user/password to connect to the database.

 database:
  driverClass: org.h2.Driver
  user: petals
  password: petals
  url: jdbc:h2:./db/cockpit
  validationQuery: "/* Health Check */ SELECT 1"

Petals Cockpit 0.22.0 has only been tested with H2 database. Be careful changing this. Validation query may have to be adapted as well to the chosen DB.

Logging

This section allows you to choose where and how logs are displayed and archived. Dropwizard provides a rather customisable configuration system, this is the default for Petals Cockpit:

 server:
  requestLog:
    appenders:
      - type: file
        currentLogFilename: ./logs/cockpit-access.log
        archivedLogFilenamePattern: ./logs/cockpit-access-%d.log.gz

logging:
#Global logging setting
  level: INFO

#Specific cockpit loggers settings
#(will bypass the console threshold & filter)
  loggers:
    "org.ow2.petals.cockpit.server":
      level: INFO
      appenders:
        - type: console

#File logging uses global setting, console filters out global cockpit output
#(to avoid duplicates from previous specific logger)
  appenders:
    - type: file
      currentLogFilename: ./logs/cockpit.log
      archivedLogFilenamePattern: ./logs/cockpit-%d.log.gz
      archivedFileCount: 5
    - type: console
      threshold: WARN
      filterFactories:
      - type: cockpit-server-filter-factory

server.requestLog.appenders allows to choose where to log all REST requests reaching the server.

logging.appenders allows to choose where to log the application output, you can filter it by logging level. Levels can be OFF, ERROR, WARN, INFO, DEBUG, TRACE, or ALL.

• logging.level is the global level for the application output, it controls directly what will be found in logging.appenders.type: file (./logs/cockpit.log)
• logging.appenders.threshold (under type: console) is the level that will be displayed in the console from all sources (except from org.ow2.petals.cockpit.server.*). Cannot be set lower than global level.
• logging.loggers allows to set specific loggers at independent levels. Here you can set any specific java class or package to the desired level on top of the rest.

This way, by default, output from org.ow2.petals.cockpit.server.* java classes (petals cockpit code specifically) will be displayed under INFO level. While global output (from dropwizard framework or other dependencies) will remain at WARN level in the console.
The console filter cockpit-server-filter-factory filters out all output from org.ow2.petals.cockpit.server.*, in order to prevent duplicates from the specific logger it is advised to leave it.

Using LDAP

LDAP connection is fully available since Petals Cockpit 0.27.0. Previous builds may not have this feature operational.

If an LDAP configuration section is added to the configuration file, Cockpit will go in LDAP mode. When in this mode, users (even admin) will only be able to log in Cockpit if they credentials are validated by the configured LDAP. If configuration is wrong or LDAP is down, user will not be able to log in. To use LDAP, add these lines :

ldapConfig:
  url: ldap://10.31.4.167:389
  usersDn: ou=personnes,dc=my-domain,dc=com
  usernameAttribute: uid
  nameAttribute: cn
  passwordAttribute: password
  principalDn: uid=admin,ou=personnes,dc=my-domain,dc=com
  principalPassword: adminpass

The technical LDAP account is used to request the LDAP server, thus it must have read rights on LDAP server.

Petals cockpit is not designed to be able to switch LDAP authentication on and off with a same installation. Users added through LDAP are not available without it, and vice versa. If you want to activate or deactivate LDAP authentication, it is advised to wipe the database in the meantime.

SSL/TLS encryption (https)

The Secure Socket Layer protocol ensures secure transactions between web servers and browsers. The protocol uses a third party, a Certificate Authority (CA), to identify one end or both end of the transactions.
Cockpit is supposed to be running within your infrastructure. Which means it will be running in clear, and encryption should be handled elsewhere (with a proxy for instance). Anyway, Cockpit is based upon Dropwizard which handles natively SSL; so configuring encryption in cockpit backend remains an option; should you desire so.

Example of a reverse proxy setup

Here's an example of a nginx reverse proxy setup (which we use for our testing). With such a setup, there is no need to configure anything in cockpit, as you can see below Cockpit in accessed in clear by the proxy:

server {
    # Exposed name (for our testing its localhost, but it should not be)
    server_name localhost;
    location / {
        # address to reach cockpit backend instance
        proxy_pass http://127.0.0.1:8484;

        # this configuration ensure SSE will reach through
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        proxy_buffering off;
        proxy_cache off;
        chunked_transfer_encoding off;
    }
# ipv6 and ipv4 listener
listen [::]:443 ssl ipv6only=on;
listen 443 ssl;

# Certificate and key pair
ssl_certificate /mkcert/localhost+2.pem;
ssl_certificate_key /mkcert/localhost+2-key.pem;

# Avoid SSE timeouts
# Nginx will close connections periodically (timeout), the connection will be restored right after.
# The whole workspace will be send each time, inscreasing the timeout reduces traffic load.
# Value is in seconds. Default value is 60s, there it's configured for 600s so 10 minutes.
proxy_connect_timeout 600;
proxy_send_timeout    600;
proxy_read_timeout    600;
send_timeout          600;
keepalive_timeout     600;

}

Configuring SSL in cockpit

If you want to handle SSL in cockpit, here's the configuration to add (from Dropwizard documentation)

SSL support is built into Dropwizard. You will need to provide your own java keystore, which is outside the scope of this document (keytool is the command you need, and Jetty’s documentation can get you started).

Configure a new keystore with an SSL certificate with keytool :

1. Use the following syntax to create the new keystore with a self-signed certificate:

   keytool -genkey -alias <alias> -keyalg RSA -keystore <keystore_filename>

2. Create a certificate signing request using the following syntax, and then send the certificate request to the Certificate Authority you are using.

   keytool -certreq -alias <alias> -keyalg RSA -file <csr_output_file> -keystore <keystore_filename>

   Procedure may then vary depending to your Certificate Authority, follow their instructions.

3. Depending on the CA you are using you may need to import an intermediate certificate and/or root certificate into your keystore. If you are importing both certificates the alias specified for each certificate should be unique. You need to first import the root certificate, and then run the keytool command again to import the intermediate certificate. Use the following syntax to import one or both of these certificates:

   keytool -import -alias <alias> -keystore <keystore_filename> -trustcacerts -file <certificate_filename>

   The alias specified must be the same value specified in step 2 when you generated the keystore. The imported certificate will replace the default self-signed certificate created in the keystore.

4. You can then check the certificate was successfully added using this command:

   keytool -list -v -keystore <keystore_filename>

5. Copy the keystore file where Cockpit will be able to access it.
6. Add this configuration to cockpit configuration file:

   server:
     applicationConnectors:
       - type: https
         port: 8443
         keyStorePath: /path/to/your.keystore
         keyStorePassword: examplePassword
         validateCerts: false
   

Launching Petals Cockpit

When you launch Petals Cockpit for the first time, a Database will be created (if none was found at configured URL).

Also, if no user were found in the database, a token will be be generated in order to add an administrator using the web interface. For instance :

WARN [2018-04-24 12:19:58,370] org.ow2.petals.cockpit.server.CockpitApplication: No users are present in the database: setup your installation via http://127.0.1.1:8080/setup?token=t3Zm5A8MtNUcRJgHPxwc

Be sure to have logging correctly set up for it to display.

There are also parameters and commands usable at launch.

Using parameters

Parameters can be added to the launching script petals-cockpit.sh :

Example:

$ ./petals-cockpit.sh --debug --no-db-migrate

Using commands

Adding user and workspace

The add-user command allows you to add a user.

Since version 1.16 :

• when adding LDAP user, name is fetched from LDAP server (argument is forbidden)
• when workspace name is specified, if a workspace with similar name exists, the user is added to it
• when workspace name is specified, permissions can be set (false if omitted)

Example:

Adding a non admin user without workspace

$ ./petals-cockpit.sh add-user -u myUserName -n myName -p myPassword

Adding a non admin user with workspace and 2 permissions

$ ./petals-cockpit.sh add-user --username myUserName --name myName -p myPassword -w myWorkspace -A --deployArtifact

Adding an admin user with workspace

$ ./petals-cockpit.sh add-user --username myUserName --name myName -p myPassword -w myWorkspace -a

Adding an LDAP admin user

$ ./petals-cockpit.sh add-user --username myUserName -l -a

Managing users

Logging in

When connecting to the web application, you have to log in. Type in your username and password to do so.

<img login>

Adding the first admin with token

If no admin are present in the database, you can add one on the setup page. You will have to fill the token field with the token provided by the backend (if you used the link {ip}:{port}/setup?token={token} the token field will be pre-filled).

In normal mode (not LDAP), you must fill the username, password and name fields to be able to add the user.

In LDAP mode, only the username field is present and you must fill it with a valid LDAP username.

Once all the fields are filled, click the button to add your first admin.

After adding the user, you will be redirected to the login page by clicking the button.

<img login token>

Administrating users

If you are an Administrator, you have access to the Administration page. To go there click on the gear icon on the top right corner. <img administration gear icon>

<img user administration page>

Adding a new user

By clicking on "ADD A NEW USER" you can open a form to add a new user.

In normal mode (not LDAP), you must fill the username, password and name fields to be able to add the user.

In LDAP mode, only the username field is present and you must fill it with a valid LDAP username.

Then click the button to add the user.

Managing existing users

You can see the list of existing users.

By clicking on a user an edition form will unfold.

In normal mode (not LDAP), you can modify users to change their name and / or password (username cannot be changed) or delete them. Type new values in the corresponding field to change them. Leaving password empty will not change their password. Then click "SAVE".

In LDAP mode, you can only delete users.

Using user preferences

Once logged, you can access user preferences by clicking on the profile icon in the top right corner (the one on the far right).

<img user pref logo>

Changing theme

Here you can select the GUI theme. For now, this preference is stored locally on you browser local storage and is linked to the server address (Meaning each cockpit backend instance will have a shared theme set for any users using the same browser on the same machine).

Managing workspace

The workspace perspective

The workspace perspective is the perspective that opens by default when launching Petals Cockpit.

The workspace is the entity that preserve the project and their contents. We can represent this as a directory.
It aims to manage the different elements that make up the workspace: in particular the import of one or more Petals buses and the configuration of the elements related to it as well as consultation of existing services.
The access to a workspace is limited to its users (see Managing workspace users))

By default, this perspective contains the following windows :

• The Workspaces view displays the workspaces accessible by the authenticated user and allows to add new ones by clicking on the button (view list button) in the top left corner near the workspace name;
• The Workspace view that allows you to obtain information about a workspace (description and list of users) is accessible by clicking on the button with its name in the top left corner or in the selection window at workspace;
• The Bus Import view displays a specific import form with controls on the input fields. To access it, just click the button (+) in the side panel next to the search bar;
• The Petals view which allows to obtain a tree with all the elements attached to the bus. These elements are also called resources. Each of these resources has a detailed view (overview), some also have an operations view;
• The Services view provides a detailed view of the service names and their dependencies.

Creating the first workspace

Once logged in, you must set a name to your workspace. Then click on the button (new folder button) to add it.
You can then set the workspace description and manage the authorized users.

Adding a new workspace

You can create as many workspaces as you want, but by default they will all be empty.
It will be necessary to select the one you wish to work on by simply clicking on it.

<img workspaces list>

Selecting workspace

Once workspace loaded, you will be redirected to the workspace page.

<img workspace overview>

Adding a description

By clicking on the edit icon from the whiteboard description area, you can put a specific description using markup formatting: *markdown*.
Then click “SUBMIT” to save or “CANCEL” if you want reset description.

Managing workspace users

By clicking on the input field from the users area, a list of users name will unfold. You can then:

• Add a user on this workspace by selecting a user and clicking "ADD";
• Delete them by clicking delete button.

Removing workspace

It is only possible to delete a workspace when in its view. Just click on the delete button at the top right of the page and confirm the deletion by clicking "DELETE".

Be sure you want to do this because everything in this workspace will no longer exist for you but also for other users.

You will then be redirected to the list of available workspaces.

Navigating between workspaces

It is possible to browse the list of available workspaces for the user (ie, having access to it) and navigate between the workspaces. You have to open the workspaces list view, and click the workspace of your choice to load it.

Working with buses

Buses are a representation of a Petals topology, composed of registries, domains and containers. For now, only containers are represented in Petals Cockpit.

In Cockpit, importing a bus means connecting to one of its containers (providing containers credentials and topology passphrase) in order to get topology informations from it. Then it tries to establish connection to all containers declared in the topology, gathering their informations in cockpit DB. Once imported, the bus and its containers are displayed in the Petals tab tree view.

<img petals tree view>

Managing buses

Importing a bus

In the Petals tab view, click on the add (+) icon located in the top right corner of the tab panel, right next to the search bar. The Workspace Bus Import view will open:

<img workspace bus import>

There you can fill all mandatory informations to connect to a Topology:

• IP (or hostname) and port: of a container to connect to it.
• Username and password: credentials to connect to the container.
• Topology passphrase: to allow accessing topology data.

At all time, fields can be cleared by clicking the CLEAR button.
Once all fields are filled, the IMPORT button will activate, click on it to start importing the Bus. This will create an IMPORT IN PROGRESS item.

Managing import in progress

As topology can be quite complex and distributed among several distant locations, importing a whole topology can take some time. Thus, while this action is performed on the server of cockpit, IMPORT IN PROGRESS view (accessed by clicking on an item) will allow you to keep track and take actions. Once imported, the bus in progress should automatically disappear from the IMPORTS IN PROGRESS and the imported bus show in the BUSES section.

Should a bus import fail, it will remain as failed bus in progress until deleted. You can click on it to see the error that prevented the import.

Both imports in progress and failed imports can be discarded using the CANCEL (or DISCARD) button. You can also click on DISCARD AND RETRY to discard the import and reopen the import form (keeping ip, port and username fields pre-filled). Password and Passphrase are not kept and must always be provided again.

Deleting a bus

To delete a bus, click on the Bus item, then click on the delete icon (red icon with a garbage bin). A popup will ask you again if you wan to delete the bus, or cancel the action. Note: Buses are only deleted from the worskpace, they are not shown anymore in cockpit but the bus itself is not impacted. If the bus was also imported in another workspace before being deleted, it will remain imported in the other workspace.

Visiting bus overview

By clicking on a bus item, you can go to its overview page. It will show the bus description and its containers. You can click on a container to go to the associated container overview.

Working with containers

When a container is selected in Petals tree, containers views are displayed in the right frame. Two tabs are available: container OVERVIEW and OPERATIONS, they are explained in the container view section.

There are also optional subsections under each container (COMPONENTS, SERVICE ASSEMBLIES and SHARED LIBRARIES) that will appear in the Petals tree if one of the corresponding artifact is deployed on the container.

Container views

Container overview

This view displays:

• An About card that shows the IP and Port used to connect to the container (via JMX RMI)
• A System info card that displays information returned by the container
• A Container reachabilities card that displays a graph of this container topology and the reachabilities of containers. Clicking on a container node will select it in the graph; displaying IP and Port of selected container, and a button View this container jumping to the selected container overview. 

Container operations

Cockpit can be used as artifact server to deploy artifacts on a container. The files will first be uploaded to cockpit backend, which will in turn serve them (via an http server) to the container in order to deploy them.

If you are experiencing issues connecting a container and the backend see the Artifact server section.

Deploying a component

By clicking on the CHOOSE A FILE button in the COMPONENT DEPLOYMENT card, you can select a component to deploy on the container.

<img: component deploy>

In the top yellow box you can see the file to be uploaded. You can cancel the deploy by clicking either on the cross at the right end of the yellow box or on the cancel button at the bottom of the deploy card.

In the EDIT INFORMATION card you can override the name of the component (that the container will use to identify this component).

You can also see the list of shared libraries required by the component, and if they are already deployed on this container. By clicking on the Override Shared Libraries icon (the one with a book stack) you can open a popup to override the required shared libraries.

Overriding the component informations means altering its jbi.xml file before deploying it. Use this only if you are certain of the requirement of the component.

When all information are in order, you can deploy the component by clicking the UPLOAD button.

Overriding required shared libraries of a component

On the popup you can see actual shared libraries needed by the component you are uploading.
You can rename these shared libraries, or change their version by modify directly their values on the textfields. You can remove the shared libraries by clicking delete button on the right. You can add shared libraries by click ADD button and filling name and version textfields.
When you are done managing shared libraries, click SAVE button.
If you don't want your modifications to be saved, click CANCEL.

<img: override component sl>

Deploying a service assembly

By clicking on the CHOOSE A FILE button in the SERVICE ASSEMBLY DEPLOYMENT card, you can select a service assembly to deploy on the container.

Deploying a shared library

By clicking on the CHOOSE A FILE button in the SHARED LIBRARY DEPLOYMENT card, you can select a shared library to deploy on the container.

Working with components

See this page to learn mode about Petals components: https://doc.petalslink.com/display/petalscomponents/Understanding+Petals+components

Components are visible on Petals tree under the COMPONENTS category for each container. When a component is selected, its view is displayed in the right frame. Two tabs are available: component OVERVIEW and OPERATIONS, they are explained in the Component views section.

Component views

Component overview

About component

In this section, the component's current state and type are displayed.

Component shared libraries

A list of shared libraries required by the component, you can view each one by clicking on the button.

Service units

If a component has service units, they are displayed with their service assembly as buttons on the SERVICE UNITS. Clicking these buttons will go respectively to the service unit or service assembly view.

Service units in this section are also displayed as component's children in Petals tree.

Component operations

On the OPERATION tab, you can view component's lifecycle, change its state or change its parameters.

Deploying a service unit

By clicking on the CHOOSE A FILE button in the SERVICE UNIT DEPLOYMENT card, you can select a service unit to deploy on the component.

Working with service units

Service unit overview

When you select a service unit, you are redirected on its overview.