InfoMonitorManager Documentation

Tuomas Koponen

1 Introduction 1 1.1 Usage examples . . . 1 2 Building blocks 3 2.1 Server. . . 3 2.2 Info monitor . . . 3 2.3 Display . . . 3 2.4 Screen . . . 3 2.5 Screen sequence . . . 4 2.6 Client mode . . . 4 3 Install 5 3.1 Requirements. . . 5

3.2 Choose install method . . . 5

3.3 Install for testing . . . 5

3.4 Install for development. . . 6

3.5 Install for production . . . 7

3.6 Verify Docker Stack . . . 7

3.7 Uninstall . . . 7

3.8 General problems and tips . . . 7

4 Configuration 9 4.1 Basics. . . 9 4.2 Sample config . . . 9 4.3 DisplayConfig . . . 10 4.4 DisplaySource . . . 12 4.5 Helpers . . . 13 4.6 Testing config . . . 14 5 Docker environment 15 5.1 Basics. . . 15

5.2 Hostname and networking . . . 15

5.3 Generating environment . . . 15

5.4 Certificate management . . . 16

5.5 Use HTTPS. . . 16

5.6 Update environment . . . 16

6.2 Whats missing?. . . 17

7 Support 19

Introduction

InfoMonitorManager is a easy to use web based info monitor manager. Have a look at ourdemoto see it in action. It supports multiple different displays and multiple sources for display data. Each display has its own settings and sequence built process.

Displays only requirement is web browser and working network connection. For example Raspberry PI is good option, even some SmartTV’s might work.

InfoMonitorManager has to be installed on a web server, preferable Linux. Easiest way to install is to use our prebuilt Docker stack with install scripts. Our install guide will help you to evaluate system and your first display should be running within minutes.

This product is used in multiple sites and proven pretty fault tolerant and flexible to configure. It even includes PhantomJS service to help you out to make screenshots.

1.1 Usage examples

• Latest tweets from twitter • Statistics for work safety

• Shop floor info about manufacturing status • System statistics from remote monitoring • Business meters from BI-system

Building blocks

InfoMonitorManager is web based application that requires a server for running and info monitor to display slideshow of screens. Each screen should contain one item to show, it can be business metrics, work safety statistics or intranet news.

2.1 Server

Servers responsibility is to prepare data forDisplayand list all available displays. End users does not normally use server directly.

We recommend Linux for InfoMonitorManager server. Any Linux distribution should be fine. You might want to prefer OS that is targeted as Docker host and notice your own requirements for source data compiling. Of course you can use any commercial service providers and cloud service providers.

2.2 Info monitor

Info monitor is presenting a slideshow of screens. It can be pretty much any device that can display a web pages. Maybe cheapest option is just a telly with Raspberry PI. In most cases info monitor should launch selected display right from boot.

2.3 Display

Display is a slideshow ofscreens, and the order of thescreensis determined inScreen sequence. You can have multiple

2.4 Screen

2.5 Screen sequence

Each Display will have its own sequence for displaying screens. Screen sequence can be as complex you like and it is defined in configuration.

2.6 Client mode

Client mode includes controllers for sequence and allows user to pause sequence or select screen he likes to see. Listing also provides details about screen data like source and duration. It is most useful when developing your own displays.

Install

3.1 Requirements

• Docker 18.02.0+install instructions

• We use mac os x for development and Linux for production. Both should work fine. • Some basic docker skills,Get started with Docker

3.2 Choose install method

This is preferable method when you want to test how InfoMonitorManager works. This method will not contain sourcecode and does not suit developing your own Displays that well.

2. Install for development

This is preferable method to configure your own displays. This will contain sourcecode that allows you to use your favorite IDE. Configurations are created with PHP objects and IDE helps you to to typehint correct methods and help you with correct syntax

3. Install for production

This is mainly the same than installing InfoMonitorManager for testing. Main issue is think ahead and know how you work with your environment.

3.3 Install for testing

1. Create directory for installation, any folder you can write will be just fine

2. Make sure Docker swarm is initialized

docker swarm init --advertise-addr <ip_used_for_docker_or_use_127.0.0.1_ ˓→for_default>

3. Download install script

