Nidulus Platform - Documentation

The "oh, so advanced" guide to get started mass producing APIs with Nidulus

Welcome, we assume you just
downloaded your Nidulus server for the first time and panic over not knowing what to do now.
Take a deep breath and let us get to work.

Unpack your download

unzip nidulus_x_x_x.zip (where x_x_x is the version of your download).

Start nidulus

cd nidulus; ./nidulus

Web interface

The web client you downloaded will have its web interface running on port 7999. Point your browser
to http://<your Nidulus client ip>:7999/ to get to the login page. Login with admin/password123

Initial configuration

After logging on, you will be directed to the server page. There are no servers pre-populated, so
you will have to add one. Click the "Add Server" button and enter the IP/URL of the machine where
you started the nidulus server on. No port must be added, just IP/URL.

The certificate that is asked for will have been created when you started up your Nidulus server,
in the home folder of the user you started it with: ~/client.crt

Once done, you will have finished setting up graphical monitoring/management of your server in your
web client.

When configuring the localhost instance (through the cogwheel menu on the server card), you will have two options:

Adding/setting your activation key
Changing security key

Activation key is your license key (if you purchased/were given one).

The security key, which must be 16 characters long, is randomized for every new machine you start
a Nidulus server on but can be changed into any 16 character sequence. If you wish to communicate
between two Nidulus machines (service network scaling), you need to update the security key to
be same on both machines to avoid getting an unauthorized reply. No other configuration is needed
as every API and service automatically find each other on the network.

If you accidentally "delete" a server in the web client, nothing will happen to the server. You will
just stop monitoring it from the web client and can add it back later on. Everything you deployed
on it will continue to run, it just won't show up in your web client.

What do I do now?

Now you can go to the "Process List" on your newly added server and add new APIs, deploy features
(the sdk package you downloaded) and schedule timed triggers of your features, as needed.

It really isn't harder than this to build advanced APIs, and shouldn't be.

We added an in-app help-center with explanations of each part if you wonder about something while
in the app. You can find it in the upper-right corner of the web app, in the cogwheel menu. You
can also change the password for the admin account from there.

Firewall Configuration

Nidulus opens up an internal communication port not just for each API and each service, but one per instance of each API or service. They will always try to claim port 8000, or next available port above 8000.

Example: You create one new API on port 4444. You run this API in 4 instances, and you have 2 services each running 2 instances each.

Firewall setup: You will have to configure your firewall to allow traffic on TCP port 4444, obviously, but also on TCP/UDP ports 8000-8008 for the internal communication to work, or your API will not communicate with your services.

You MUST also allow traffic on UDP port 12345, this is used for the discovery broadcasting/multicasting.

This is valid even when the API and its services reside on the same machine, as they do not communicate on interface 127.0.0.1 (localhost) but on the external interface of the server.
The traffic in and out from these communication ports is encrypted.

Network Scaling

What do we mean with network scaling, anyways? We are talking about when the time comes where the solution you built is upholding such high traffic that you need more hardware, but you do not want to take the system down for even a second.

As Nidulus processes automatically know about each other on the local network, all you need to cluster/scale is deploy Nidulus on another machine on the same network. Set the "Security key" on both machines to be identical, and deploy all your
services on both machines. You just offloaded the traffic from machine one, to machine two and will now have two machines working together to process your requests.

How this actually works? The APIS in Nidulus will always forward messages to the processes in a round-robin fashion, so every instance on the network will get to process one message each, before it starts over on the first instance. Only required
configuration is that the Nidulus instance on all machines that communicate MUST have the same "Security key" as the API machine has.

Backup

Nidulus is very easy to backup. Every deploy and configuration, as well as all logs and statistics, will be saved to ~/.nidulus
of the user HOME folder that started Nidulus application. Taking a regular copy of this folder allows you to restore
the state at any point by moving the folder to any Linux machine and starting up Nidulus on the machine.Note that if you start nidulus under a different user HOME than previously, you must replace references to the old HOME path in files inside this folder.

Logging

Nidulus has three different log directories.

~/.nidulus/logs/ contains the logs for the nidulus application it self.

~/.nidulus/user_deploy/apis/<APIname>/logs/ exist for all of the APIs you created and will contain API specific errors.

~/.nidulus/user_deploy/services/<ServiceName>/logs/ exist for all of the features/services you deployed and will contain
service specific errors, and your own logging that you write in your code using the logger object. This folder is the same that is downloadable
through the management API and the web client GUI in zipped format.

All of these log folders maintain rotating log files. current.log is the file being written to currently. log1.log, log2.log and log3.log are
the previous three files that have been written. Nidulus rotates current.log to become log1.log when reaching a filesize of 50Mb. Max size of
any log directory is therefor 200Mb.

When log level is set for a specific service, either through management API or the web client GUI, no logging of lower log level will be written
to the log files and taking up space.

A good procedure for a production environment is therefor to keep the service log level at the default "Error" level. Only logs of level "Error"
and "Critical" will be written, while "Info", "Debug" and "Warning" are left out.

Management API

Nidulus official API documentation. Each Nidulus installation contains its own RESTful API server on port 7734 to manage that particular Nidulus
server. The management API allows you to do anything the web client GUI does.

Before running any of the Node.js code examples, make sure you have executed "npm install request" and "npm install util" in the folder you run the
scripts from.

Make sure you have the correct client certificate for the machine you are accessing, or any request will fail.

System features

/system/activation/set

Description: Sets the activation code for this machine. Re-using activation code for multiple machines will result in your APIs and Services on both to automatically be disabled/stopped. The machine MUST be allowed
(check firewall configurations) to access the activation server at https://nidulus.io:6854

/system/seckey/set

Description: Set the security key for clustered service communication. Key MUST be 16 characters long and MUST be same as any other machines seckey you wish to communicate with. If no services/apis from other
machines shall be allowed to call the services on this machine, and apis/services on this machine are not allowed to access services on other machines, set a unique key

/api/cert/add

Description: Upload a certificate to an existing API. Must be a base64 encoded zip file containing (in the root of the zip, no subfolders) CA, Server key, Server Cert. Files must be named like the API: myApi.ca,
myApi.key, myApi.crt. See Node.js example

API Endpoints

/api/endpoint/add

Description: Add a new endpoint to an existing API. datalimit is specified in kilobytes, and timeout in milliseconds. Same path can exist on same API, as long as the method is different (GET/POST/PUT/PATCH/DELETE)

Service Configuration

/service/deploy

Description: Deploy a new service. Must be a base64 encoded zip file containing the service folder. See Node.js example. Number of instances should not be higher than physical cores dedicated to the virtual machine