Skip to content
Szymon Owczarzak edited this page Oct 21, 2020 · 183 revisions

Getting started

Prerequisites

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

  2. Install docker:

Additional steps for Windows:

  • Make sure that Hyper-V is enabled
    windows enable hyper v
  • Log-in to Docker Desktop in Windows tray
  • Check Expose daemon on... property
    docker expose daemon
  • Share drive where cogboard was cloned
    docker expose daemon
  • Disable Cloud Experience
    docker disable cloud experience

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

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)

Adding New Board

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

Adding New Endpoint

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.

Changing Credentials


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

Sonarcube Sonarcube v5

AEM Bundle Info

Aemn Bundle Widget

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

Aemn Bundle Dialog

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

AEM Healthcheck

AEM Healthcheck Widget

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.

AEM Healthcheck Dialog

Tested on AEM v.6.5

Bamboo Deployment

Bamboo Deploy Widget

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

Bamboo Deploy Dialog

Tested on Bamboo v.6.1.1

Bamboo Plan

Bamboo Plan Widget

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

Bamboo Plan Dialog

Tested on Bamboo v.6.1.1

Checkbox

Checkbox Widget

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.
    copy widget id
  • widgetStatus - widget status to be set, possible vaues are: CHECKBOX_OK, CHECKBOX_FAIL, CHECKBOX_UNKNOWN

Configuration:

No additional configuration needed

Iframe Embed

Iframe Widget

Configuration:

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

Iframe Dialog

Jenkins Job

Jenkins Widget

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"
  }

Jenkins Dialog

Tested on Jenkins v.2.46.3

Jira Buckets

Jira Buckets Widget

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

Jira Buckets Dialog

You can also use build-in jira search:

jira search

and copy the jql query parameter value from URL

jql query

Link List

Link List Widget

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

Link List Dialog

Random Picker

Random Picker Widget

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

Random Picker Dialog

Service Check

Service Check Widget

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

Service Check Dialog

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

Sonarcube v7 Widget Sonarcube v7 Expanded

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"
  }

Sonarcube Dialog

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

Text

Text Widget

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

Text Dialog

ToDo List

ToDo List Widget

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)

ToDo List Dialog

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

World Clock Widget

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

World Clock Dialog

Zabbix

Zabbix WidgetZabbix WidgetZabbix Widget

Description:

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

Configuration:

  • Endpoint - choose Zabbix endpoint
  • Schedule Period - time interval between executions
  • Host - provide host name e.g. pre-cog-front-publisher01.dll.dlgpl.net
  • Metric - choose which metric should be displayed

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

Zabbix Dialog

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]1[--spec path/to/spec.js]2 from the functional/cypress-tests directory.

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

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