NLX is an open source inter-organisational system facilitating federated authentication, secure connecting and protocolling in a large-scale, dynamic API landscape.
This repository contains all of the components required to act out the NLX Product Vision.
Developing on NLX
Please find the latest documentation for using NLX on docs.nlx.io. This is a good place to start if you would like to develop an application or service that uses or provides API access over NLX.
Questions and contributions
Read more on how to ask questions, file bugs and contribute code and documentation in
Building and running an NLX network locally
The NLX project consists of multiple components that together make up the entire NLX platform. Some components run as centralized NLX services, others run on-premise at organizations. All components are maintained in a single repository. This means that a developer has all the tools and code to build and test the complete NLX platform in a single repository. It simplifies version and dependency management and allows changes that affect multiple components to be combined in a single feature branch and merge-request.
If you want to develop locally, or run your own NLX network, you will likely want to start all the components.
Make sure you have installed the following tools:
For autocompletion and local development tasks, it's also recommended to install the following:
This project uses the new go module feature so it is not required to setup a
Clone nlx in your workspace.
Note for Go developers: We advise to not clone nlx inside the GOPATH. If you must, be sure to set the environment variable
Go doesn't need to be located in the GOPATH since it uses Go module support.
git clone https://gitlab.com/commonground/nlx cd nlx
Running complete stack in kubernetes/minikube
Setup minikube on your local development machine. For developers, it's advised to setup minikube with 4 cores, 8GB RAM and 100+G storage.
minikube start --vm-driver=kvm2 --cpus 4 --memory 8192 --disk-size=100G
Read the minikube README for more information.
Once minikube is running, initialize helm by running
Next, install the following dependencies:
traefikfor web and rest-api requests.
nginx-ingressfor grpc and mutual-tls connections. Latest version is currently(2018-09-06) broken, so needs
postgresfor directory-db and txlog-db.
helm install stable/traefik --name traefik --namespace traefik --values helm/traefik-values-minikube.yaml helm install stable/nginx-ingress --version 0.17.1 --name nginx-ingress --namespace=nginx-ingress --values helm/nginx-ingress-values-minikube.yaml helm install stable/postgresql --name postgresql --namespace=postgresql --values helm/postgresql-values-minikube.yaml
When these components are running, you can start all the NLX components by executing:
MINIKUBE_IP=$(minikube ip) skaffold dev --profile minikube
Finally, add the minikube hostnames to your machine's
/etc/hosts file so you can reach the services from your browser.
echo "$(minikube ip) traefik.minikube" | sudo tee -a /etc/hosts echo "$(minikube ip) docs.dev.nlx.minikube" | sudo tee -a /etc/hosts echo "$(minikube ip) certportal.dev.nlx.minikube" | sudo tee -a /etc/hosts echo "$(minikube ip) directory.dev.nlx.minikube" | sudo tee -a /etc/hosts echo "$(minikube ip) directory-api.dev.nlx.minikube" | sudo tee -a /etc/hosts echo "$(minikube ip) insight.dev.nlx.minikube" | sudo tee -a /etc/hosts echo "$(minikube ip) txlog.dev.rdw.minikube" | sudo tee -a /etc/hosts echo "$(minikube ip) irma-api.dev.rdw.minikube" | sudo tee -a /etc/hosts echo "$(minikube ip) insight-api.dev.rdw.minikube" | sudo tee -a /etc/hosts echo "$(minikube ip) txlog.dev.brp.minikube" | sudo tee -a /etc/hosts echo "$(minikube ip) irma-api.dev.brp.minikube" | sudo tee -a /etc/hosts echo "$(minikube ip) insight-api.dev.brp.minikube" | sudo tee -a /etc/hosts echo "$(minikube ip) txlog.dev.haarlem.minikube" | sudo tee -a /etc/hosts echo "$(minikube ip) irma-api.dev.haarlem.minikube" | sudo tee -a /etc/hosts echo "$(minikube ip) insight-api.dev.haarlem.minikube" | sudo tee -a /etc/hosts echo "$(minikube ip) outway.dev.haarlem.minikube" | sudo tee -a /etc/hosts echo "$(minikube ip) application.dev.haarlem.minikube" | sudo tee -a /etc/hosts
You may now test the following sites:
- https://traefik.minikube:30443 A webinterface showing the status of the traefik ingress controller.
- http://docs.dev.nlx.minikube:30080 The NLX docs
- http://certportal.dev.nlx.minikube:30080 The NLX certportal
- http://directory.dev.nlx.minikube:30080 The NLX directory
- http://txlog.dev.rdw.minikube:30080/ Transactionlogs for the RDW example organization
- http://txlog.dev.brp.minikube:30080/ Transactionlogs for the BRP example organization
- http://txlog.dev.haarlem.minikube:30080/ Transactionlogs for the Haarlem example organization
- http://outway.dev.haarlem.minikube:30080/ Outway in the Haarlem example organization
- http://application.dev.haarlem.minikube:30080/ Demo application
To test a full request through outway>inway, use the PostmanEcho service through the exampleorg outway:
Note the ports;
30443 are routed via traefik (TLS handled by traefik), whereas
:443 are used by nginx-ingress, which does "tcp-proxying" with ssl passthrough so the mutual TLS can be handled by inway/outway/directory/etc.
If you want to connect over IP instead of using a hostname, the ingress controller cannot route the request properly. Therefore you must setup a port-forward directly to the application you want to expose. This is useful, for example, when testing IRMA using a phone on the same WiFi network as your host machine.
kubectl --namespace nlx-dev-rdw port-forward deployment/irma-api-server 2222:8080 socat tcp-listen:3333,fork tcp:127.0.0.1:2222
You can now let your phone connect to the IRMA api server of RDW on
If you are running into other issues, please Post an Issue on GitLab.
Deploying and releasing
NOTE: Automated releases are currently not available.
The CI system of GitLab builds every push to the master branch and creates a release to Docker, tagging it with the short git commit hash. When a release is successful, it also gets deployed to the test environment.
When a git tag is pushed, GitLab builds and deploys it to the test and staging environments.
There are multiple live environments for NLX
test: deployed with a new version on master was build
acc: deployed when a version tag (git tag) was build
demo: manually deployed, only version tagged releases should be deployed to demo
Copyright © VNG Realisatie 2017