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 a 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 | yes/no | \- | The user's password. Required only for non-LDAP users. |
| \--admin | \-a | yes | \- | Whether the user will be added as an admin or not. |
| \--ldapUser | \-l | yes | \- | Whether the user to add is an LDAP user 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}
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>
h3. 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>
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.
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.
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 *[Petals buses|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.
The access to a workspace is limited to its users (see [Managing workspace users)|#Managing workspace users|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.
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 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.
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
Buses are a representation of a [Petals topology|https://doc.petalslink.com/display/petalsesb510/Topology+Configuration], 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>
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.
h3. 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.
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.
h1. 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.
h2. Container views
h3. 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.
h3. 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.
{note}
If you are experiencing issues connecting a container and the backend see the [Artifact server|#Artifact server|Artifact server] section.
{note}
h4. 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.
h5. 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>
h4. 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.
h4. 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.
h1. 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|#Component views|Component views] section.
h2. Component views
h3. Component overview
h4. About component
In this section, the component's current state and type are displayed.
h4. Component shared libraries
A list of shared libraries required by the component, you can view each one by clicking on the button.
h4. 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.
h3. Component operations
On the _OPERATION_ tab, you can view component's lifecycle, change its state or change its parameters.
h4. 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.
h1. Working with service units
h2. Service unit overview
When you select a service unit, you are redirected on its overview.
E-mail
...