Home

Getting started

Prerequisites

1. Make sure that some Java JDK is installed (tested on AdoptOpenJDK 8)

2. Install docker:

   • Windows / Mac use: Docker desktop
   • Linux use: Docker

Additional steps for Windows:

• Make sure that Hyper-V is enabled
  
• Log-in to Docker Desktop in Windows tray
• Check Expose daemon on... property
  
• Share drive where cogboard was cloned
  
• Disable Cloud Experience
  

WARN: We've discovered that in Docker v 19.03.13 there is a problem with disabling Cloud Experience and this change may not been saved. Always check if it's disabled before building application!

Installation

Note: Docker instalation will be available from version 1.0.0.
Note: For development installation go here.

1. Download cogboard-1.0.0.zip from latest release.

2. Extract cogboard-1.0.0.zip

3. Optional: Execute the command below if this is the first time use of docker on a machine.

docker swarm init

4. Deploy CogBoard Stack

docker stack deploy -c cogboard-compose.yml cogboard

To uninstall stack use: docker stack rm cogboard command.

Developer Installation

Use this approach when developing new features for CogBoard.

1. Clone Cogboard repository

git clone https://github.com/Cognifide/cogboard.git

2. Execute below command inside the cloned repository:

./gradlew

After successful installation CogBoard should be up and running on localhost

For debugging see Debugging wiki section.

Running Cogboard on different port see Changing default port wiki section.

Update

Note: Only the latest version is supported by updates.

1. Uninstall old version

docker stack rm cogboard-local

or

./gradlew undeployLocal

2. Follow installation guide.

Backup

Configuration persistence is achieved with Docker Volume feature.

• Config files are stored under <project_root>/mnt/ folder.
• mnt folder contains:
  • admin.json - in this file setup of administrator is held
  • config.json - in this file setup of boards and widgets is held
  • credentials.json - in this file setup credentials is held
  • endpoints.json - in this file setup of endpoints is held
• In order to backup files copy files from mnt folder somewhere safe.

Note: Files from mnt/content folder are not required for backup.

Restore

Copy config files mentioned in Backup section to mnt folder of new instance of Cogboard.

---

Configuration

Login as Admin

Use login button (left top corner) and provide credentials.
Default credentials are: username admin | password admin.
Important: In order to change default password you should go to Settings->User Control.

Boards

Adding New Boards

1. Open Board menu (first icon)

2. Click the '+' icon

3. Configure your new board and click 'OK'

4. Click 'SAVE' (bottom right corner)

Deleting Boards

1. Open Board menu (first icon)

2. Click the bin icon on the board you want to delete

3. Confirm

Auto Switch

If at least two boards have 'Auto Switch' option turned on you can automatically switch currently displayed board by setting up 'Switch Interval' for every board and using the Auto Switch menu on the upper right corner.

Endpoints

1. Go into settings

2. Click 'ADD ENDPOINT'

3. Enter your endpoint data

Endpoint Tab Fields:

• Label - any text
• URL - set endpoint url
  • url used to communication Cogboard -> some API e.g. Jenkins
  • it may be available on the internal network only (JSON)
• Public URL - set endpoint public url
  • available everywhere e.g. it allows you to go to the Jenkins Job view when you click on link in widget (HTML)
• Credential - select credential or add new one

Credentials

1. Go into settings

2. Switch tab to 'CREDENTIALS' and click 'ADD CREDENTIAL'

3. Enter your new credentials data. There are two options - login with password (BASIC AUTH tab) or with a token (API TOKEN tab) where token has priority.

4. Login with a token works with Jenkins service.

---

Widgets

All widgets have General tab and some of them have a separate tab with settings specific to the widget

General Tab Fields:

• Type - type of widget f.e AEM Bundle, AEM Healthcheck
• Title - any text
• Columns - set widget width in grid
• Rows - set widget height in grid
• Go to new line - check if widget should be displayed in new line
• Disabled - check if widget should have disabled state

*Expandable Content - option that allows you to display a large amount of content in the form of expandable content. Option is is not available for all widget. Take a look at screens below

AEM Bundle Info

Configuration:

• Endpoint - choose AEM endpoint
• Schedule Period - time interval between executions >> recommended: 300 (5min)
• Error threshold for 'resolved' bundles - how many bundles with status resolved are needed to throw an error instead of warning
• Error threshold for 'installed' bundles - how many bundles with status installed are needed to throw an error instead of warning
• Excluded bundles - list of bundles to be ignored when calculating widget status; can be either display name or symbolic name. Excluded bundles will be put in a separate section, with an option to view them all (including statuses).

