Central installation

Requirements to run Central

Central requires Postgres database and Prometheus to be running. All tables needed are created by application itself. All arguments for application are set via environment variables.

  • JWT_SECRET - (required) secret phrase used for JWT token
  • POSTGRES_URL - (required) postgres's connection string
  • PASSWORD_RESET_SECRET - (required) secret phrase for password reset token
  • PROMETHEUS_URL - (required) URL of Prometheus for metric's data
  • ADMIN_USERNAME, ADMIN_PASSWORD - are used to set first user login username and password, if not set will be randomly generated, ADMIN_USERNAME must be valid e-mail address
  • EMAIL_USERNAME, EMAIL_PASSWORD, EMAIL_SERVER, EMAIL_PORT - used to authorize and send email, user will be used as a sender aswell
  • DEPLOYMENT_URL - URL of where Central is deployed, used to construct reset link with token

Postgres setup

Steps to set up PostgreSQL can be found in Orchesto installation guide or below. Central requires it's own database where it connects to and creates required tables automatically on launch. Central needs to be provided with correct connection string via environment variable POSTGRES_URL, for example postgres://user:password@localhost:5432/central-db?sslmode=disable.

The connection string syntax is: postgres://username:password@host:port/database-name?sslmode=disable

If you have set up PostgreSQL for Orchesto, you can create new database with command:

CREATE DATABASE "central-db" ;

If you are already running PosgresSQL container:

  1. login into postgreSQL container: docker exec -it <container name> psql -h localhost -U <user name> -d postgres
  2. create database
    CREATE DATABASE "central-db";
  3. quit with command \q

Run PostgreSQL via Docker

  1. Create persistent volume for data:
    sudo docker volume create postgres-data

  2. Run docker image
    sudo docker run --name central-postgres -e POSTGRES_USER=user -e POSTGRES_PASSWORD=password -e POSTGRES_DB=central-db -v postgres-data:/var/lib/postgresql/data -d -p 5433:5432 postgres

    IMPORTANT:

    If your port 5433 is already in use, use some other free port. ie change -p 5433:5432 to -p yourChosenPortNumber:5432 and also change it in connection string.

    Flags explanation

    • -e POSTGRES_USER=user PostgreSQL creates new user user
    • -e POSTGRES_PASSWORD=password sets the password for user user to be password
    • -e POSTGRES_DB=central-db PostgreSQL automatically creates database with name central-db
    • -p 5433:5432 makes PosgreSQL accessible at port 5433 and maps it to port 5432 inside Docker container
    • -v postgres-data:/var/lib/postgresql/data mounts persistent volume postgres-data to a folder /var/lib/postgresql/data where PostgreSQL stores its data in the container

    With the docker run command above the connection string to the PostgreSQL would be: postgres://user:password@localhost:5433/central-db?sslmode=disable

  3. You can stop central-postgres container with CTRL + C (CONTROL + C for OS X) and start it again with sudo docker start central-postgres

Prometheus setup

First create Prometheus configuration file (prometheus.yml) with content:

global:
 scrape_interval:     10s
 evaluation_interval: 10s

Prometheus can be run locally via Docker. First create data volume:

sudo docker volume create prometheus-data

And run Prometheus with command:

sudo docker run --name prom -v /path/to/configuration/file/prometheus.yml:/etc/prometheus/prometheus.yml -v prometheus-data:/prometheus -p 9191:9090 prom/prometheus:v2.12.0 --storage.tsdb.retention.time 32d --config.file=/etc/prometheus/prometheus.yml

  • --name prom is the name of the container, can be changed to any name desired
  • -p 9191:9090 maps port 9191 to port 9090 in docker container, prometheus should be accessible at http://localhost:9191
  • /path/to/configuration/file/prometheus.yml should point to configuration file that will Prometheus load
  • --storage.tsdb.retention.time 32d flag will set to keep data only for 32 days

Example configuration file for Prometheus:

global:
 scrape_interval:     10s
 evaluation_interval: 10s
scrape_configs:
 - job_name: insert_gateway_id_here
   metrics_path: /orchesto/prometheus/metrics
   static_configs:
     - targets: ['host_where_orchesto_is_running']

Central setup

  1. set environment variables required by Central:

    • JWT_SECRET
    • POSTGRES_URL
    • PASSWORD_RESET_SECRET
    • PROMETHEUS_URL (including protocol, ie http://localhost:9191)
    • ADMIN_USERNAME (optional)
    • ADMIN_PASSWORD (optional)
    • EMAIL_USERNAME (optional)
    • EMAIL_PASSWORD (optional)
    • EMAIL_SERVER (optional)
    • DEPLOYMENT_URL (optional)
    • EMAIL_PORT (optional)

  2. run Central application

  3. If not set via environment variables ADMIN_USERNAME and ADMIN_PASSWORD, first user will be created automatically and login details will be printed in the console like this.
    {"level":"info","ts":1572966003.9026456,"caller":"db/postgres.go:104", "msg":"Created default user with username: PKQ369YaIRH3hy5T@orchesto.io and password: 5xzR1PmUhncssgEKfd0CWXxEFauENVyFawaQ1rZtWdfwMQypFqYL4SuRV1pAoHyU"}
    If set via environment variables, no info will be printed

  4. Use a web browser and go to localhost:5000

  5. Log in using the credentials from the console or the ones set via environment variables
  6. Change the password
  7. In the left menu choose Gateways > Add gateway
  8. Fill in:
    • Gateway name name of the gateway, will show up on Gateways list
    • Tags (optional)
    • Endpoint address of the running Orchesto, will be used for heartbeats
    • Access key provided by Orchesto
    • Secret key provided by Orchesto

  9. After creating first gateway, click on its name to see Gateway detail and copy the gateway ID from url. https://example.com/central/gateways/bfa2599e-f633-11e9-be60-82c7c3f46f34

    The gateway ID is in this example bfa2599e-f633-11e9-be60-82c7c3f46f34

  10. Open the Prometheus configuration file and add scraping target

scrape_configs:
 - job_name: bfa2599e-f633-11e9-be60-82c7c3f46f34
   metrics_path: /orchesto/prometheus/metrics
   static_configs:
    - targets: ['orchesto.example.com']

  • Change job_name to gateway ID and targets to Orchesto host.

  • Restart Prometheus container with sudo docker stop prom and sudo docker start prom