Running nio locally

[info] Prerequisites

Create a project

Projects are collections of services, blocks, and configurations. Create a nio folder to keep things tidy:

mkdir -p nio/projects && cd nio/projects

Use the nio CLI (Command Line Interface) to create a new project named "my_project":

nio new my_project

You will be prompted for you Pubkeeper credentials. Obtain your Pubkeeper hostname and token from the System Designer in the edit modal for your system as explained here:

Start your project

The command to run nio locally is niod. This will start running a nio instance on your machine. This command requires that you run it from the root of your project directory.

cd my_project && niod

Log messages should display, similar to the following output. There should be no errors.

NIO [INFO] [main.WebServer] Server configured on
NIO [INFO] Component: ServiceManager status changed to: created
NIO [INFO] Component: ServiceManager status changed from: created to: configuring
NIO [INFO] Component: ServiceManager status changed from: configuring to: configured
NIO [INFO] [main.WebServer] Starting server on
NIO [INFO] [main.WebServer] Server started on
NIO [INFO] Component: ServiceManager status changed from: configured to: starting
NIO [INFO] Component: ServiceManager status changed from: starting to: started

If you see those logs, nio is up and running. Congratulations!

By default, new projects use port 8181. If port 8181 isn’t available, you'll see an error. Change the NIOPORT value in your project's nio.conf file under the [user_defined] section to fix this error.

MacOS Users: While your system comes pre-installed with Python, it is an older version. When installing newer versions, Python may require that you install and trust a set of Root Certificates for its SSL package. That file is located at /Applications/Python 3.x/Install Certificates.command. Just double-click that file to complete the process. Check /Applications/Python 3.x/ReadMe.rtf for more details.

The error string you'll see will look something like this:

WARNING:tornado.general:SSL Error on 7 ('x.x.x.x', 443): [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed

niod can be run from outside of a project directory by using the -r flag and specifying the location of the project directory. For example:

niod -r path/to/my_project

You can run a project in the background on MacOS and Linux using nohup (so you can close your terminal):

nohup niod -r path/to/my_project 2>&1 > /dev/null &

Add the instance to the System Designer

To manage your local instance, you need to add it to the System Designer:

  1. Open the nio System Designer in a browser:
  2. Select your system card from the grid.
  3. Click add instance on the left side of your screen.
    • Check the local instance checkbox.
    • In the instance name box, enter an instance name.
  4. The rest of the text inputs will be pre-filled with default values that you may edit if necessary.
  5. Click accept.

When the System Designer connects to a nio instance, it communicates with that instance directly from your browser via an XHR request. Hostnames like localhost and other internal IP addresses will work. You must have access to the localhost or other IP address from your machine to use the System Designer.

You may see an issue regarding HTTPS and HTTP instances.

[info] security error?

If you launched your instance without any SSL certificates, the instance is only accessible via HTTP. If you are logged into the System Designer via HTTPS, your browser will restrict any XHR requests going over HTTP.

To connect to a local HTTP instance of nio with the System Designer, you'll need to log into the designer via HTTP at All of your instances and systems will be the same, the only difference is, the nio commands to edit these instances won't happen over HTTPS.

Once your instance is loaded and available, you can add services and blocks in the same manner as a cloud instance.

Available nio Blocks can be explored in the nio Block Library where you will find a summary of the block's purpose, a list of its properties, commands, inputs, and outputs, and a link to the block code repository.

View your logs

When running in background mode, you can monitor your logs using the “tail” command:

tail -f /path/to/my_project/logs/main.log

Stop your project

nio shutdown -p {NIOPORT}

NIOPORT is set in your project's nio.conf file under the [user_defined] section

nio.env is obsolete

nio Binaries released after January 26, 2018, no longer use the nio.env file for user-defined variables. Instead, all of these variables are located under the [user_defined] section of nio.conf.

If you would like to use your old projects with the latest binary, run this script from your project directory with python to easily move your variables from nio.env to nio.conf.

results matching ""

    No results matching ""