Tutorials › Getting Started › NEPI Docker Setup

NEPI Docker Setup

This tutorial walks you through installing, configuring, and running NEPI in a Docker container. It covers both the Lite setup (minimal host changes) and the Full setup (complete production deployment).

NEPI Docker Lite Setup

Introduction

The NEPI Docker Lite Setup tutorial walks you through installing, configuring, and running the NEPI software inside a Docker container while making minimal changes to the host operating system. This tutorial focuses on setting up the required NEPI users, configuring the Docker environment, initializing NEPI storage and images, and launching the NEPI container and Resident User Interface for the first time.

The Lite setup is designed for fast evaluation, development, and a demonstration trial on edge devices before running the NEPI Full Container Installation. It allows users to explore NEPI's AI, automation, and hardware integration capabilities without NEPI managing system-level services such as networking, SSH, or storage sharing. This makes it ideal for learning, prototyping, classroom use, and early-stage testing before committing a device to a production configuration.

Prerequisites:

Before you begin, make sure you have the following ready. This Lite setup is designed to be quick and makes minimal changes to the system.

Hardware

NEPI-compatible device (NVIDIA Jetson)

Monitor, keyboard, and mouse connected to the device

Internet connection (Ethernet recommended, WiFi also works)

Operating System

Debian-based Linux

Tested with Ubuntu 20.04

Default Jetson Linux images are supported

User Access & Permissions

Admin (sudo) access on the device

Ability to reboot the device when prompted

Time Required

30-45 minutes

This includes:

User and environment setup

Docker Lite configuration

Image download and first launch

Note: This setup includes a few reboots. Plan to complete it in one session

 

NEPI Docker Lite User Setup

This section creates the nepihost user account and prepares your device to install NEPI Docker by cloning the NEPI setup repository that contains the required installation scripts.

1) Log into a user account with Administrator privileges, or use the existing nepihost account if available.

2) Open a Terminal window: right-click the desktop / Open in Terminal

3) Confirm your system has internet access by running the following command:

ping -c 1 google.com

USER_1 - NEPI

4) Update Git application:

sudo apt update && sudo apt install -y git

USER_2 - NEPI

5) Clone the NEPI setup repository:

cd /home/${USER}

git clone https://github.com/nepi-engine/nepi_setup.git

USER_3 - NEPI

6) Run the NEPI Docker user setup script (sudo password is '#Nsetup4You'):

cd /home/${USER}/nepi_setup/scripts

sudo su

Then:

./docker_user_setup.sh

Start Screen:

USER_3 - NEPI

End Screen:

USER_4 - NEPI

7) POWER CYCLE your system when complete to apply the new settings

NOTE: This section creates a new user account nepihost, the next section will have you login to this new user with the sudo password nepi.

NEPI Docker Lite Environment Setup

This section will set up the NEPI Docker required software environment.

1) Log into the nepihost account created in Docker User Setup (sudo password is now 'nepi'). Go through any new user starter popups. Then Open terminal.

2) Make sure your system has internet access by running the following command:

ping -c 1 google.com

3) Clone the NEPI Setup repo:

cd /home/${USER}

git clone https://github.com/nepi-engine/nepi_setup.git

4) Run the NEPI Docker Lite Environment setup script (sudo password is 'nepi'):

source /home/nepihost/nepi_setup/scripts/docker_lite_env_setup.sh

NOTE: For all password inputs, the text will be invisible, press enter after typing password.

NOTE: If prompted enter: 'y' or 'yes':

NOTE: This step can take around ~10 minutes to load.

Start Screen:

ENV_1 - NEPI

NOTE: If you get a 'System program problem detected' popup, select 'Cancel' to dismiss it.

ENV_2 - NEPI

NOTE: If you get a 'Configuration Code' popup, select 'Yes' and enter to continue.

ENV_3 - NEPI

End Screen:

ENV_3 - NEPI

5) Once the script completes, scroll through the terminal output and verify there are no errors.

6) POWER CYCLE your system when complete.

NEPI Docker Config Setup

This section will configure the NEPI Docker configuration using the default settings. You can change settings later in the 'NEPI Docker Customization' section.

1) Log into the nepihost account (sudo password is 'nepi')

2) Run the NEPI Docker Lite Configuration setup script (sudo password is 'nepi'):

source /home/nepihost/nepi_setup/scripts/docker_lite_config_setup.sh

Start Screen:

CONFIG_1 - NEPI

End Screen:

CONFIG_2 - NEPI

3) POWER CYCLE your system when complete.

