Getting Started

The easiest way to get started is to run Nivio using Docker. To compile it, you need Java 11.

The Docker image is about 350MB and can be started with:

docker run dedica/nivio

Demo mode

docker run -e DEMO=1 dedica/nivio

In the demo mode Nivio loads sample data for demonstration purposes.

There is a demo in the directory ./nivio-demo/ which starts nginx to serve all example configs from the project and starts Nivio as Docker container.

From this directory run

docker-compose up

then point your browser to http://localhost:8080.

Adding your own content (seed config)

Make sure to read Using Templates to dynamically assign data before putting too much effort into item configuration.

Nivio expects a seed configuration at start time (unless you want to run the demo mode). You need to set the environment variable SEED. If you want to use files on the host, modify the docker-compose.yml to bind to the corresponding folder, e.g:

version: '3.2'

services:
  nivio:
    image: dedica/nivio:latest
    environment:
      SEED: ${SEED}
      DEMO: ${DEMO}
    volumes:
      - type: bind
        source: /onmyhost/my/files/here
        target: /my/files/here
    ports:
      - 8080:8080

Then you can point to a specific file with the SEED environment variable:

SEED=/my/files/here/file.yml docker-compose up

Or you provide a URL that serves the yml files to Nivio:

SEED=https://foo.com/bar.yml java -jar nivio

then point your browser to the GUI at http://localhost:8080 or the API at http://localhost:8080/api/.

Environment variables

The following environment variables can be set to configure nivio:

DEMO

A non-empty value causes Nivio to start in demo mode with prepared data. Use the value ‘all’ to load more landscapes.

GITHUB_JWT

GitHub JSON Web Token (JWT) to connect to GitHub as a GitHub App.

GITHUB_LOGIN

GitHub user name. Can also be used to connect as organization with OAuth.

GITHUB_OAUTH

GitHUb OAuth Token to connect to GitHub via personal access token.

GITHUB_PASSWORD

GitHub password (for username/password login).

GITLAB_HOST_URL

The full URL to the GitLab API, e.g. http://your.gitlab.server.com/api/v4.

GITLAB_PASSWORD

GitLab OAuth login password (optional).

GITLAB_PERSONAL_ACCESS_TOKEN

Personal token to access the GitLab API at GITLAB_HOST_URL (optional).

GITLAB_USERNAME

GitLab OAuth login username (optional). If used, GITLAB_PASSWORD is also required).

KUBERNETES_MASTER

K8s master URL (optional). All variables from https://github.com/fabric8io/kubernetes-client#configuring-the-client can be used.

NIVIO_BASE_URL

The base URL of Nivio to be used for frontends if running behind a proxy.

NIVIO_BRANDING_BACKGROUND

Branding background color (hexadecimal only).

NIVIO_BRANDING_FOREGROUND

Branding foreground color (hexadecimal only).

NIVIO_BRANDING_LOGO_URL

A URL pointing to a logo.

NIVIO_BRANDING_MESSAGE

A welcome message on the front page.

NIVIO_BRANDING_SECONDARY

Accent color used for active elements (hexadecimal only).

NIVIO_MAIL_HOST

SMTP mail host.

NIVIO_MAIL_PASSWORD

SMTP mail password.

NIVIO_MAIL_PORT

SMTP mail port.

NIVIO_MAIL_USERNAME

SMTP mail username.

PORT

The port Nivio runs on.

SEED

A semicolon-separated list of file paths containing landscape configurations.

SONAR_LOGIN

SonarQube login (username).

SONAR_PASSWORD

SonarQube password.

SONAR_PROXY_HOST

SonarQube proxy host (optional).

SONAR_PROXY_PORT

SonarQube proxy port (optional).

SONAR_SERVER_URL

SonarQube server URL.

Landscape configuration

The configuration file contains basic data, references to item descriptions sources, which can be local paths or URLs. The descriptions can be gathered by HTTP, i.e. it is possible to fetch files from protected sources via authentication headers. Think of GitLab or GitHub and the related tokens.

You can also add state providers which are used to gather live data and thereby provide state for the items.

To finetune the visual appearance of rendered landscapes, the automatic color choice for groups can be overridden as well.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
 identifier: nivio:example
 name: Landscape example
 contact: mail@acme.org
 description: This is an example landscape.
 sources:
   - "./items/wordpress.yml"
   - url: "./items/dashboard.yml"
     format: nivio
   - url: "http://some.server/docker-compose.yml"
     format: docker-compose-v2
   - url: https://gitlab.com/bonndan/nivio-private-demo/raw/docker-compose.yml
     headerTokenName: PRIVATE_TOKEN
     headerTokenValue: ${MY_SECRET_TOKEN_ENV_VAR}
   - url: xxx
     format: kubernetes

 config:
   groups:
     content:
       color: "24a0ed"

Deleting items

Items not referenced anymore in the descriptions will be deleted automatically on a complete and successful re-index run. If an error occurs fetching the source while indexing, the behaviour of the indexer changes to treat the available data as partial input. This means only upserts will happen and no deletion.

Behind a proxy

If you deploy Nivio to run under a different path than root (/), make sure to set the environment variables SERVER_SERVLET_CONTEXT_PATH and NIVIO_BASE_URL to the path.

SERVER_SERVLET_CONTEXT_PATH: /my-landscape
NIVIO_BASE_URL: https://foo.com/my-landscape/