Running a Unifi Network Controller in a Proxmox LXC Container

4/10/2025: A few minor updates since this was originally posted, including a new section called Future Proofing Use of LXC for your Unifi Network Controller.

For 2025, I decided it was time to address some goals and resurrect a home lab setup I lost a few years back (hard drive failures) along with upgrading the home WiFi from a Netgear Orbi mesh network to a Unifi network with Unifi access points (to help segment my growing IoT onto its own completely isolated VLAN).

My pfSense firewall suddenly crashing (another SD hard drive failure!) also helped with motivation. The pfSense firewall crash prioritized rebuilding the network over the Proxmox VE servers. To facilitate the requisite Unifi Network Controller for the Unifi network, I was forced to rely on a Unifi Cloud Network Controller Subscription for a month or two while I got around to building the Proxmox VE servers.

This meant migrating from the cloud to a local network controller was in my future. Here is how I did it along with setting up a remote backup strategy for my network controller configs.

What Will Be Covered Here

What I’ll cover here then will be:

1. Setting up/installing the Unifi Network Controller in a Proxmox VE LXC container to essentially run as a local fully-encapsulated network appliance. A full VM is really not needed for this.
2. Setting up a backup scheme for the Unifi Network Controller as backups are stored locally on the controller and I wanted those backed up to the (also new) NAS.
3. Migrating from the Unifi Cloud Controller to my LAN-local “network appliance” running as an LXC container in Proxmox VE.

Let’s Get Started

First of all, as I said, there’s really no need to set up a VM for this. The Unifi Network Controller is run as a Java network application with a web frontend and a backend Mongo DB database. We want our appliance stripped down to only these necessary installs and that’s it. This works fine inside an LXC container.

I’m also here to say that the installation instructions on Unifi for installing the network controller on Linux were antiquated. I needed some help from other articles to get past the issues I ran into attempting to follow their documentation. The best article I found was here and from this article, I was able to salvage my work and successfully install.

I’ve subsequentially taken my notes and approach, tested it again, and documented it here.

Step 1: Create an LXC Container on Proxmox

The first step is simply to create the LXC container from the correct LXC template inside of Proxmox VE. Here is the LXC footprint that I used in terms of resources:

The Debian Linux distro is for what Unifi wrote their instructions. So Debian it is — any Debian derivative like Ubuntu should work just fine.

As for the 8GB of disk space, you’ll have a generous 70%+ of disk space left after this install to store backups — which I will also backup to my NAS as a discussion point here.

Step 2: apt update && apt upgrade and SNAPSHOT

As a preface to this step and before going further, let me just say, since this is running as essentially a network appliance inside of Proxmox VE, I personally saw/see no need to get elaborate. I’m simply going to hop into the LXC console inside of my Proxmox VE web interface and execute these commands as root. If you want to create a user account — maybe a unifi account? — and preface all the following commands using sudo, that’s up to you. But in my view, once this is done, this is the only access to the appliance I need is the default web interface that results. ssh isn’t even enabled.

But this is Proxmox VE — you have full control and you can do as you’d like. The instructions from here on assume they are being executed in the Proxmox VE console window for the LXC as root.

Now that the LXC container is running, Step 2 is just update, upgrade, and snapshot. (If I’ve told myself once, I’ve told myself 1000x to snapshot after update and upgrade and how many times have I forgotten to snapshot!!):

# apt update && apt upgrade -y

Now snapshot that container!! 🙂

Step 3: Install Upfront Requisite Packages

We need gpg, Java, and haveged to allow the Unifi Network Controller to run. (haveged generates entropy the controller uses to help with security.)

# apt install -y haveged gpg openjdk-17-jre-headless

Step 4: Download Unifi GPG Key & Add Unifi Repository

Now we need to download the Unifi GPG key and add the Unifi repository to our Debian sources list, referencing the GPG key using the signed-by source directive:

# wget -O /usr/share/keyrings/ubiquiti-archive-keyring.gpg https://dl.ui.com/unifi/unifi-repo.gpg
# echo "deb [signed-by=/usr/share/keyrings/ubiquiti-archive-keyring.gpg] https://www.ui.com/downloads/unifi/debian stable ubiquiti" | tee /etc/apt/sources.list.d/100-ubnt-unifi.list

(Wrap-around lines are all one line.)

Step 5: Download MongoDB GPG Key & Add MongoDB Repository

Now we do the same for MongoDB: Download the Mongo DB GPG key and add the Mongo DB repository to our Debian sources list, again referencing the GPG using the signed-by source directive:

# wget -qO - https://pgp.mongodb.com/server-7.0.asc | gpg --dearmor | tee /usr/share/keyrings/mongodb-org-server-7.0-archive-keyring.gpg > /dev/null
# echo "deb [arch=amd64,arm64 signed-by=/usr/share/keyrings/mongodb-org-server-7.0-archive-keyring.gpg] https://repo.mongodb.org/apt/ubuntu jammy/mongodb-org/7.0 multiverse" | tee /etc/apt/sources.list.d/mongodb-org-7.0.list

Step 6: Update, Install, Enable & Start MongoDB

Now we update the system, and install Mongo DB. Once it’s installed, we systemctl enable and systemctl start the database. Unifi will need to see this up and running when we do the Unifi install as the last step:

# apt update
# apt install -y mongodb-org-server
# system enable mongod
# system start mongod

Step 7: Install Unifi Network Controller

At this point, we install the Unifi Network Controller:

# apt install -y unifi

After the apt install command runs, the Unifi Network Controller should be up and running. Go into your web browser and point your browser to the IP address you entered when you created the LXC container, using port 8443 as the port designation over HTTPS:

https://<your-LXC-IP-address-or-internal-FQDN-here>:8443

Set this up in your hosts file (unifi?) or internal DNS, and you’re good to go:

https://unifi:8443

Remember That Snapshot?! Yeah… 🙂

If somehow this all doesn’t work, or you ran into issues along the way… remember that snapshot you took? You can just restore that snapshot and try again. Likely you just cut and paste a command wrong. Now you don’t have to tear down the container and rebuild it again from scratch. Restore from snapshot and start again at Step 3.

Using curl Instead of wget

If you prefer using curl over wget, you just need to apt install -y curl as part of Step 3. You can use the article I used to iron out my initial issues for the proper curl commands.

Remote Backup of the Unifi Network Controller

My strategy here is to “simply” set a cron job to periodically rsync the local backups on the Unifi Network Controller — which warns all backups are local — over to my NAS. I quoted “simply” because I’m going to make it look local to the LXC container by creating and mounting another disk on the container and having that disk live on the NAS.

Step 1: Install rsync

As already mentioned, my goal for the Unifi Network Controller is to have a stripped network appliance running inside an LXC container. rsync isn’t installed inside the LXC container.

Since I’m just going to rsync these backups, I have to install rsync first inside the LXC container console I’ve been using to do the Mongo DB and Unifi Network Controller installs:

# apt install -y rsync

Step 2: Create New Backup Disk

Next I create a new disk that backups will be rsync‘d to. 8GB is fine. You can make it smaller — it doesn’t need to be huge. The config backups are small. I just went with the default 8GB. You probably don’t want backups of this disk — that is, when you backup the LXC container on Proxmox VE, it will backup the newly mounted disk as well. We don’t need that — that’s why it’s stored on the NAS to begin with:

Now, bear in mind, think of this from the perspective of Proxmox VE. My mount point inside the LXC container says “NAS1” to let me know the disk volume itself is on the NAS. So my backups will be inside the disk volume stored by Proxmox VE on the NAS — the NAS is not NFS mounted at /mnt/NAS1/backup in the LXC container.

If I go over to where the NAS is mounted in Proxmox VE, I can see this set up for my LXC container, which for me is ID 102:

root@construct1:~# df -h
Filesystem             Size  Used Avail Use% Mounted on
udev                    16G     0   16G   0% /dev
tmpfs                  3.2G  1.9M  3.2G   1% /run
/dev/mapper/pve-root    94G   31G   59G  35% /
tmpfs                   16G   66M   16G   1% /dev/shm
tmpfs                  5.0M     0  5.0M   0% /run/lock
/dev/fuse              128M   28K  128M   1% /etc/pve
nas1.lan:/volume1/pve  2.0T   72G  2.0T   4% /mnt/pve/NAS1  <-- Here's where NAS *is*
tmpfs                  3.2G     0  3.2G   0% /run/user/0.       NFS mounted for PVE
root@construct1:~# cd /mnt/pve/NAS1
root@construct1:/mnt/pve/NAS1# ls -l
total 0
drwxrwxrwx 1 root root 256 Mar 19 02:46 dump/
drwxrwxrwx 1 root root   6 Mar 29 18:09 images/      <-- LXC/VM disk images
drwxrwxrwx 1 root root   0 Mar 19 02:40 private/.           are here on NAS
drwxrwxrwx 1 root root  16 Mar 19 02:40 template/
root@construct1:/mnt/pve/NAS1# cd images
root@construct1:/mnt/pve/NAS1/images# ls -l
total 0
drwxrwxrwx 1 root root 34 Mar 28 15:25 102/          <-- My LXC ID is 102
root@construct1:/mnt/pve/NAS1/images# cd 102
root@construct1:/mnt/pve/NAS1/images/102# ls -l
total 221380
-rwxrwxrwx 1 root root 8589934592 Mar 29 23:11 vm-102-disk-0.raw*.  <-- INSIDE image
root@construct1:/mnt/pve/NAS1/images/102#                               are Unifi backups

Step 3: Setup Cron Job to RSync Unifi Network Controller Configs As Needed

Now, I just need to setup a cron job to rsync from the LXC container rootfs volume where the Unifi Network Controller will store them over to the new disk volume I created.

What’s the appropriate timing for the rsync job to run? I’m backing up my Unifi Network Controller weekly on Sunday at 12:30am. So I’m going to set my rsync cronjob for Saturday night at 11pm. I could make it earlier Sunday <shrug>. Just needs to be before the next weekly backup. rsync will ensure only new backups will be copied over when it runs.

You could backup every day — depends on how often you’re changing your Unifi network — and rsync once a week. How often and when is up to you. Hopefully this “NAS volume backup strategy” gives you one idea for storing backups — there are a number of ways you could skin the cat here.

So again, inside the LXC container console:

# crontab -e

And set the rsync job appropriately. Unifi stores the backups in /var/lib/unifi/backup/autobackup. And I’m going to copy them into the /mnt/NAS1/backup/unifi/config/ directory:

0 23 * * 5 rsync -tv /var/lib/unifi/backup/autobackup/* /mnt/NAS1/backup/unifi/config/

List your crontab when you’re done to make sure it’s right:

# crontab -l
# Edit this file to introduce tasks to be run by cron.
# 
# Each task to run has to be defined through a single line
# indicating with different fields when the task will be run
# and what command to run for the task
# 
# To define the time you can provide concrete values for
# minute (m), hour (h), day of month (dom), month (mon),
# and day of week (dow) or use '*' in these fields (for 'any').
# 
# Notice that tasks will be started based on the cron's system
# daemon's notion of time and timezones.
# 
# Output of the crontab jobs (including errors) is sent through
# email to the user the crontab file belongs to (unless redirected).
# 
# For example, you can run a backup of all your user accounts
# at 5 a.m every week with:
# 0 5 * * 1 tar -zcf /var/backups/home.tgz /home/
# 
# For more information see the manual pages of crontab(5) and cron(8)
# 
# m h  dom mon dow   command
0 23 * * 5 rsync -tv /var/lib/unifi/backup/autobackup/* /mnt/NAS1/backup/unifi/config/

Eventually I’ll have to look into a script for cleaning up inside the backup volume. But with 8GB for backups and my network backup being ~10MB, it’s not going to be needed for a while.

(Yes, the backup size will grow as my network data in Mongo DB grows, so I’m gonna have to keep an eye on it and strategize from there — I’ll update this article as I make updates to the backup strategy. Also, yes, the Unifi Network Controller has settings as seen above for limiting the number and days of these backups. But if I’m copying those into my backup disk volume, eventually I’m going to run out of NAS backup space. It’ll be a long time at 8GB, but eventually that 8GB will fill up. I of course have the option with Proxmox VE of expanding the size of the backup volume — an advantage of running Proxmox VE.)

Migrating From Unifi Cloud Network Controller to Local Network Controller

It’s really not complicated:

1. Backup under “Settings” in the cloud.
2. Export the backup.
3. Choose “Restore Server from a Backup” on the opening screen you saw right after you installed Unifi Network Controller locally.

What I didn’t know when I did this:

1. When you backup in the cloud, there are options for “Just for config” or “days and weeks in the past.” What I didn’t realize was the “days and weeks in the past” held all my accumulated network stats from the past as well. That would have been nice to have. I didn’t know and just chose to export the config — the networking equipment and all the configs for each piece of equipment: my switch and APs.
2. I totally missed the “Restore Server from Backup’ option at the bottom. (This resulted in a bit of a kludge I’ll just live with that I won’t go into here.)

At this point, I’m recommending DO NOT GO CRAZY AND LOGIN JUST YET!!!

Read ahead to the next section and see if you won’t agree.

Future Proofing Running Unifi Network Controller in LXC

Now that your (admittedly cool) Unifi Network Controller is up and running in Proxmox VE, it’s time to rejoice, right?! Okay, go ahead… for a little while. Like 5 minutes tops. The very next thing you should do BEFORE LOGGING IN is take both a snapshot and a full backup of your LXC container.

WHY?

The snapshot is for now. The backup is for later. Because you can create a fully functioning LXC container from a full backup. That means, if you backup now, and something happens to your Unifi Network Controller LXC container (or your entire Proxmox VE server — I’ve had it happen!), you’re gonna want your Unifi Network Controller back ASAP.

And one command will do it:

# pct restore 104 vzdump-lxc-103-2025_04_10-14_05_20.tar.zst --storage local-lvm

That’s the exact command I used to clone my Container #103 into Container #104 using the backup from Container #103².

Two things to consider with this approach:

1. The created/ restored container name will be the same as the container that was backed up. (So visit DNS in the container control in the Web GUI and change the name.)
2. The container IP address of the created/restored container will be the same as the container that was backed up. (So visit Network in the container control in the Web GUI and change the IP address.)

If you keep your containers and virtual machines in local-lvm and your backups of both the container image and your Unifi Network Controller backups somewhere else — like in a NAS (as I described above) — this will work very well. You’ll recover your new Proxmox VE server as fast as you can (from a USB install), and you have the two pieces you need — a container image backup and a Unifi Network Controller backup — to bring your Unifi Network Controller up pretty quickly.³

Oh and… NOW you can login. 🙂

What We Covered

Here’s what we covered:

HTH!

Related: Installing Certificate for Self-Hosted Unifi Network Controller

Footnotes

1. In my initial posting, I specified memory of 1024MB or 1GB and swap of 512MB. That turns out to be a bit tight. So far, my installation has run a lot better in 2048MB/2GB of memory and 1024MB/1GB of swap. <ret>
2. I have NO IDEA why Proxmox VE (as of this writing) assumes you want to restore to local storage and not local-lvm storage. Generally images are created on local-lvm or on a NAS. You’ll likely get an error on the pct command without the --storage option because pct restore restores to local storage by default which often isn’t configured for LXC images. The --storage option, directing the restore to the right storage remedies this. (Of course, use --storage <name-of-attached-NAS> to restore to NAS if that’s where you want the restored LXC container to live.) <ret>
3. Note this approach will only provide you with a restored LXC container running your Unifi Network Controller and retired network objects — access points, etc. You’ll have lost all your historical data which was in the Mongo DB database on the container you lost. To remedy, take period snapshots of your Unifi Network Controller LXC container we well. Then (1) restore from the container backup as shown above, and (2) apply your snapshots to get back your historical data. <ret>