Tested on AEM 6.5 & 6.4, should work on all modern/recent-ish versions

AEM Healthcheck

Configuration:

• Endpoint - choose AEM endpoint
• Schedule Period - time interval between executions >> recommended: 300 (5min)
• Health Checks - choose health checks which you would like to show*

* There are other health checks available in AEM. If other checks are desirable they can be added easily by contributing to: cogboard-webapp/src/constants/index.js#AEM_HEALTH_CHECKS constant.

Tested on AEM v.6.5

Bamboo Deployment

Configuration:

• Endpoint - choose configured Bamboo endpoint
• Schedule Period - time interval between executions >> recommended: 300 (5min)
• ID - choose deployment which you would like to show

Where to find ID?

1. Go to <bamboo_host>/deploy/viewAllDeploymentProjects.action

2. Click on deployment from list

3. Project page opens:

   • In URL you will find ID number >> <bamboo_host>/deploy/viewEnvironment.action?id=1234567

Tested on Bamboo v.6.1.1

Bamboo Plan

Configuration:

• Endpoint - choose configured Bamboo endpoint
• Schedule Period - time interval between executions >> recommended: 300 (5min)
• ID - choose plan you would like to show

Where to find ID?

1. Go to <bamboo_host>/allPlans.action
2. Click on plan from list
3. Project page opens:
   • In URL you will find ID number >> <bamboo_host>/browse/CSOI-SDFAPTAS

Tested on Bamboo v.6.1.1

Checkbox

Description:

Widget displays one of three status icons:

• success (green checkmark)
• failure (red cancel icon)
• indeterminate (indeterminate checkbox icon)

Users can toggle widget state by clicking its area.

State can also be updated by sending a POST request to content update endpoint: http://<board_host>/api/widget/contentUpdate for example using curl command in the CLI (first ensure that curl is installed on the machine):

curl -d '{"id": "widget17","content": {"widgetStatus": "CHECKBOX_OK"}}' -H "Content-Type: application/json" -X POST http://<board_host>/api/widget/contentUpdate

The JSON body of the request should follow the example structure:

{
  "id": "widget17",
  "content": {
    "widgetStatus": "CHECKBOX_FAIL"
  }
}

where:

• id - the widget ID that can be copied from widget edit dialog.
  
• widgetStatus - widget status to be set, possible vaues are: CHECKBOX_OK, CHECKBOX_FAIL, CHECKBOX_UNKNOWN

Configuration:

No additional configuration needed

Iframe Embed

Configuration:

• URL - URL of a page that will be embedded as an iframe in a widget
  example: https://www.youtube.com/embed/uBP9K2QJSSs

Jenkins Job

Configuration:

• Endpoint - choose Jenkins endpoint*
• Schedule Period - time interval between executions | recommended: 300 (5min)
• Path - path to the job | example: /job/ProjectName/job/build-name

* example Jenkins Endpoint props:

  {
    id: "endpoint1",
    label: "Jenkins Endpoint",
    url: "http://internal.url or http://ip.address",
    publicUrl: "https://external.url",
    credentials: "credential2"
  }

Tested on Jenkins v.2.46.3

Jira Buckets

Description:

Widget displays the amount of Jira issues in user defined buckets. Buckets of issues can be added, deleted and edited.

Configuration:

• Endpoint - choose Jira endpoint
• Schedule Period - time interval between executions | recommended: 300 (5min)
• Maximum number of issues - limit of the issues pulled from Jira in every bucket
• Bucket Name - name of the user defined bucket
• JQL Query - user defined query that matches the ticket requirements*

*JQL - Jira Query Language documentation

You can also use build-in jira search:

and copy the jql query parameter value from URL

Link List

Description:

Widget displays list of links specified be user. Items can be added, deleted and edited.

Configuration:

• Link Title - any ext
• Link Url - url to external website

Random Picker

Description:

Widget cycle through defined text items in scheduled time intervals. Admin user can force item picking with a refresh button.

Configuration:

• Randomize - By default widget cycle throw items in LIFO order, if this is enabled items are selected randomly
• Daily - If enabled next value will be selected in next day - minute after midnight
• Interval - Interval between cycling items in minutes
• Entries - List of values to be showed

Service Check

Configuration:

• Schedule Period - time interval between executions >> recommended: 300 (5min)
• Request Method - choose request method >> GET | PUT | POST | DELETE
• Endpoint - choose service endpoint
• Path - service url >> example: /login
• Response Body Fragment - response body fragment that is expected for this service
• Expected Status Code - status code that is expected for this service >> default: 200

Presentation

Widget displays:

