Repository files navigation

ez-Dashing is a customizable free dashboard tool for agile development teams. The project is still indevelopment but already usable for production. I am aware that many things could be improved, feel freeto contribute !

/!\ Huge work still in progress, master is currently broken, only documentation (npm run doc) is available.I am currently doing a huge refactoring and try to create a pure json generic widget :)

Guidelines

• Responsive
• Configurable
• Ready to use

Tech Stack

The online demo shows a running dashboard (release 1.2.0) configured to consume online public API (withoutauthentication). Some API are maybe out of date as the consequence the widgets are loading infinitely.For example, it seems it is not possible to call demo.qotilabs.com without authentitfication anymore, or maybewe should update the dashboard config.

The online demo is temporarily disabled.

The docker demo show a running dashboard (development build) configured to consume a mocked API. This demo is now thesame as the online demo.

docker run --rm -it -p 8081:8081 --name ez-demo ylacaute/ez-dashing:demo

The first screenshots below is exactly what you should see.

Go onhttp://localhost:8081

You can directly start to useez-Dashing by pulling the production docker image. You just have to define yourjson configuration.

docker run --rm -itp 8080:8080 --name ez-dashing -v /ABSOLUTE/PATH/TO/CONFIG/DIR:/ez-config  ylacaute/ez-dashing:1.2.0

Go onhttp://localhost:8080

Please note that your config directory:

• MUST be in absolute path for Docker
• MUST contains 'dashboard.json' (check sample config directory in the project)
• CAN also contains 'application.yml' in order to override Spring Boot config

DEPRECATED

If you need ez-Dashing in production but without Docker, you will have to package it manually.But keep in mind you should have no reason to start server like that, please use Docker for production.

# BUILD FOR PRODUCTION./ez.sh build-prod# START FOR PRODUCTION./ez.sh start-prod<location_directory># More options here./ez.sh -h

The documentation web site can be started with the command below (WIP).

npm run doc

Here are the available docker images:

• ylacaute/ez-Dashing:latest (December 2019)
• ylacaute/ez-Dashing:1.2.0 (December 2019)
• ylacaute/ez-Dashing:demo (December 2019)

New release

This application do not use maven release plugin. The main reason is because no jar are published, but this plugin isnot CI friendly anyway. Since Maven 3 we can use ${revision} in version which bring simplicity. Seethis goodarticle.

Sample to release ez-Dashing version 1.3.0:

# Create the branchgit checkout -b 1.3# Build the app./ez.sh build-prod 1.3.0# Build the docker image./ez.sh create-docker-image 1.3.0# Push the docker image./ez.sh push-docker-image 1.3.0# Git taggit tag -a v1.3.0 -m"Release 1.3.0"

Define adashboard.json configuration file, composed of the sections below:

• env: global variables which can be used anywhere in the configuration
• server: server config, you should have no reason to use that in production
• theme: choose your favorite theme ("default", "black", etc)
• dataSources: refreshable dataSources making REST call and mapping the result to properties
• widgets: your widgets, usually attached to one or many dataSources. See widgets backlog to see available widgets.
• avatars: declare some avatars for your team
• thresholds: define the thresholds values which will impact the CSS rules
• grid: mainly responsive configuration parameters of the grid

You can define a server configuration fileapplication.yml to override SpringBoot configuration. However, this file is not mandatory.

• DataSources are regularly refreshed. When refreshed, REST responses are mapped to properties depending your configuration
• Properties are then injected into the application state
• Widgets are dumb components with properties defined in the configuration and the mapped properties of the dataSources they listen to
• Widgets are re-rendered each time properties change

• User have a total control of REST requests and how data are mapped to the application
• No more REST client dependencies: you build your own
• One dataSource can serve many components (no request duplication)

