{section}
{column}

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

{warning}
Petals Cockpit *0.22.0* works with Petals ESB *5.2.0*, but may also work in degraded mode with previous versions.
{warning}
{column}
{column:width=40%}
{panel:title=Table of contents}{toc}{panel}
{panel:title=Contributors}{contributors:order=name|mode=list}{panel}
{column}
{section}

h1. Installing Petals Cockpit

The supported browsers are Chrome and chromium variants. While not officially supported, the frontend is highly compatible with Firefox.

{code}


h2. Building and running from docker

A pre-built Petals Cockpit docker image is hosted on [its docker hub public repository|https://hub.docker.com/r/petals/petals-cockpit/].
Docker must be properly installed on your system for these commands to function.

# Download the image:
{code}
$ docker pull petals/petals-cockpit:latest
{code}
# Start in detached mode
{code}
$ docker run -d -p 8080:8080 --name petals-cockpit petals/petals-cockpit:latest
{code}

For exhaustive information about building and running a docker image of Petals Cockpit, see the [Github docker-petals-cockpit project page|https://github.com/petalslink/docker-petals-cockpit].

h2. Building and running from sources

# Build the frontend
{code}
$ cd frontend && yarn run build:product && cd ..
{code}
# Build Petals Cockpit (it will also build the backend)
{code}

$ ./petals-cockpit.sh
{code}

For exhaustive information about building and running Petals Cockpit from its sources, see the [Gitlab Petals Cockpit project page|https://gitlab.com/linagora/petals-cockpit].

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

h1. Configuring Petals Cockpit


h2. 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.|http://www.dropwizard.io]

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

{code}
server:
  applicationConnectors:
    - type: http
      port: 8080
bindHost: 56.158.30.50

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

{code}
artifactServer:
temporaryPath: /tmp/petals-cockpit-artifacts
externalHost: 56.158.30.10
{code}

*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_.

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

{code}
database:
driverClass: org.h2.Driver
user: petals
password: petals
url: jdbc:h2:./db/cockpit

{code}
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

{code}
*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.*

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 :

{code}
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
{code}


|| Parameter || Optionnal || Default || Description ||

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.

h2. 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 :

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

There are also parameters and commands usable at launch.

h3. Using parameters

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

{code}
$ ./petals-cockpit.sh --debug --no-db-migrate
{code}







h3. Using commands

Adding a non admin user without workspace

{code}
$ ./petals-cockpit.sh add-user -u myUserName -n myName -p myPassword
{code}
Adding an admin user with workspace

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

Adding an LDAP admin user

{code}
$ ./petals-cockpit.sh add-user --username myUserName --name myName -l -a
{code}

h1. Managing users

h2. Logging in


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

<img login>

*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>

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

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


h3. Managing existing users

You can see the list of existing users.

*In LDAP mode*, you can only *delete* users.


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


h3. 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).

h1. Managing workspace

It aims to manage the different elements that make up the workspace: in particular the import of one or more *[bus ESB|https://doc.petalslink.com/pages/viewpage.action?pageId=1803735]* and the configuration of the elements related to it as well as consultation of existing services.

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.


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


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

h2. Selecting workspace

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

<img workspace overview>

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

h3. Managing people able to user this workspace

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.

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

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

h1. Working with buses

h2. Managing buses


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

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.

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

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