• Expected status code. If the response status code is different it shows ex. "200 EXPECTED, GOT 404"
• Response status:
  • MATCH - response includes expected response fragment
  • NOT MATCH - response not includes expected response fragment
  • OK - when expected response body remains empty
• Response body message - in a popover after hovering a mouse over response status

SonarQube

Configuration:

• SonarQube Version - 7.x, 6.x or 5.x supported
• Endpoint - choose Jenkins endpoint*
• Schedule Period - time interval between executions | recommended: 300 (5min)
• Key - project key | example: com.cognifide.zg:com.cognifide.zg:stable
• Metrics - choose metrics which you would like to show

Where to find Key and Index?

1. Go to <sonarqube_host>/dashboard/index
2. Click on project from list
3. Project page opens:
   • In URL you will find ID number | <sonarqube_host>/overview?id=316488
   • On a page (upper-right corner) you will find Key

* example SonarQube Endpoint props:

  {
    id: "endpoint2",
    label: "SonarQube Endpoint",
    url: "http://internal.url or http://ip.address",
    publicUrl: "https://external.url",
    user: "user.name",
    password: "pass"
  }

Tested on SonarQube v.5.6.6 | v.6.7.3 | v.7.9.1

Text

Configuration:

• Text - any text (multiple lines allowed)
• Text Size - text sizes from XXS to XXL >> default: M
• Vertical Text - rotate text by 90 degrees >> default: false

ToDo List

Description:

Widget displays list of items specified be user. Items can be added, deleted and edited. You can check the done items.

Configuration:

• Item Title - any text (multiple lines allowed)

White Space

Description:

It creates a blank space between widgets.

Configuration:

No additional configuration needed. This widget is invisible when the user logged out.

World Clock

Description:

Widget displays current time and date of the specific timezone

Configuration:

• Timezone - choose GMT timezone
• Date Format - choose date display format
• Time Format - choose between 12 or 24 hour time format
• Display date - check if date should be displayed
• Display time - check if time should be displayed
• Text Size - choose size of date and time

Zabbix

Description:

Widget is able to show information about: cpu, ram, heap, disk, logged users, uptime and number of processes.

Configuration:

It is mandatory to fill all the fields with proper content to have properly working widget.

• Endpoint - choose Zabbix endpoint -> endpoint URL and Public URL must have /zabbix/api_jsonrpc.php on the end
• Schedule Period - time interval between executions
• Host - provide host name, host name shouldn't be taken from group level. Choose lower level host name - e.g. pre-cog-front-publisher01.dll.dlgpl.net
• Metric - choose which metric should be displayed:
  • Active users
  • Available Memory
  • CPU Utilization
  • Mem heap size
  • Number of processes
  • System uptime
  • Used disk space
  • Used swap space

Next two configuration fields are available only if specific metric will be selected e.g. available memory, disk space etc. This is due to the fact that in some cases the progress bar will be displayed. So we need to specify range and maximum value, which will be used to calculate the percentage value.

• Max Value - provide max value for metric (in GB)
• Range - define the range where the widget will display ok, warning or error status based on the percentage value

Development

Widget development

Frontend

Add new widget file

All available widgets are listed in cogboard-webapp/src/components/widgets/types. Create a new file or copy any existing widget. Remember to keep filename convention - WidgetNameWidget.js. Widget is a React functional component which consumes props from the backend server.

The very basic structure of the widget component looks as follows:

import React from 'react';

import Typography from '@material-ui/core/Typography';

const DefaultWidget = () => {
  return (
    <Typography color="textSecondary" variant="subtitle2">
      Default content
    </Typography>
  );
};

export default DefaultWidget;

Update index

Also, you must update cogboard-webapp/src/components/widgets/index.js and register your new widget.

Example:

const widgetTypes = {
  // Other widgets
  MyWidget: {
    name: 'My Widget',
    component: MyWidget,
    showUpdateTime: true
  }
};

Configuration:

• name - name shown in widget type dialog field
• component - React component used for this widget
• (optional) dialogFields - dialog fields used for widget configuration
• (optional) showUpdateTime - display time of a last widget data update
• (optional) validationConstraints - constraints for dialog fields that prevent inputting incorrect data
• optional custom properties

Create custom dialog fields (optional)

If your widget needs specific data to function correctly, you can create custom dialog fields using which users can input necessary information.

1. Create custom dialog field component in cogboard-webapp/src/components/widgets/dialogFields