docker run -v $(pwd):$(pwd) -w $(pwd) -i -t bash /usr/local/bin/bash

-˓→c "apk update && apk add ca-certificates openssl &&

update-ca-˓→certificates; wget https://raw.githubusercontent.com/ossbusiness/

˓→infoMonitorManager/master/install_sample.sh; wget https://raw.

˓→githubusercontent.com/ossbusiness/infoMonitorManager/master/install_

˓→sample.md5; if md5sum -s -c install_sample.md5; then chmod u+x install_

˓→sample.sh; else echo printf \"\\\nmd5 sum does not match, installation ˓→failed! \\\n\\\n\"; fi; rm -f install_sample.md5;";

4. Execute installation script. If you have a hostname provide it here. ./install_sample.sh <hostname_or_empty_for_default>

5. Wait for few minutes until all services are up and running.

6. Open URL that was provided by installation script to access InfoMonitorManager.

3.4 Install for development

git clone https://github.com/ossbusiness/infoMonitorManager && cd

˓→infoMonitorManager

2. Make sure Docker swarm is initialized

docker swarm init --advertise-addr <ip_used_for_docker_or_use_127.0.0.1_ ˓→for_default>

3. Generate local enviroment configuration

./docker_generate_enviroment_config.sh <hostname_or_empty_for_default>

4. Copy composer devel yaml

cp docker-compose-dev.yml docker-compose-local.yml

5. Start Docker stack with script provided, it will merge docker config required for development. ./stack_deploy.sh

6. Wait for few minutes until all services are up and running.

7. Open URL that was provided by installation script to access DemoDisplay.

If you hesitate to go live you can always ask somesupportfrom us.

3.6 Verify Docker Stack

InfoMonitorManager does contain four services. As a default there should be one replica for each service running. You get status of your stack by running.

docker stack services infoMonitorManager

ID NAME MODE REPLICAS

˓→ IMAGE PORTS

23pek4msxk0s infoMonitorManager_visualizer replicated 1/1

˓→ dockersamples/visualizer:stable *:8080->8080/tcp

6r6zca9s2voi infoMonitorManager_phantom replicated 1/1

˓→ ossbusiness/info_monitor_manager_phantom:latest *:8910->8910/tcp

lwydo5e8gudc infoMonitorManager_app replicated 1/1

˓→ ossbusiness/info_monitor_manager_app:latest

orhwhqmmoyva infoMonitorManager_web replicated 1/1

˓→ ossbusiness/info_monitor_manager_web:latest _{*:80->80/tcp, *:443->443/tcp}

s08sh78as0mu infoMonitorManager_sphinx replicated 1/1

˓→ ossbusiness/info_monitor_manager_sphinx:latest

If there is any problems with any of the services you will se 0/1 replicas. In some cases replica count can keep changing 0/1 to 1/1, this means service keeps rebooting.

3.7 Uninstall

To uninstall InfoMonitorManager first remove docker stack. docker stack rm infoMonitorManager

Make sure there is no services running. You should getNothing found in stack: infoMonitorManager

docker stack services infoMonitorManager

Note: You can not have two different installation methods running at the same time. Uninstall InfoMonitorManager before changing install method.

You can also remove all files in your installation folder.

3.8 General problems and tips

• SELinux does give you a headache and permission denied problems • Make sure ports 80 and 443 are free and available for Docker • Make sure that ports 80 and 443 are not reserved

• If you are experiencing some network etc issues try to restart docker • Inspect docker container logs to see any problems with running service

• If you use preCompileScripts to write data make sure Docker is allowed to write to your folders

Configuration

4.1 Basics

• Display configurations are located at displays/configs • Display presents screens by generated sequence • Each display can contain multiple sources for screens • Configuration is made of PHP Objects

• All files within a config are relative to displays folder

• When developing displays useInstall for developmentmethod • Useclient modewhen developing displays

4.2 Sample config

Here is quick sample about what config could look like. It is using three different sources and PreCompileScript to generate cat pictures. Every display will start with our two most important screens and then we just have 2 cat pictures and one external stats screen for three rounds. This would make total 11 screens.

<?php

use App\Display\DisplayConfig; use App\Display\DisplaySource;