• ClockWidget (current date)
• BugWidget (Jira)
• SonkinsWidget (Jenkins + Sonar metrics)
• SprintWidget (current sprint status)
• BurndownChartWidget (graphical scrum burndown chart)
• VelocityWidget (team velocity average on last sprints, need to debug)
• ReliabilityWidget (team reliability average on last sprints, need to debug)
• TeamWidget (name and logo)
• TextWidget (editable text, update server config)
• MoodWidget (editable team mood)
• HelloBarChart (example widget)
• HelloPieChart (example widget)
• HelloLineChart (example widget)
• OpenshiftWidget (POD in error in a given env)
• HipTestWidget (test-run report)
• AudioPlayerWidget (WIP, client side ok, todo: shared server folder)
• PullRequestWidget (Gitlab)
• PullRequestWidget (Github)
• MediaWidget (Insert images, videos, sounds)
• jenkinsMonitoringWidget (widget not migrating yet)
• RadioWidget (shared music from server)

• Provide online demo
• Save widget position users can save/reset widget position in the localStorage
• Add a menu a menu allow to control the localStorage user settings
• Dashing theme add a dashing-like theme, even if ugly
• Add Jenkins pipeline build on commit, front + back tests, push docker images
• Release management release 1.0.0 is out !
• Improve WidgetFactory type declaration should be automatic
• Improve unit tests
• Add documentationWIP
• OpenShift pipeline + dedicated podTemplate + deploymentConfig
• Better logging front & back
• Improve Startup break the "startup" state tree
• DataSource Template dataSources should allow variables (not only global)
• Improve RestClient improve error management
• Improve Sonkins Widget sonar metrics should be parameterizable
• Dynamic widget ideally, make pure json configurable widget !

• Node 12
• Java 8
• Maven 3

Most of the time, you will work with front-end only, your best option is then to start a mocked API and start the devserver.

Start the frontend

npm run serve

• Hot reload: works for any kind of front sources change (js, sass, html...)
• HMR: sadly, HMR is still not working. Feel free to create a PR and make it working !!

Start the mocked API (mock the backend)

npm run api

• On mocks change (ez-client/api/mocks): you need to restart the mocked API
• Verify all the chain without mocks: turn off the mocked API and start the back-end

If you just work on the backend, use maven as usual. Please notice that ez-Dashing is now based on Spring-Boot 2.2 whichbring many breaking changes, please read the [Spring Boot 2.2 Release Notes](https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-2.2-Release-Notes) for more information.

Build the back-end

mvn package

Start the back-end

# Inside the ez-server directorymvn spring-boot:run -Dspring-boot.run.profiles=dev# If you want to change the location of the dashboard configmvn spring-boot:run -Dspring-boot.run.profiles=dev -Dspring-boot.run.jvmArguments="-Dspring.config.additional-location=<YOUR_CONFIG_LOCATION>"

If you don't use the dev profile, the spring.config.additional-location become mandatory. Please care about the pathwhich must end with a / otherwise Spring will kick you out.

Start the back-end from IDEA Intellij

• With dev profile: run the classEzDashingApplication with the vm arg -Dspring.profiles.active=dev
• With custom location: run the classEzDashingApplication with the vm arg -Dspring.config.additional-location=<YOUR_DIR>

The production build will generate a Spring Boot application by embedding the frontend inside the final fat jar. Thefrontend build must be triggered by the maven profile "prod". Without this profile, the Spring Application will notcontain the frontend.

# Package the application with the frontendmvn package -P prod# Start the applicationmvn spring-boot:run -Dspring-boot.run.jvmArguments="-Dspring.config.additional-location=<YOUR_CONFIG_LOCATION>"

For frontend development, this project use the AirBnb code style with few changes:

• no spaces on braces for import and object destructuring
• allow empty objects{} in a single line
• try catch: no new line on catch

You can use the.editorconfig or theCodingStyle.xml in this project.

Error: Application does not start

Caused by: java.io.FileNotFoundException: @project.parent.basedir@/config/local/dashboard.json

Solution: You must first run maven to compile and do it again each time you modify the application.yml configbecause maven is in charge to generate some keys, @project.parent.basedir@ in this case.

mvn compile

Error: When building the application, we can see that front logs are marked in ERROR by Maven (even if all testsare passing)

Solution This is not a real buta known Jest bug, Jest writeson stderr instead of stdout, as the result Maven mark them on error.

Error: Error: attribute height: A negative value is not valid.

Solution: Just resize chart widget, when the widget is too small, it can generated negative values.

• Chromium : good (only last version tested)
• Firefox : good (only last version tested)
• Safari : not tested
• Internet Explorer not tested

ez-Dashing is licensed under theApache 2 license.