-
Notifications
You must be signed in to change notification settings - Fork 9
Home
-
Make sure that some Java JDK is installed (tested on AdoptOpenJDK 8)
-
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!
Note: Docker instalation will be available from version 1.0.0.
Note: For development installation go here.
-
Download
cogboard-1.0.0.zip
from latest release. -
Extract
cogboard-1.0.0.zip
-
Optional: Execute the command below if this is the first time use of docker on a machine.
docker swarm init
- Deploy CogBoard Stack
docker stack deploy -c cogboard-compose.yml cogboard
To uninstall stack use: docker stack rm cogboard
command.
Use this approach when developing new features for CogBoard.
- Clone Cogboard repository
git clone https://github.com/Cognifide/cogboard.git
- 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.
Note: Only the latest version is supported by updates.
- Uninstall old version
docker stack rm cogboard-local
or
./gradlew undeployLocal
- Follow installation guide.
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.
Copy config files mentioned in Backup section to mnt
folder of new instance of Cogboard.
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
.
-
Open Board menu (first icon)
-
Click the '+' icon
-
Configure your new board and click 'OK'
-
Click 'SAVE' (bottom right corner)
-
Open Board menu (first icon)
-
Click the bin icon on the board you want to delete
-
Confirm
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.
-
Go into settings
-
Click 'ADD ENDPOINT'
-
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
-
Go into settings
-
Switch tab to 'CREDENTIALS' and click 'ADD CREDENTIAL'
-
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.
-
Login with a token works with next services:
Jenkins
,SonarQube
.
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
-
Endpoint
- choose AEM endpoint -
Schedule Period
- time interval between executions >> recommended:300
(5min) -
Error threshold for 'resolved' bundles
- how many bundles with statusresolved
are needed to throw an error instead of warning -
Error threshold for 'installed' bundles
- how many bundles with statusinstalled
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).
-
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.
-
Endpoint
- choose configured Bamboo endpoint -
Schedule Period
- time interval between executions >> recommended:300
(5min) -
ID
- choose deployment which you would like to show
-
Go to
<bamboo_host>/deploy/viewAllDeploymentProjects.action
-
Click on deployment from list
-
Project page opens:
- In URL you will find
ID
number >> <bamboo_host>/deploy/viewEnvironment.action?id=1234567
- In URL you will find
-
Endpoint
- choose configured Bamboo endpoint -
Schedule Period
- time interval between executions >> recommended:300
(5min) -
ID
- choose plan you would like to show
- Go to
<bamboo_host>/allPlans.action
- Click on plan from list
- Project page opens:
- In URL you will find
ID
number >> <bamboo_host>/browse/CSOI-SDFAPTAS
- In URL you will find
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
No additional configuration needed
-
URL
- URL of a page that will be embedded as an iframe in a widget
example:https://www.youtube.com/embed/uBP9K2QJSSs
-
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
Widget displays the amount of Jira issues in user defined buckets. Buckets of issues can be added, deleted and edited.
-
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
Widget displays list of links specified be user. Items can be added, deleted and edited.
-
Link Title
- any ext -
Link Url
- url to external website
Widget cycle through defined text items in scheduled time intervals. Admin user can force item picking with a refresh button.
-
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
-
Schedule Period
- time interval between executions >> recommended:300
(5min) -
Request Method
- choose request method >>GET | PUT | POST | DELETE
-
Content Type
- choose header content type >>application/json | application/xml | multipart/form-data | text/html | text/plain
-
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
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 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
- Go to
<sonarqube_host>/dashboard/index
- Click on project from list
- 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
- In URL you will find
*
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",
token: "token"
}
- user should fill one of two login options:
password
ortoken
field
-
Text
- any text (multiple lines allowed) -
Text Size
- text sizes fromXXS
toXXL
>> default:M
-
Vertical Text
- rotate text by 90 degrees >> default:false
Widget displays list of items specified be user. Items can be added, deleted and edited. You can check the done items.
-
Item Title
- any text (multiple lines allowed)
It creates a blank space between widgets.
No additional configuration needed. This widget is invisible when the user logged out.
Widget displays current time and date of the specific timezone
-
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
Widget is able to show information about: cpu, ram, heap, disk, logged users, uptime and number of processes.
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
Note: Repository admins only
- Make sure that correct version is set on
master
branch (it should match the version in release draft) - Turn off
master
branch protectionSetting -> Branches -> Branch protection rules
- Open release draft, check if the text needs updates, look for typos - make it look great
- Make sure that tag field has this format: v[version number], example
v1.0.4
- Make sure that release title has this format: [version number], example
1.0.4
- Click
Publish Release
button - Go to the
Actions
tab and check if release sucseeded -
IMPORTANT Turn on
master
branch protection again
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.
-
Edit
cogboard-local-compose.yml
-
In the
frontend
service change defaultport
from80:80
toyourNewPort:80
for example8081:80
-
Redeploy Cogboard
Admin can exclude widgets by adding widget names into /mnt/app-config.json
file in excludedWidgets
array.
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.
In order to bypass the firewall while installing CogBoard try this instruction: Support for proxy configuration might be needed