Skip to content

On-premises Install guide

In this guide, you will learn how to install the Serenytics data-platform on your own servers.

This guide only explains how to install Serenytics on a single machine. For multi-machines architecture, please contact our support.

The Serenytics data platform is composed of several services provided as Docker images. Installing Serenytics on a machine means downloading these images, defining a configuration and starting all the images.

Prerequisites

  • You need a server with an Ubuntu 18.04 LTS - 64 bits OS (similar Linux distributions should work).
  • You need an admin (sudo) account on this machine.
  • The recommended machine is highly related to your Serenytics needs. As a minimum, we recommend a quad-core machine, with CPU frequency above 3GHz, 16Gb of RAM and 100Gb of disk.
  • You need to have obtained a dedicated DockerHub login/password from Serenytics to be able to download the Serenytics images. These identifiers are to be kept secret.
  • If you want to enable SSL (strongly encouraged), you also need a private key and an SSL certificate. If you don't have it, the instructions below will guide through the setup of a default self-signed certificate. If you don't enable the SSL, your passwords and data won't be encrypted. That's only acceptable if you use test data or work in a strictly controlled environment and know precisely what you are doing.

Step 1: Download the Serenytics CLI

The install is done through the Serenytics CLI (Command Line Interface).

The first step is to download this CLI on your machine:

curl -L "https://s3-us-west-2.amazonaws.com/assets.serenytics.com/install/serenytics_onpremises_cli.py" -o serenytics_onpremises_cli.py && chmod u+x serenytics_onpremises_cli.py

This step downloads the file serenytics_onpremises_cli.py which is our CLI. This CLI has commands to install Serenytics, but also to restart it and a few other ones used to administrate the platform.

Step 2: Download the config files

Before launching the install, you also need to download the default configuration file.

For non SSL install

Run the command below to download the serenytics.yml file (that's the docker configuration as a docker-compose file).

curl -L "https://s3-us-west-2.amazonaws.com/assets.serenytics.com/install/serenytics.yml" -o serenytics.yml

For SSL install

SSL - step 2.a

Run the command below to download the serenytics.yml file (that's the docker configuration as a docker-compose file with SSL enabled).

curl -L "https://s3-us-west-2.amazonaws.com/assets.serenytics.com/install/serenytics-with-ssl.yml" -o serenytics.yml

SSL - step 2.b

You also need to download a specific config file to configure the Serenytics web server and proxy (using Nginx) with SSL:

curl -L "https://s3-us-west-2.amazonaws.com/assets.serenytics.com/install/nginx-custom.conf" -o nginx-custom.conf

This file customizes NGinx to enable SSL. If your a web administrator, you can later open and check the configuration.

SSL - step 2.c

You need to drop your certificate file and your private key in a folder (you can specify this folder later to Serenytics).

If you do not have it, run:

sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout /etc/ssl/private/nginx-selfsigned.key -out /etc/ssl/certs/nginx-selfsigned.crt

This will create a private key and a certificate in the default folder /etc/ssl.

Step 3: Run the installation

Run the command ./serenytics_onpremises_cli.py install

The CLI will ask you a few questions. Your answers will be stored in a .env file. During the setup, you can skip answers and modify this .env file later.

The install will have the following steps:

  1. It installs Docker on the machine (if not already installed).
  2. It asks for the credentials you obtained from Serenytics to get the Serenytics images.
  3. It asks for the dedicated version name to install (leave empty in most cases)
  4. It asks for the version number to install (asks the Serenytics support if you're not sure). Current default version is 4717.
  5. It asks for the IP of the machine. In Serenytics, the frontend (in the browser) calls the Serenytics API provided by the backend. This IP will be used in the frontend to query the API. You can provide an URL (e.g. serenytics.mydomain.com) or an IP.
  6. It asks for the PostGreSQL database password (for the db storing the Serenytics objects such as dashboards, datasources, automations...).
  7. It asks for the datawarehouse password (by default a local PostGreSQL database).
  8. It asks for a secret (used to generate authentication tokens). You can enter any text of your choice.
  9. It asks for SMTP settings (required if you want the platform to be able to send emails). Remember that you can edit any setting later.
  10. It asks for a Mapbox key. Such a key is mandatory to show maps background (obtained from Mapbox).

Then, the CLI will download the docker images and run it. This can take a few minutes.

If you need to edit the .env file manually, you need to restart the Serenytics platform with ./serenytics_onpremises_cli.py start once you have saved your modifications.

SSL - specify the folder for your certificate and private key

In the .env file, you need to define :

  • SSL_PEM_PATH: the path to your certificate file
  • SSL_PRIVATE_KEY_PATH: the path to your private key

And add these three lines into your .env file:

SSL_PEM_PATH=/etc/ssl/certs/nginx-selfsigned.crt SSL_PRIVATE_KEY_PATH=/etc/ssl/private/nginx-selfsigned.key IP_ADDRESS=YOUR_IP_OR_DOMAIN

You need to replace YOUR_IP_OR_DOMAIN by either the server IP or URL (without the http part, e.g. serenytics.mydomain.com).

Once you have configured these options, restart the Serenytics platform with:

./serenytics_onpremises_cli.py start

Step 4: Firewall configuration

By default, everything must be closed on your server (except ssh access to administrate it).

For a non SSL install

You need to open the following ports from the outside world to this machine:

  • port 80: Serenytics embeds a web server running on this port. To enable a user to get the Serenytics frontEnd in its browser, this port must be open.
  • port 4000: This port is used by the Serenytics backend to provide the API. To enable the Serenytics frontend app to query the API, this port must be open.

For an SSL install

You need to open the following ports from the outside to this machine:

  • port 80: In SSL mode, queries to this port will be redirected to https on port 443.
  • port 443: In an SSL install, all http queries are run to this port. The Nginx then redirects the queries either to the frontEnd web server or to the backend server (if this is an API query).

In an SSL install, do not open the port 4000

If you open the port 4000, the api will be callable without SSL and that would be a security breach.

Step 5: Test your installation

Open the page http://machine_IP, http://my_url (with https if you activated SSL). You should see the Serenytics login page.

Limitation of self-signed certificates

If you used a self-signed certificate, your browser will certainly refuse to open this page. You need to accept the certificate (the steps to do that depends on your OS and browsers, this is beyond the goal of this guide). For the same security reasons, some Serenytics features won't work. Those are the features that request our backend to call our API. For example, generating a PDF file from a dashboard will not work with a self-signed certificate.

Click on create account to create your first account.

Then follow these 3 steps:

  • As a very first installation test, create a new datasource (using an XLS file). The preview must display its content.
  • Then create a dashboard with a first widget using this datasource.
  • Then, create an automation of type Python script. Run it. It should display "Hello world" in its output.
  • Then, create an automation of type 'Send dashbaord as PDF'. Choose the dashboard you just created, enter your email and execute it. You should receive the corresponding PDF in your inbox a few minutes later (this only works if you have configured an SMTP server and you are not using a self-signed certificate).

Troubleshooting

The CLI command ./serenytics_onpremises_cli.py status checks that all the services are running.

If you run a docker ps, you should see all the Serenytics containers running. You can run a docker logs --follow CONTAINER_ID to see a container's output.

If you have access to the frontend, open the browser console and if all the calls to the Serenytics API are failing, this means the firewall is blocking the API.