Home

Getting started

Prerequisites

1. Required JDK - the project is now using Gradle Java Toolchains so it should download compatible JDK for you.
   If it fails you may use 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.

---

Realese process

Note: Repository admins only

1. Make sure that correct version is set on master branch (it should match the version in release draft)
2. Turn off master branch protection Setting -> Branches -> Branch protection rules
3. Open release draft, check if the text needs updates, look for typos - make it look great
4. Make sure that tag field has this format: v[version number], example v1.0.4
5. Make sure that release title has this format: [version number], example 1.0.4
6. Click Publish Release button
7. Go to the Actions tab and check if release sucseeded
8. IMPORTANT Turn on master branch protection again

---

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

Excluding Widgets

Admin can exclude widgets by adding widget names into /mnt/app-config.json file in excludedWidgets array.

Error while deploying Cogboard container

If You see a 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.

Unable to open cypress test

Error: Failed to deserialize the V8 snapshot blob. This can mean that the snapshot blob file is corrupted or missing.
Solution: Use npx cypress install --force command from cogboard\functional\cypress-tests\cypress folder

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