NOTE: After this process, the following changes will be made:

  • Desktop background and sidebar applications menu updates.
    • NEPI bash alias and util functions added to user bash profile.
    • NEPI folder shortcuts added to File Manager folder bookmarks.
    • Chromium browser updated with useful NEPI browser bookmarks.
    • The NEPI Docker install instructions file is added to the Desktop.

NOTE: This process will create the following NEPI Folders:

  • NEPI Storage folder created at '/mnt/nepi_storage', along with several user subfolders. This is where NEPI processes store user files such as: Saved Data, AI models, Import/Export Docker Images, and User Saved Configurations.
    • NEPI Docker folder created at '/mnt/nepi_docker', This is where NEPI Docker Images are stored.
    • NEPI Config folder created at '/mnt/nepi_config', along with several config subfolders.

NEPI Docker Lite Init Setup

This section will initialize and test your NEPI Docker solution. You can change settings later in the 'NEPI Docker Customization' section.

1) Log into the nepihost account (sudo password is 'nepi')

2) Check for internet connection:

ping -c 1 google.com

3) Run the Docker Lite Initialization script (sudo password is 'nepi'). If prompted enter: 'y' or 'yes':

source /home/nepihost/nepi_setup/scripts/docker_lite_init_setup.sh

INIT_3 - NEPI

4) Run the NEPI Docker Import command (sudo password is now 'nepi'):

nepiimport

5) After the initialization script completes, you can view and print the installed NEPI Docker Images by typing:

dimg

NOTE: This process downloads the Lite AI models, AI training scripts, sample data files, and user_configurations to folders in /mnt/nepi_storage.

NOTE: This process downloads the latest NEPI Docker Image for your system's architecture NEPI Docker's import folder at /mnt/nepi_storage/nepi_images.

NEPI Docker Image Testing

This section verifies that the NEPI Docker container runs successfully and that the NEPI Resident User Interface (RUI) launches correctly.

1) Start your NEPI container running:

nepistart

DTEST_1 - NEPI

2) Wait for the startup confirmation message.

NOTE Newly installed NEPI Docker Images may take several attempts to start successfully the first time after installation. Try running several times if it fails

3) Open Chromium browser. Check that the NEPI Resident User Interface (RUI) is running by opening the Chromium browser tab and entering the following in the URL search bar:

localhost:5003

4) Confirm that the NEPI RUI dashboard loads and shows a blinking green indicator, signaling that the core NEPI software system is running and that NEPI is active.

NOTE: RUI Controls related to User, Device, Time, Network, and Software management require the NEPI Docker service running.

DTEST_2 - NEPI

NEPI Docker Service Setup

This step enables NEPI to automatically start whenever the system boots, so you don't have to manually start it each time.

1) Enable NEPI Docker service:

nepienable

NOTE: You can disable the NEPI Docker Service with 'nepidisable'

SERVICE_1 - NEPI

2) POWER CYCLE your system when complete.

3) Log back into nepihost (sudo password is 'nepi').

4) Verify that your NEPI Container is running after reboot:

dps

NOTE:If your container is not running, try to debug NEPI Docker Service issues with the following commands:

nepirestart

nepistatus

nepilogs

NEPI Docker IP Configuration

If you want to connect to your NEPI device from a network connected PC, setup and test a remote connection following these instructions

Additional Resources

If this is your first time setting up NEPI Docker, it is highly recommended that you read through the "NEPI Docker Installation Notes" section on the official GitHub setup guide: NEPI Docker Host Setup Instructions on GitHub.

If you encounter any issues starting and running the NEPI Software container, see the debugging steps in the "NEPI Docker Debugging" section at the bottom of this page: https://github.com/nepi-engine/nepi_setup/blob/main/NEPI_DOCKER_LITE_SETUP.md

For additional support, visit the NEPI Software Community Forum at: NEPI Community

Debugging Troubleshooting

If your container is not running, try to debug NEPI Docker Service issues with the following commands:

nepirestart

nepistatus

nepilogs

For detailed debugging instructions, logs, and advanced troubleshooting steps, refer to the official GitHub setup guide: NEPI Docker Host Setup Instructions on GitHub.

NEPI Software Shortcut Functions

View all NEPI Docker command-line shortcuts anytime by typing:

nepihelp

NEPI Docker Local PC Connections

In this step, you will configure your NEPI device's IP address to allow local PC's to find and communicate with with the device. ]