use Displays\scripts\generateCatPictures;

return (new DisplayConfig()) ->setName('DemoDisplay') ->setBlade('layouts/basic')

->addStylesheet('style/default.css')

(continued from previous page) ->setPreCompileScript(generateCatPictures::class) ->addSource( (new DisplaySource('importantSources')) ->setName('Important screens') ->addSourceFile('html/screen1.html') ->addSourceFile('html/screen2.html') ->setMaxCount(2) ) ->addSource( (new DisplaySource('catPictures')) ->setName('Cat pictures!') ->setDurationSec(10) ->addSourceFolder('catPictures') ) ->addSource( (new DisplaySource('externalSources')) ->setName('External source') ->addUrl('https://my.external.source.com') ->setMaxCount(5) ->setDurationSec(20) ) ->setSequence( " _arr.push({ source: 'importantSources', }); for (i = 0; i < 3; i++) { _arr.push({ source: 'catPictures', options: { maxCount: 2, } }); _arr.push({ source: 'externalSources', options: { maxCount: 1, } }); }" );

4.3 DisplayConfig

Each config file must return a new DisplayConfig object. This will create one display you can use on info monitors.

4.3.1 new DisplayConfig()

Name for your display. Make it read what it means. setName('Cat pictures of the day')

4.3.3 setBlade( $blade )

Blade template to be used for your display. setBlade('templates/basicLayout')

4.3.4 addStylesheet( $stylesheet )

Custom stylesheet used for this display. You can define multiple stylesheets. addStylesheet('css/style.css')

4.3.5 addSource( $displaySource )

New source object for display. This contain actual screens that will be presented. You can add multiple sources.

addSource((new `DisplaySource`_('sourceKey')) ...

)

4.3.6 setPreCompileScript( $className )

Script class name, with namespace, that will be used to compile data for this display. setPreCompileScript(Displays\scripts\generateCatPictures::class)

Here is sample of PreCompileScript that is triggered each time beforeDisplaySourceare compiled. Our systems is built onLumenso there is quite nice tools built in. System has PHP 7.2 installed with basic extensions. Only thing you have to remeber is to implementPreCompileScriptInterface, use Display-CompileScriptHelperTraitand have method called run. You can get as complex as you like.

4.3.7 setGaCode( $blade )

Set Google analytics code for your display. Default can be added to .env file setGaCode('UA-12345678-1')

4.3.8 setSequence( $javascript )

Javascript that will generate your display screen sequence.

Your javascript has to push instructions to _arr -variable. First sources are sorted and then maxCount of screens are moved from source to sequence. Here you can overwrite default fromDisplaySource. As a tip, you can use for loop to pick few screen from each source. This will allow you to make sequence feel a bit more natural.

for (i = 0; i < 3; i++) { _arr.push({ source: '<nameOfSource>', options: { maxCount: integer, durationSec: integer, sort: random|timestampDesc|timestampAsc } }); _arr.push({ source: '<nameOfAnotherSource>', options: { maxCount: integer, durationSec: integer, sort: random|timestampDesc|timestampAsc } }); }

4.3.9 Display layout

This is bare minimum layout blade template. If you modify, just make sure you are extending masterlayout that brings in all required dependencies and boots up InfoMonitorManager.

@extends('masterlayout') @section('content')

<div id="headerBar"></div>

<div id="displayContainer"></div> <div id="footerBar"></div>

@endsection

4.3.10 Using WebDriver

Our stack includes Facebook’sWebDriver. This allows you to manipulate web pages and take screenshots. One use case for example is to login to custom system and have a screenshot from a report or listing. There is more info on WebDriver’s GitHub page.

4.4 DisplaySource

Display source defines actual data that will presented on screen. You can have multiple sources per display and you can use them to help you sort your sequence.

4.4.2 addSourceFolder( $folderName, $filter=null )

Add all files from directory to display. You can apply filter as a second argument. addSourceFolder('screens', 'catImages*.html')

4.4.3 addUrl( $url )

You can fetch data from external sources, just provide full URL that returns proper JSON. addSourceFile('htts://my.data.source')

