{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 5 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
h2. Requirements
Petals Cockpit needs [Java 8|http://www.oracle.com/technetwork/java/javase/downloads/jre8-downloads-2133155.html] to run the backend. {color:#333333}If you have more than one JRE available, set the environment variable JAVA_HOME with the path of the JRE you want to use.{color}
The [H2 Database|http://www.h2database.com/html/main.html] 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. While not officially supported, the frontend is highly compatible with Firefox.
h2. Installing from .zip file
# Get latest compiled version from [Petals Cockpit project page|https://gitlab.com/linagora/petals-cockpit]
# Unpack it and go into the directory
# On POSIX systems, if needed, set the [execute bit|https://en.wikipedia.org/wiki/File_system_permissions] on *petals-cockpit.sh*
# Run Petals Cockpit script and follow instructions :
{code}
$ ./petals-cockpit.sh
{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}
$ mvn -s ci/settings.xml clean verify antrun:run@build-product-dist
{code}
# 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|https://en.wikipedia.org/wiki/File_system_permissions] on *petals-cockpit.sh*
# From there, run the script:
{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]
h3. Application connector
Here you can modify the port on which the frontend application will be served :
{code}
server:
applicationConnectors:
- type: http
port: 8080
{code}
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
validationQuery: "/* Health Check */ SELECT 1"
{code}
{warning}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.{warning}
h3. 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:
{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.*
* *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.
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 :
{quote}
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]
{quote}
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* :
|| Name || Description ||
| *\--no-db-migrate* \\ | At startup, db version is automatically migrated to the version embedded in the jar file. *This options allows you to skip this migration (not recommended). * |
| *\--no-db-check* \\ | if *\--no-db-migrate* is set, the status of the database will be checked. If it is not up to date, the application will exit. *This option allows you to skip this check (not recommended).* |
| *\--debug* \\ | This option will launch Petals Cockpit in debug mode. Allowing an IDE (for instance: Eclipse) to *connect to it via port 5000* and benefit from debugging functionalities such as breakpoints and variable inspection. |
Example:
{code}
$ ./petals-cockpit.sh --debug --no-db-migrate
{code}
h3. Using commands
h4. Adding user and workspace
The *add-user* command allows you to add an user
|| Argument || Short argument || Optionnal || Default || Description ||
| \--username | \-u | no | \- | The user's id, also his login. |
| \--name | \-n \\ | no \\ | \- | The name under which the user will appear. |
| \--password \\ | \-p | no \\ | \- | The user's password. |
| \--admin | \-a | yes \\ | \- | Whether the user will be added as an admin or not. |
| \--workspacename | \-w | yes \\ | \- | The user's workspace. Which will be created and set as current workspace for the user. |
Example:
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}
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>
h3. Adding the first user with token
If no user are present in the database, a dialog box will allow you tu add one. You will have to use the token provided by the backend (if you used the link *\{ip\}:\{port\}/setup?token=\{token\}* the token field will be pre-filled). You must fill the remaining *username*, *password* and *name* fields to be able to add the user. You will be redirected to the login page.
<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. Type in his *username*, *name* and *password* and click "ADD" to add him.
h3. Managing existing users
On the right you can see the list of exising users. By clicking on an user an edition form will unfold. You can then:
* Set him a new *name* and / or *password.* Type in the new values in the corresponding field to change them. Leaving password empty will not change his password. Then click "SAVE" ;
* Delete him by clicking on "DELETE".
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
h2. 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 *[bus ESB|https://doc.petalslink.com/pages/viewpage.action?pageId=1803735]* and the configuration of the elements in relation 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 seems like list in the top left corner near the workspace name ;
* The _Workspace_ view that allows you to obtain information about it (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 imput fields. To access it, just click on the button with an add icon in the area to the left where is the content of *Petals* ;
* 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, some also have a view of operations ;
* 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 add button to save it in a normally empty list on first use.
You can then see the name of the created workspace and your authorized access to access it.
h3. Adding a new workspace
You can create as many workspace as you want, but by default they will all be empty.
It will be necessary to select the one on which you wish to work 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
WIP
h3. Removing workspace
WIP
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.
{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 5 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
h2. Requirements
Petals Cockpit needs [Java 8|http://www.oracle.com/technetwork/java/javase/downloads/jre8-downloads-2133155.html] to run the backend. {color:#333333}If you have more than one JRE available, set the environment variable JAVA_HOME with the path of the JRE you want to use.{color}
The [H2 Database|http://www.h2database.com/html/main.html] 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. While not officially supported, the frontend is highly compatible with Firefox.
h2. Installing from .zip file
# Get latest compiled version from [Petals Cockpit project page|https://gitlab.com/linagora/petals-cockpit]
# Unpack it and go into the directory
# On POSIX systems, if needed, set the [execute bit|https://en.wikipedia.org/wiki/File_system_permissions] on *petals-cockpit.sh*
# Run Petals Cockpit script and follow instructions :
{code}
$ ./petals-cockpit.sh
{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}
$ mvn -s ci/settings.xml clean verify antrun:run@build-product-dist
{code}
# 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|https://en.wikipedia.org/wiki/File_system_permissions] on *petals-cockpit.sh*
# From there, run the script:
{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]
h3. Application connector
Here you can modify the port on which the frontend application will be served :
{code}
server:
applicationConnectors:
- type: http
port: 8080
{code}
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
validationQuery: "/* Health Check */ SELECT 1"
{code}
{warning}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.{warning}
h3. 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:
{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.*
* *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.
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 :
{quote}
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]
{quote}
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* :
|| Name || Description ||
| *\--no-db-migrate* \\ | At startup, db version is automatically migrated to the version embedded in the jar file. *This options allows you to skip this migration (not recommended). * |
| *\--no-db-check* \\ | if *\--no-db-migrate* is set, the status of the database will be checked. If it is not up to date, the application will exit. *This option allows you to skip this check (not recommended).* |
| *\--debug* \\ | This option will launch Petals Cockpit in debug mode. Allowing an IDE (for instance: Eclipse) to *connect to it via port 5000* and benefit from debugging functionalities such as breakpoints and variable inspection. |
Example:
{code}
$ ./petals-cockpit.sh --debug --no-db-migrate
{code}
h3. Using commands
h4. Adding user and workspace
The *add-user* command allows you to add an user
|| Argument || Short argument || Optionnal || Default || Description ||
| \--username | \-u | no | \- | The user's id, also his login. |
| \--name | \-n \\ | no \\ | \- | The name under which the user will appear. |
| \--password \\ | \-p | no \\ | \- | The user's password. |
| \--admin | \-a | yes \\ | \- | Whether the user will be added as an admin or not. |
| \--workspacename | \-w | yes \\ | \- | The user's workspace. Which will be created and set as current workspace for the user. |
Example:
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}
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>
h3. Adding the first user with token
If no user are present in the database, a dialog box will allow you tu add one. You will have to use the token provided by the backend (if you used the link *\{ip\}:\{port\}/setup?token=\{token\}* the token field will be pre-filled). You must fill the remaining *username*, *password* and *name* fields to be able to add the user. You will be redirected to the login page.
<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. Type in his *username*, *name* and *password* and click "ADD" to add him.
h3. Managing existing users
On the right you can see the list of exising users. By clicking on an user an edition form will unfold. You can then:
* Set him a new *name* and / or *password.* Type in the new values in the corresponding field to change them. Leaving password empty will not change his password. Then click "SAVE" ;
* Delete him by clicking on "DELETE".
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
h2. 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 *[bus ESB|https://doc.petalslink.com/pages/viewpage.action?pageId=1803735]* and the configuration of the elements in relation 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 seems like list in the top left corner near the workspace name ;
* The _Workspace_ view that allows you to obtain information about it (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 imput fields. To access it, just click on the button with an add icon in the area to the left where is the content of *Petals* ;
* 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, some also have a view of operations ;
* 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 add button to save it in a normally empty list on first use.
You can then see the name of the created workspace and your authorized access to access it.
h3. Adding a new workspace
You can create as many workspace as you want, but by default they will all be empty.
It will be necessary to select the one on which you wish to work 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
WIP
h3. Removing workspace
WIP
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.