Overview
This article describes how to install a fresh copy of UISP or update an existing installation on a (self-hosted) server. This is a guide for a Linux installation, see the following note for Windows and macOS operating systems:
- See the section below for the UISP installation prerequisites.
- Unfortunately, proper operation, smooth backups, and upgrades of critical Docker containers cannot be ensured on Windows and macOS systems.
- At this time we recommend that you install a virtualization program such as VirtualBox to run the latest version of Ubuntu 20.04. (Focal Fossa) 64-bit and then follow the Linux instructions provided below.
Table of Contents
Prerequisites
It is certainly possible to place the UISP server in a different spot in a topology, but there may be some limitations involved.
- Supported Distros (LXC virtualized Distros aren’t officially supported please use KVM):
- Ubuntu 16.04 LTS (Xenial Xerus) 64-bit
- Ubuntu 18.04 LTS (Bionic Beaver) 64-bit
- Ubuntu 20.04 LTS (Focal Fossa) 64-bit
- Debian 9 64-bit
- 2 GB RAM (Minimal)
- 16 GB of fast SSD storage (Minimal)
- 64-bit (x64) CPU
- Locally used ports (see Changing the HTTP and HTTPS Ports for custom ports)
- 80 (Let's Encrypt certificate automation)
- 81 (Suspension page)
- 443 (UI, API, Devices connector)
- Allow ping (see Devices Latency and Outage Statistics)
- A kernel with overlay2 storage driver (see Docker Storage Drivers)
- bash, curl, sudo (see Installing Prerequisites)
Installation Instructions
Run the command below on the host to install and start UISP (it will automatically install Docker if it is not installed already). If a UISP installation already exists, it will be overwritten, but all data will be kept. It is possible to use the --update
attribute if the new installation needs to have the same parameters as the old one.
The command below will always install the newest, stable version that is listed in the Software Releases section on the Ubiquiti Community. To view, select the Stable status, followed by the UISP tag in the General section.
curl -fsSL https://unms.com/v1/install > /tmp/unms_inst.sh && sudo bash /tmp/unms_inst.sh
During the installation process, the script will check if TCP port 80 and TCP port 443 are open/available. If the ports are in use, the script will pause and ask which ports should be used by UISP. The same applies to the overcommit memory settings. If the vm.overcommit_memory
is not set to '1', the installation script asks for permission to enable it. In case those interrupts are unwanted in the installation process it is possible to suppress them with --unattended
attribute which lets the installation script do all the necessary arrangements by itself.
When the process is complete, UISP will be accessible at the https://<ip or hostname> address. Please do not use localhost to connect to UISP.
Registering new devices to UISP can be done by following the steps in:
If it is necessary to customize the installation process, follow the steps in:
If you wish to install a UISP version that is not the current, stable version see:
Updating an Existing Installation
Once installed, UISP will periodically check for new updates and prompts for installation. Verify whether UISP is up to date and the version that is installed in the Settings > Maintenance section. It is also possible to manually check for updates in this section.
We recommend using the Web UI update method over manually updating through the CLI. It is highly suggested to create a full backup of UISP before using the CLI method.
Related Articles
UISP - The UISP Key and the Device Registration Process
UISP - Optional Installation Steps