[ {

html: '<div>some html</div>'

description: 'Some info about our source' timestamp: Unix timestamp

}, {

html: '<div>some more html</div>'

description: 'Some info about our source' timestamp: Unix timestamp

} ]

Note: You can also set default values setDurationSec, setMaxCount and setSort. These can be overwritten at setSe-quence( $javascript ).

4.4.4 Display screen

This is actual data that will be displayed inside layouts ‘displayContainer’ -div. This is plain HTML and no blade templating is used in here. You can usesetPreCompileScript( $className )to generate Display screens.

<h2>Welcome!</h2>

<p>We will present you perfect set of cat pictures. Please keep looking at the

˓→monitor.</p>

4.5 Helpers

4.5.1 InlineImage( $filename )

Some cases it makes sense to add images as inline. This avoids problem with network connectivity issues and images does not have to be published. It has it downside and might not always be the option. \App\Display\DisplayRepository::InlineImage('images/OSS_logo.png')

4.5.2 saveScreenshotToTmp($driver, $imageName)

WebDriver includes tools to take a screenshot. This is just a wrapper for save image to /tmp/ so it is easier to be used with InlineImage.

This returns full path and filename.

use App\Display\DisplayCompileScriptHelperTrait; ...

$driver = RemoteWebDriver::create($host, DesiredCapabilities::chrome()); ...

$imageName = 'MyScreenShot';

$screenCapture = self::saveScreenshotToTmp($driver, $imageName);

4.6 Testing config

To test you configuration is ok you can run compile script manually.

docker exec -it $(docker ps -f "name=app" -q) php artisan display:compile <display_ ˓→name>

docker exec -it $(docker ps -f "name=app" -q) php artisan display:compile --all

Docker environment

5.1 Basics

Our Docker configuration is located under docker folder and environment configuration is located under environment folder. All changes to your environment should be done files under environment folder.

Remember that this is just a general documentation that should get you going easily. For more advanced Dockering please refer Docker documentation.

Note: All images are prebuilt with codebase and for running InfoMonitorManager you will not need to clone whole repository.

5.2 Hostname and networking

You should always use FQDN as a hostname when possible. Only ports 80 and 443 needs to be open to public. Certificates will be generated to given hostname and browser might fail to connect if you use HTTPS.

5.3 Generating environment

Installation scripts will generate you a basic system. If you need to recreate your environment just remove parts of environment folder or whole environment folder and run generator script again.

./docker_generate_enviroment_config.sh <hostname_or_empty_for_default>

5.4 Certificate management

All certificates are located underenvironment/nginx/certs/. Environment generator will generate self signed certificates that can be used for testing purpose.

If you use real certificates you will not need Root CA. Only provide properenvironment/nginx/certs/site.crtand envi-ronment/nginx/certs/site.keythis will void certificate generation.

If you do have own trusted Root CA you save it asenvironment/nginx/certs/root-ca/root-ca.keyand it will be used when host key will be generated.

Note: To avoid problems default connection is HTTP and no certificates are used.Use HTTPSwill help to use secure connection.

5.5 Use HTTPS

For ease of usage HTTP is used as a default. If you want to start using secure connection there is config ready for you. Just renameenvironment/nginx/webserver.conf withenvironment/nginx/webserver_for_HTTPS.conf andUpdate environment

5.6 Update environment

To make sure all your changes will take effect it is easiest to recreate whole stack. docker stack rm infoMonitorManager

Make sure there is no services running.

docker stack services infoMonitorManager

Depoloy stack

./stack_deploy.sh

Note: If you get errors when you run./stack_deploy.shmost likely some of the services are still not removed. Wait a minute and try again.

5.7 Certbot

If you want to automate certification management you might want to setupCertbotfor certification management. As our system is mainly running internally, this is not provided. Please feel free to contribute, it should not be too difficult to implement.

Contribute

6.1 Github

Code is shared atGitHub. Don’t be shy to open an issue or just send us a pull request.

6.2 Whats missing?

Support

This is an Open Source project and development is done by our own or clients request. Source code is onGitHub. From there you can post an issue and we will check it when we can. If you have a Pull Request we are more than a happy to review that.

If you found InfoMonitorManger useful and need some help to get started, you can alsocontact usand see if we can help you.