1) Open the Settings app and navigate to the Network Settings page. You can also click the "Show Applications" button at the bottom-left corner of your screen, search for the "Settings" application, and launch it from there.

2) Select your Wired connection. Click the gear icon to edit the connection.

3) Go to the IPv4 tab and set IPv4 Method to Manual.

4) Add an address with the following values:

Address: 192.168.179.103

Netmask: 255.255.255.0

5) Click Add or Save, then close the settings window.

6) Reboot your NEPI device

Your device is now configured with a static IP address and ready for the next step.

NEPI Docker Camera and AI Detection Test

If you want connect a camera and run an AI model on the camera's video stream follow the instruction in the following 'Using NEPI' tutorial:  https://nepi.com/tutorials/connecting-a-camera-to-an-ai-detector/

NTP Time Servers

NEPI Engine - Configuring NTP Time Syncing

Introduction

This tutorial covers connecting and configuring an NTP server running on a locally network connected PC with a NEPI devices' onboard time management system, which will automatically update your NEPI devices clock when both devices are connected on the network.

What you will need

1) 1x NEPI-enabled processor device and power supply.

2) 1x PC with Ethernet network adapter

3) 1x Ethernet Cable

Hardware Setup

1) Connect the NEPI device to your PC's Ethernet adapter using an Ethernet cable, then power your NEPI device.

A close-up of a computer Description automatically generated

PC Setup

Network Adapter Configuration

On the PC, you will need to configure the Ethernet network adapter with a static IPV4 address on the same subnet that your NEPI device following the steps below. The NEPI software uses a default subnet of 192.168.179.0/24 with the device configured for IP address 192.168.179.103.

Example: PC Network Adapter Settings

IP Address: 192.168.179.5

Submask 255.255.255.0

NTP Server Setup

On the PC, you will need to install and start an NTP Server. The process varies based on the operating system your PC is running as described below.

Linux Operating Systems

1) With your PC connected to the internet, open a terminal and run the following commands:

sudo apt-get install ntp

service ntp start

2) Check that the NTP server is running by typing

ntpq -p

You should see something like this

For additional information, take a look at: https://www.tekopolis.com/configuring-ntp-linux-client/

Windows Operating System

1) Instructions for setting up an NTP server on a Windows PC can be found at: https://support.hanwhavision.com/hc/en-us/articles/26570683589529-How-to-Setup-an-NTP-Server-on-Windows-10

NEPI Device Setup

By default, NEPI looks for and will connect to a local NTP server broadcasting on IP address 192.168.179.5. 

Adding Additional NTP Connections

Additional NTP server IP addresses can be added or removed by publishing the IP address to the ROS topics "add_ntp_server" and "remove_ntp_server".

1) To add an NTP server IP address to your NEPI device's NTP search addresses, open an SSH connected terminal to your nepi device and enter the following commands:

rostopic pub /nepi/s2x/add_ntp_server std_msgs/String "data: 'IP_ADDRESS_TO_ADD'"

NOTE: If your NTP server is on a subnet other than "192.168.179", you will need to add the NTP's server's subnet to your NEPI device's IP addresses. See the "NEPI Ethernet Setup" section in "NEPI Engine - Connecting and Setup" tutorial for instructions on adding additional IP addresses to your NEPI device at: https://nepi.com/nepi-tutorials/nepi-engine-connecting-and-setup/

2) To remove an NTP server IP address to your NEPI device's NTP search addresses, open an SSH connected terminal to your nepi device and enter the following commands:

rostopic pub /nepi/s2x/remove_ntp_server std_msgs/String "data: 'IP_ADDRESS_TO_REMOVE'"

Check your NEPI NTP Connection

You can check that your NEPI device is connected to your PC's NTP server by opening the NEPI device's RUI Dashboard tab and verifying that the "NTP" indicator is green.

NOTE: It can take several seconds for the indicator to update after opening the RUI Dashboard tab.

A screenshot of a computer Description automatically generated

You can find additional information about your NEPI Device's NTP connections by opening an SSH connected terminal to your NEPI device and typing:

chronyc tracking

You should see something like this.

NEPI Docker Full Setup

This tutorial walks you through setting up, configuring, and running the full NEPI Docker container on a suitable edge processor. This is a more comprehensive setup than Docker Lite and is recommended for production deployments.

What you will need

1) 1x A monitor, keyboard, and mouse connected to the host system.

NEPI Docker User Setup

This section creates the nepihost user account and prepares your device to install NEPI Docker by cloning the NEPI setup repository that contains the required installation scripts.

