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 2 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 data base 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 Database Logging  Launching Petals Cockpit Using parameters Using commands Adding user and workspace 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 JRE available, set the environment variable JAVA_HOME with the path of the JRE 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. 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
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 8080:8080 --name petals-cockpit petals/petals-cockpit:latest
   

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 :

• A conf directory which contains the config.yml server configuration file
• A db directory which contains the generated cockpit.mv.db and cockpit.trace.db data base files.
• A lib directory which contains the petals-cockpit-X.X.X-capsule.jar application jarfile.
• A logs directory which contains the log files generated at runtime.
• A petals-cockpit.sh run script.
• A README.txt helper file.

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

Database

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

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

 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.

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 an user

Example:

Adding an non admin user without workspace

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

Adding an admin user with workspace

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

end