2. Register dialog field in cogboard-webapp/src/components/widgets/dialogFields/index.js

   Example:

   const dialogFields = {
     // Other custom dialog fields
     MyField: {
       component: MyField,
       name: 'myField',
       label: 'My Field',
       validator: () => string().required(vm.FIELD_REQUIRED())
     }
   };

   Configuration:

   • name - name under which field will be registered in form data
   • component - React component used for this dialog field
   • label - label shown in widget configuration dialog
   • validator - function which validates inputted data
   • (optional) initialValue - default value for a dialog field
   • optional custom properties

Backend (optional)

When widget just displays fields given in configuration then the backend part is not required.

Add new Widget Class

All available widgets are listed in com.cognifide.cogboard.widget.type package. Create new Kotlin class for new widget. Remember to keep filename convention - WidgetNameWidget.kt. Widget should extend BaseWidget or AsyncWidget. Use AsyncWidget when widget is communicating with 3rd party data source, otherwise - BaseWidget.

Example:

class JenkinsJobWidget(vertx: Vertx, config: JsonObject) : AsyncWidget(vertx, config) {

    private val url: String = config.endpointProp("url")

    // this method will be executed for once or in schedule
    override fun updateState() {
        httpGet(url = "$url/api/json") // send request for JSON to 3rd party
    }

    // handleResponse(...) is executed when httpGet or httpPost finishes and gets data
    override fun handleResponse(responseBody: JsonObject) {
        responseBody.getJsonObject("data")?.let {
            val status = Widget.Status.from(it.getString("result"))

            // at the end use send(...) to notify front-end that widget status has changed
            send(JsonObject()
                    .put(CogboardConstants.PROP_STATUS, status) // new status for widget
                    .put(CogboardConstants.PROP_CONTENT, it)) // new content for widget
        }
    }
}

Update WidgetIndex

Also you must update com.cognifide.cogboard.widget.WidgetIndex and register your new widget.

Debugging

Normal debugging

Uncomment ports in cogboard-local-compose.yml

     ports:
       - "18092:18092"

Uncomment line in Dockerfile

RUN sed -i 's/# JVM_DEBUG=/JVM_DEBUG=/g' /usr/local/knotx/bin/knotx

Startup debugging - use this when debugging start() methods

Uncomment line in Dockerfile

RUN sed -i 's/suspend=n/suspend=y/g' /usr/local/knotx/bin/knotx

IMPORTANT ! - Make sure that CMD [ "knotx", "run-knotx" ] is a last command in Dockerfile

Automated Functional Tests

Running tests

CLI

There are a couple of options. First one is using Gradle:

./gradlew functionalTests - will launch all specs with local environment configuration.

To override environment add -DcypressEnv=envName system property. It will make cypress run with config named envName.json under functional/cypress-tests/cypress/config directory. Make sure it is there.

Spec customization is not currently implemented in gradle wrapper. If you want to run specific tests only, use cypress explictitly:

npx cypress run [--config-file path/to/config.json]¹[--spec path/to/spec.js]² from the functional/cypress-tests directory.

¹ - provide custom config file path. By default it will use functional/cypress-tests/cypress.json

² - provide spec file(s) to be launched. By default all specs are run.

GUI

To open Cypress GUI (i.e. for test aligning or writing new scenarios) run:

npx cypress open in the /functional/cypress-tests directory

---

Known Issues

Concurrent Configuration Issue

Important: There is no mechanism to merge configuration when two admins are making changes to boards and widgets. In order to prevent data lost only one admin should work at one time. When the second admin wants to make changes he needs to make sure that the previous one saved his changes. He should then refresh Cogboard before making his changes.

---

Tips & Tricks

Changing default port

1. Edit cogboard-local-compose.yml

2. In the frontend service change default port from 80:80 to yourNewPort:80 for example 8081:80

3. Redeploy Cogboard

Error while deploying Cogboard container

If You see similar error while deploying Cogboard:

Failed to deploy 'cogboard Image id: cogboard/cogboard-app': com.github.dockerjava.api.exception.InternalServerErrorException: {"message":"error while creating mount source path '/host_mnt/c/Users/user.name/.workspace/cogboard/mnt': mkdir /host_mnt/c: file exists"

If you recently changed your system password.

Try to restart Docker Desktop so it will ask You for system credentials to access local filesystem.

Using a proxy to bypass the firewall

In order to bypass the firewall while installing CogBoard try this instruction: Support for proxy configuration might be needed

---

Stack

• Platform: Docker and Knot.x
• Backend language: Kotlin
• Layout: CSS Grid
• Webapp: React JS
• Webapp UI: Material UI
• Webapp model: Redux
• Automated tests Frontend: Cypress
• Automated tests Mocks: WireMock
• Build with: Gradle