1) Log into a user account with Administrator privileges, or use the existing nepihost account if available.

2) Open a Terminal window: right-click the desktop / Open in Terminal

3) Confirm your system has internet access by running the following command:

ping -c 1 google.com

Terminal output showing ping test

4) Update Git application (sudo password is '#Nsetup4You'):

sudo apt update && sudo apt install -y git

Terminal output showing git installation

5) Clone the NEPI setup repository:

cd /home/${USER}

git clone https://github.com/nepi-engine/nepi_setup.git

Terminal output showing repository clone

6) Run the NEPI Docker user setup script (sudo password is '#Nsetup4You'):

cd /home/${USER}/nepi_setup/scripts

sudo su

Then:

./docker_user_setup.sh

Terminal output showing user setup script

Terminal output showing user setup completion

7) Power cycle your system when complete to apply the new settings.

NEPI Docker Environment Setup

This section will set up the NEPI Docker required software environment.

1) Log into the nepihost account created in Docker User Setup (sudo password is now 'nepi').

2) Run the NEPI Docker environment setup script (sudo password is 'nepi'). If prompted enter: 'y' or 'yes':

/home/nepihost/nepi_setup/scripts/docker_env_setup.sh

Terminal output showing environment setup

NOTE: If you get a 'System program problem detected' popup, select 'Cancel' to dismiss it.

System program problem dialog

Terminal output showing environment setup completion

3) Once the script completes, scroll through the terminal output and verify there are no errors.

4) Power Cycle your system when complete.

NEPI Docker Config Setup

This section will configure the NEPI Docker configuration using the default settings.

1) Log into the nepihost account (sudo password is 'nepi').

NOTE: To enable remote file access through NEPI's built-in Samba network drive sharing, you must first create and mount the following folders as separate partitions:

  1. /mnt/nepi_config - minimum 200 MB
    • /mnt/nepi_storage - minimum 20 GB

Create these partitions before running the next setup step.

2) Run the NEPI configuration setup script (sudo password is 'nepi'):

source /home/nepihost/nepi_setup/scripts/docker_config_setup.sh

Terminal output showing config setup

Terminal output showing config setup progress

This process will create the following NEPI Folders:

  1. NEPI Storage folder created at '/mnt/nepi_storage', along with several user subfolders for saved data, AI models, import/export Docker images, and user saved configurations.
    • NEPI Docker folder created at '/mnt/nepi_docker' for storing NEPI Docker Images.
    • NEPI Config folder created at '/mnt/nepi_config', along with several config subfolders.

3) Test that you can reconnect to the internet and sync clocks:

ninet

4) Check for internet connection:

pingi

Terminal output showing internet connectivity test

5) Power Cycle your system when complete.

NEPI Docker Init Setup

This section will initialize and test your NEPI Docker solution.

1) Log into the nepihost account (sudo password is 'nepi').

2) Enable internet connection and sync clocks:

ninet

Terminal output showing internet connection

3) Check for internet connection:

pingi

Terminal output showing ping test

4) Run the Docker storage initialization script (sudo password is 'nepi'). If prompted enter: 'y' or 'yes':

source /home/nepihost/nepi_setup/scripts/docker_storage_init.sh

Terminal output showing storage initialization

5) Initialize the NEPI Docker image installation:

nepiinit

The script will display the NEPI images currently installed.

Terminal output showing NEPI Docker images

NEPI Docker Image Testing

This section verifies that the NEPI Docker container runs successfully and that the NEPI Resident User Interface (RUI) launches correctly.

1) Start your NEPI container running:

nepistart

Terminal output showing NEPI container starting

2) Wait for the startup confirmation message.

3) Open Chromium browser and enter: localhost:5003

4) Confirm that the NEPI RUI dashboard loads and shows a blinking green indicator, signaling that NEPI is active.

NEPI RUI dashboard showing active status

NEPI Docker Service Setup

This step enables NEPI to automatically start whenever the system boots.

1) Enable NEPI Docker service:

nepienable

Terminal output showing NEPI service enabled

2) Power Cycle your system when complete.

3) Log back into nepihost (sudo password is 'nepi').

4) Verify that your NEPI Container is running after reboot:

dps

Debugging and Shortcuts

If your container is not running, try to debug NEPI Docker Service issues with the following commands:

nepirestart

nepistatus

nepilogs

For detailed debugging instructions, refer to the official GitHub setup guide: NEPI Docker Host Setup Instructions on GitHub.

View all NEPI Docker command-line shortcuts anytime by typing:

nepihelp