Version: current

Getting up and running

Start NLX using Docker Compose

Now we have prepared all the requirements to run NLX, we can start all components using Docker Compose.

Next to the certificates you created in retrieve a demo certificate you also need certificates from an internal PKI to encrypt traffic between NLX components (such as the Management API and the Inway). The demo already has a working PKI so you don't have to set this up yourself.

First, let's clone the NLX project. It contains the Docker Compose file and its dependencies.

git clone --depth 1 https://gitlab.com/commonground/nlx/nlx.git nlx

After the repository is cloned, move into it:

cd nlx

Set the hostname of the Inway (where my-organization.nl:443 should be replaced with your own hostname).

echo "INWAY_SELF_ADDRESS=my-organization.nl:443" > .env

Then, start all components by running:

docker-compose -f docker-compose.management.yml up

This will start Dex (Identity Provider), ETCD and the required NLX components.

The NLX components are configured using environment variables which in this guide are set in docker-compose.management.yml

Below you is an overview of the environment variables per NLX component:

Environment variables

  • DIRECTORY_REGISTRATION_ADDRESS This address is used by the inway to anounce itself to the directory.
  • INWAY_NAME Alias the Inway by a name instead of it's unique identifier.
  • SELF_ADDRESS The address of the inway so it can be reached by the NLX network.
  • MANAGEMENT_API_ADDRESS The address of the Management API.
  • TLS_NLX_ROOT_CERT This is the location of the root certificate.
  • TLS_ORG_CERT This is the location of the organization certificate.
  • TLS_ORG_KEY This is the location of the organization private key.
  • POSTGRES_DSN Connection-string to the PostgreSQL database.
  • DISABLE_LOGDB The value 1 will disable the transaction logs, the value 0 will enable them.

At last, let's verify if all the components are up and running:

docker-compose -f docker-compose.management.yml ps

It might take a while for all components to become healthy. If after a while one or more components aren't running you can inspect the logs for any errors.

Dex (Identity Provider)

The Management UI supports the OpenID Connect protocol for authentication and authorization. In the demo we provide Dex, which is a configurable Identity Provider.

On Linux based operating systems this works out-of-the-box. If you're using MacOS or Windows you will need to add the hostname for Dex to the known hosts.

sudo sh -c "echo '127.0.0.1 dex.nlx.localhost' >> /etc/hosts"

Now let's verify that the local hostname for Dex points to the host:

ping dex.nlx.localhost -c 1

The output should be:

#
# PING dex.nlx.localhost (127.0.0.1) 56(84) bytes of data.
# 64 bytes from localhost (127.0.0.1): icmp_seq=1 ttl=64 time=0.026 ms
#
# --- dex.nlx.localhost ping statistics ---
# 1 packets transmitted, 1 received, 0% packet loss, time 0ms
# rtt min/avg/max/mdev = 0.026/0.026/0.026/0.000 ms

Access the Management UI

You can access the Management UI by opening http://localhost:8080 in your browser. When you do you should see the login screen:

Login screen

Clicking on the login button leads you to Dex which acts as an OpenID Connect Identity Provider. For demo purposes we configured Dex to accept a static username/password but in production you would use your own Identity Provider.

You can login with the demo credentials:

After logging in you will be asked to grant access. Click on "Grant Access" to get access to the Management UI.

Management UI overview

On the left you will find the main navigation which separates the UI in several pages:

  • Inways: Lists all available inways.
  • Services: Shows a list of your services. You can also register new services here.
  • Directory: Lists all available services in the demo directory. This is also the place where you can request access to another service.
  • Settings: Shows all global settings. Currently only the insight and organization inway settings.

Overview

Set the organization inway

In order to receive access requests you have to set a default inway for your organization. You can do that by going to the settings page, selecting the "Inway-01" and clicking on "Save settings".

Settings screen

In sum

So far we have:

  • Started all components using docker-compose
  • Granted access to the Management UI
  • Set a default organization inway

Next up, let's consume an API.