Virtual Linux Environment Setup

Warning: If you already have Linux on your system, you do not need this tutorial. Skip it and move on to Remote System Setup.

NEPI development tools run in Ubuntu Linux. Choose the tab for your computer's operating system and follow the steps to create an Ubuntu 20.04 virtual machine:

  • Windows - uses Windows Subsystem for Linux (WSL2).
  • Mac - uses UTM on Apple Silicon (M-series) Macs.

Introduction

This tutorial covers installing Ubuntu under Windows Subsystem for Linux (WSL2) and configuring it as a NEPI Remote Dev system. It also covers common first-run issues and their fixes.

Installing WSL and the Ubuntu VM

This section installs WSL2 and an Ubuntu 20.04 virtual machine on your Windows PC.

1) Open a PowerShell terminal with admin privileges. Enter 'powershell' in the Windows search bar, then right-click Windows PowerShell and select Run as administrator. This is required - running without admin privileges causes install failures.

Windows search bar with powershell entered

Run as administrator option for Windows PowerShell

2) Install a specific Ubuntu version by entering the command below. Ubuntu 20.04 is used here for compatibility with NEPI's build environment. Swap the version string if needed:

wsl --install -d Ubuntu-20.04
Note: If you see "The requested operation requires elevation", you were not running as Administrator. Close the window, reopen PowerShell as Administrator, and re-run the command.

3) Reboot Windows - changes to these features do not take effect until restart. Then re-run the install command:

wsl --install -d Ubuntu-20.04

4) Once installed, Ubuntu launches automatically and provisions the instance. When prompted, create the default Unix user account with the following values:

Create a default Unix user account: nepi_dev
New password: nepi
Retype new password: nepi
Note: For all password inputs, the text will be invisible. Press enter after typing the password.

5) You are now working in an Ubuntu virtual environment terminal.

Ubuntu VM terminal prompt

6) You can access your user and other Linux folders in File Explorer under the new Linux sidebar tab.

Windows File Explorer showing the Linux sidebar tab

Logging in to Your WSL Ubuntu VM

This section covers reopening your Ubuntu VM after a Windows restart, or opening additional terminals.

1) Open a PowerShell terminal in Windows and select your Ubuntu VM from the dropdown menu.

PowerShell dropdown menu showing the Ubuntu VM

Note: If you see a message about not having Ubuntu Font Family installed, you can ignore it, or install Ubuntu Font Family in your Windows environment to fix the issue.

Ubuntu Font Family warning message

2) You are now in your Ubuntu VM terminal.

Ubuntu VM terminal

NEPI Remote Connection Setup

This section covers configuring your WSL Ubuntu VM environment to connect to a remote NEPI device over a wired Ethernet connection or a NEPI WiFi hotspot connection.

Note: If your NEPI device is available, it is recommended that you set it up and confirm your Windows environment can connect to the NEPI device's RUI browser interface before proceeding. If your NEPI device is not connected and configured within your Windows environment, you may see some warnings and notes that the setup failed to connect. You can ignore these if that is the case.

1) Connect your Windows PC to your NEPI device:

2) To configure your WSL Ubuntu environment for NEPI remote device connection, follow the instructions at: Remote System Setup

Note: The default Chromium installation does not currently work in this configuration, so you can ignore any errors during that part of the setup. Use Chromium in Windows for now, or force Chromium to open from Ubuntu with: sudo /snap/bin/chromium --no-sandbox 2> /dev/null
Note: If shortcut commands say "command not found", your current shell session started before the script updated your bash config. Reload it by running: source ~/.bashrc

Introduction

These instructions describe how to create and install an Ubuntu 20.04 virtual machine on an Apple Mac computer using UTM.

Requirements:

Create the Virtual Machine

This section creates a new Ubuntu virtual machine in UTM.

1) Open UTM and select Create a New Virtual Machine.

2) Choose Virtualize / Linux.

3) Allocate memory and 6 CPU cores.

4) Leave Use Apple Virtualization unchecked (use QEMU).

5) Select Boot from ISO image and browse to ubuntu-20.04-live-server-arm64.iso.

6) Assign 64 GB of storage.

7) Skip Shared Directory.

8) Review the summary and save the VM.

Install Ubuntu

This section installs Ubuntu Server on the new virtual machine.

1) Boot the VM and choose Install Ubuntu Server.

2) Continue without updating the installer.

3) Accept the default DHCP network configuration.

4) Leave Proxy blank.

5) Accept the default Ubuntu archive mirror.

6) Choose Use entire disk (no LVM).

7) Accept the partition layout and continue.

8) Create your username and password.

9) Enable Install OpenSSH Server.

10) Leave Featured Server Snaps unchecked.

11) Wait for the installation to complete, then reboot.

12) Eject the ISO and restart the VM.

UTM drive menu showing the Eject option for the Ubuntu ISO

Installing the Graphical Interface

This section adds the Ubuntu desktop to your text-based Ubuntu Server install.

1) Log in to the text-based version of Ubuntu.

2) Install tasksel:

sudo apt install tasksel

3) Enter your password when prompted.

Note: For all password inputs, the text will be invisible. Press enter after typing the password.

4) Press 'y' to approve the additional download.

5) Install the Ubuntu desktop:

sudo tasksel install ubuntu-desktop

6) Wait for the install to finish.

Next Step

Your Ubuntu virtual machine is ready. Continue to Remote System Setup to configure it for NEPI development.