Skip to content

Deploying the Nexodus Service

This document discusses how to run the control plane for Nexodus.

Run on Kubernetes

Deploy using KIND

Note This section is only if you want to build the service stack. If you want to attach to a running service, see Deploying the Nexodus Agent.

You should first ensure that you have kind, kubectl and mkcert installed.

If not, you can follow the instructions in the KIND Quick Start.

Once you have kind installed, you should also follow the instructions here to prevent errors due to "too many open files".

make run-on-kind

This will install:

  • nexodus-dev kind cluster
  • ingress-nginx ingress controller
  • a rewrite rule in coredns to allow auth.try.nexodus.127.0.0.1.nip.io to resolve inside the k8s cluster
  • the nexodus stack

To bring the cluster down again:

make teardown

HTTPS

The Makefile will install the https certs. You can view the cert in the Nexodus root where you ran the Makefile.

cat .certs/rootCA.pem

You can recreate that file at any time with the following.

make cacerts

In order to join a self-signed Nexodus Service from a remote node or view the Nexodus UI in your dev environment, you will need to install the cert on the remote machine. This is only necessary when the service is self-signed with a domain like we are using with the try.nexodus.127.0.0.1.nip.io domain for development.

Add the following host entries to /etc/hosts pointing to the IP the kind stack is running on.

<IP of machine running the KIND stack> auth.try.nexodus.127.0.0.1.nip.io api.try.nexodus.127.0.0.1.nip.io try.nexodus.127.0.0.1.nip.io

Install mkcert on the agent node, copy the cert from the service running kind (.certs/rootCA.pem) to the remote node you will be joining (or viewing the web UI) and run the following.

CAROOT=$(pwd)/.certs mkcert -install

Verify the service by attaching a node using built-in accounts as part of the kubernetes dev overlay build make run-on-kind provides.

# from the nexodus repo directory root:
make dist/nexd
sudo NEXD_LOGLEVEL=debug dist/nexd --username admin --password floofykittens --service-url https://try.nexodus.127.0.0.1.nip.io

# or if you wanted to run multiple sandboxed containers:
make run-nexd-container

Alternatively, or build the nexctl binary and running a command with it.

make dist/nexctl-linux-amd64
dist/nexctl-linux-amd64 --service-url https://try.nexodus.127.0.0.1.nip.io --username admin --password floofykittens -output json device list

For windows, we recommend installing the root certificate via the MMC snap-in.

Redeploy with code changes

If you modify api-server code and would like to build and redeploy the KIND cluster, the following make commands are available to you from the Makefile.

# make, load and redeploy the services
make redeploy
# redeploy the services and reset the database
make recreate-db

Enabling Email Notifications

To enable email notifications, you will need to create a Kubernetes secret that contains the SMTP server configuration in the namespace that the nexodus. Here's an example of what that Kubernetes secret would look like:

apiVersion: v1
kind: Secret
metadata:
  name: smtp-server
stringData:
  NEXAPI_SMTP_HOST_PORT: "smtp.example.com:465"
  NEXAPI_SMTP_TLS: "true"
  NEXAPI_SMTP_USER: "smtp-username"
  NEXAPI_SMTP_PASSWORD: "password"
  NEXAPI_SMTP_FROM: "no-reply@example"