Skip to content

OpenLI Provisioner Web UI

Jump to bottom
Shane Alcock edited this page May 21, 2023 · 7 revisions

There is now an officially-supported graphical user interface for managing intercept configuration on the OpenLI provisioner.

The UI is a simple web application that allows you to configure OpenLI intercepts from within your web browser.

The UI code is open source (GPLv3 license) and you can build upon it to create your own custom application, if desired. The source code is available at https://github.com/OpenLI-NZ/openli-provisioner-web.

Installation

The UI web service runs on a GUnicorn WSGI web server, but we recommend that you put a more conventional web server in front of this to act as a proxy. All install instructions assume that you are going to use the apache2 web server as the proxy. You can use a different web server as your proxy (e.g. nginx) but you would need to then port the included apache config over to suit your preferred web server.

The UI web service does not need to be installed on the same host as the OpenLI provisioner, but it may make sense for you to do that.

Installing via Debian Package

NOTE: the package will install apache2 as a dependency. If you want to use a different web server for proxying, you should do a "manual" install.

sudo apt-get install apt-transport-https curl
curl -1sLf 'https://dl.cloudsmith.io/public/wand/openli/cfg/setup/bash.deb.sh' | sudo -E bash
sudo apt-get update

sudo apt install openli-provisioner-web

Installing via RPM

NOTE: the package will install httpd (aka apache) as a dependency. If you want to use a different web server for proxying, you should do a "manual" install.

curl -1sLf 'https://dl.cloudsmith.io/public/wand/openli/cfg/setup/bash.rpm.sh' | sudo -E bash
sudo yum install openli-provisioner-web

Manual install

A manual install is recommended if you intend to use a different proxy server or are using a Linux distribution that does not support .deb or .rpm packages.

Before beginning a manual install, please make sure that the following software is installed:

  • apache2 (or your preferred web server)
  • redis
  • python3 virtual environments
  • systemd / systemctl
  • curl
  • make
  • sudo

On a Debian / Ubuntu system, these prerequisites can be installed by running:

sudo apt install -y apache2 redis-server python3-venv systemd curl make sudo

For RHEL and its derivatives, instead run:

sudo yum install -y httpd make redis systemd curl make mod_ssl findutils sudo

Note that httpd is the name of the rpm for the apache2 server on RHEL.

Once you have the prerequisites, you can install the OpenLI provisioner web UI by running:

git clone https://github.com/OpenLI-NZ/openli-provisioner-web.git
cd openli-provisioner-web
sudo ./scripts/openli-web-provisioner-install-manual.sh

Configuration

There are 3 configuration files that are used by the provisioner UI which you will need to edit before starting the UI service.

Core configuration

/etc/openli-provisioner-web/config.yml

This is a YAML configuration file that contains core configuration for the UI service itself.

The config options included in this file are:

  • api_url -- set this to the URI where your OpenLI provisioner is listening for REST API requests. If your provisioner is using TLS, make sure that your URI begins with https://.
  • api_auth_enabled -- set this to true if the OpenLI provisioner REST API is configured to require authentication (either via digest auth or API key), otherwise set this to false.
  • ignore_tls_verification -- set this to true if the OpenLI provisioner is using a self-signed certificate for TLS, otherwise set this to false.
  • log_level -- defines how much logging that the UI service should do. Should be one of [ DEBUG, INFO, WARN, ERROR, FATAL] in decreasing order of verbosity -- INFO or WARN are good choices if you have no strong preference otherwise.
  • redis_host -- the host that is providing the redis service for the UI. Usually this will be localhost.
  • redis_port -- the port that the redis service is listening on for connections. Usually this will be 6379 unless you have modified your redis configuration.
  • redis_db -- the ID of the redis database to use for the UI service. Unless you have a good reason otherwise, 0 is the correct value to use here.
  • session_cookie_path -- the location where the browser will store the cookies for the UI service. / is fine to use here, but you may put a more specific path if you prefer.
  • session_cookie_secure -- if set to true, session cookies will always be encrypted when sent to and from the browser.
  • session_cookie_domain -- the domain to associate with the session cookies -- this should match the domain where you are going to host the provisioner UI site (e.g. if you will be hosting the UI at https://foo.example.org, then set this option to foo.example.org).
  • session_cookie_signing_key -- the key to use when signing the session cookies -- ideally this should be a long (32 chars +) string of random characters.

GUnicorn configuration

/etc/openli-provisioner-web/gunicorn.py

This is the configuration for the GUnicorn WSGI service that runs the UI service backend. The config is expressed as simple Python code.

The only configuration option in this file that you typically need to worry about is the bind option, which should be set to the address and port that you want the UI backend to be reachable on. Assuming you want a proxy server in front of GUnicorn, then you should use 127.0.0.1 as your address. If you would rather that clients just connect to GUnicorn directly, then you will need to specify an address that your clients can reach.

Apache config for the proxy server

/etc/apache2/sites-available/openli-provisioner-web.conf for Debian/Ubuntu .deb installs

/etc/httpd/conf.d/openli-provisioner-web.conf for .rpm installs

For manual installs, you will need to copy the file contrib/apache2/openli-provisioner-web.conf to wherever apache2 site configuration is located on your system (/etc/apache2/sites-available for Debian/Ubuntu, /etc/httpd/conf.d for RHEL derivatives).

Next, you will need to:

  • replace all instances of example.openli-provisioner.com in the apache configuration with your intended domain name for the UI website.
  • replace the SSL certificate file and SSL certificate key file with genuine TLS certificates
  • make sure the port in the ProxyPass / and ProxyPassReverse / options match the address and port that you set for the bind option in the gunicorn.py config file.

On Debian/Ubuntu, you will also need to enable the site by running:

    sudo a2ensite openli-provisioner-web

On RHEL, any sites configured in /etc/httpd/conf.d are automatically enabled, so you don't have to do anything extra.

Starting the UI service

Once all of your configuration is in place, you can start the website and its underlying services using the following commands:

Debian/Ubuntu

sudo systemctl restart redis-server
sudo systemctl restart apache2                     // if you used a different web server, restart that service instead
sudo systemctl restart openli-provisioner-web

RHEL

sudo systemctl restart redis
sudo systemctl restart httpd                       // if you used a different web server, restart that service instead
sudo systemctl restart openli-provisioner-web

Uninstall

The uninstall process will depend on how you installed the web UI in the first place

Debian / Ubuntu package

sudo apt remove --purge openli-provisioner-web

RHEL .rpm package

sudo yum remove openli-provisioner-web     OR
sudo rpm -e openli-provisioner-web

Manual (un)install

Go into the openli-provisioner-web source directly that you cloned from github to do the install and run:

sudo ./scripts/openli-web-provisioner-uninstall-manual.sh
Clone this wiki locally