The complete guide to self-hosting a UniFi controller on Debian OS

Setting up a UniFi controller on a self-hosted Debian server can be a rewarding experience. You gain control, save costs, and avoid relying on cloud-based subscription services.

Let's dive in!

Table of Contents

• Why Self-Host Your UniFi Controller?
• What You’ll Need
• Step 1: Update Debian OS
• Step 2: Install Required Packages
• Step 3: Add the UniFi Repository
• Step 4: Install UniFi Controller
• Step 5: Configure Java (Optional)
• Step 6: Start and Enable the UniFi Service
• Step 7: Access the UniFi Web Interface
• Step 8: Adopt UniFi Devices
  • How to Adopt a Device
• Step 9: Secure Your UniFi Controller
• Managing the UniFi Controller
• Updating the Controller
• Troubleshooting
  • 1. Can't Access the Web Interface
• Why Use UniHosted Instead?
• Frequently Asked Questions
  • 1. Can I run UniFi on Raspberry Pi?
  • 2. How many devices can a self-hosted controller handle?
  • 3. Can I run UniFi in a Docker container?
• Final Thoughts

Why Self-Host Your UniFi Controller?

Why not just buy a Cloud Key or use a hosting service? Here’s why self-hosting might be a better idea:

1. Cost Savings: No need to purchase extra hardware like a Cloud Key or pay for hosted services.
2. Full Control: You decide when to update, reboot, or migrate.
3. Data Privacy: Your network data stays on your server—no third-party involvement.
4. Customizability: Want to experiment with settings or scripts? You have full control.
5. Fun: If you love working with Linux or learning about network management, this is a satisfying project.

What You’ll Need

Here’s the checklist for what you’ll need to get started.

• Debian OS (Debian 10 or 11 is recommended)
• 2GB of RAM or more (The more devices you manage, the more RAM you’ll need)
• 5GB of Disk Space for the UniFi Controller (more if you plan to keep logs and backups)
• A Static IP Address (optional but recommended)
• Server Access (SSH or direct console access)
• Basic Linux Skills (copy/paste works too)
• Time (setup takes about 30-60 minutes)

Step 1: Update Debian OS

Before anything, make sure your system is up to date. Outdated software can cause issues down the line.

sudo apt update && sudo apt upgrade -y

This will ensure you have the latest security patches and system improvements.

Step 2: Install Required Packages

You need some essential packages to make the UniFi controller work. Let’s install them.

sudo apt install wget gnupg ca-certificates -y

This installs tools like "wget" (for downloads) and "gnupg" (for verifying package authenticity).

Step 3: Add the UniFi Repository

The UniFi controller isn’t available in standard Debian repositories. So, we need to add Ubiquiti's repository.

# Add the GPG key

wget -qO - https://dl.ui.com/unifi/unifi-repo.gpg | sudo tee 

/usr/share/keyrings/unifi-repo.gpg > /dev/null

# Add the UniFi repository to the package list

echo 'deb [signed-by=/usr/share/keyrings/unifi-repo.gpg] 

https://www.ui.com/downloads/unifi/debian stable ubiquiti' | sudo tee 

/etc/apt/sources.list.d/unifi.list

This tells Debian where to find UniFi software packages and how to trust them.

Step 4: Install UniFi Controller

Now, it’s time to install the controller itself.

sudo apt update

sudo apt install unifi -y

This will download and install the UniFi controller. Once it's done, you’ll have a web server running on port "8443".

Step 5: Configure Java (Optional)

The UniFi controller runs on Java, but Debian usually handles it for you. If not, install OpenJDK.

sudo apt install openjdk-11-jre-headless -y

Check that Java is working correctly.

java -version

If you see something like `openjdk version "11.x.x", you’re good to go.

Step 6: Start and Enable the UniFi Service

After installation, the UniFi service should start automatically. If not, run these commands to get it going and ensure it starts on boot.

sudo systemctl start unifi

sudo systemctl enable unifi

To check the service status:

sudo systemctl status unifi

You should see "active (running)" in green.

Step 7: Access the UniFi Web Interface

The UniFi controller runs on port "8443", so you’ll access it through your web browser.

1. Open your browser and go to:

   https://<server-ip>:8443
   

2. You’ll see a security warning. This is normal since the certificate is self-signed. Proceed to the page.
3. Follow the setup wizard to create your UniFi controller admin account.
4. Enable "Remote Access" (optional but recommended if you want access from anywhere).
5. Configure basic network settings and adopt your UniFi devices.

Step 8: Adopt UniFi Devices

Your UniFi devices (Access Points, Switches, etc.) will need to be "adopted" by the controller.

How to Adopt a Device

1. Connect the device to the same network as the server.
2. Open the UniFi web interface.
3. You should see the device listed as “Pending Adoption.”
4. Click "Adopt" and wait for it to configure.

Tip: If the device is not showing up, try resetting it to factory settings.

Step 9: Secure Your UniFi Controller

You don’t want your controller exposed to the world, so follow these tips to secure it.

1. Change the Default Ports - Hackers scan common ports like "8443". Change this in the UniFi controller settings.
2. Enable SSL - Use Let's Encrypt for a proper SSL certificate.
3. Backup Regularly - You can set this up in the controller settings.
4. Use a Strong Admin Password - Don’t leave it as "admin/admin" (duh!).
5. Set Up a Firewall - Block unwanted traffic to port "8443".

Managing the UniFi Controller

Here are some essential commands to manage your UniFi controller.

# Check if the UniFi service is running

sudo systemctl status unifi

# Start/Stop/Restart the controller

sudo systemctl start unifi

sudo systemctl stop unifi

sudo systemctl restart unifi

# Check the controller logs

sudo tail -f /var/log/unifi/server.log

Updating the Controller

To keep everything running smoothly, keep your UniFi controller up to date.

sudo apt update

sudo apt upgrade -y

Check if UniFi is up to date:

sudo apt list --upgradable

If there’s a new version of the UniFi package, it will show up here.

Troubleshooting

Here are common issues and how to fix them.

1. Can't Access the Web Interface

• Check if the UniFi service is running:

  sudo systemctl status unifi
  

• Ensure the firewall allows port "8443":

  sudo ufw allow 8443
  

Why Use UniHosted Instead?

If you don't want the hassle of self-hosting, UniHosted offers fully managed UniFi controllers. We handle:

• Backups - No more worrying about lost configs.
• Updates - Always up-to-date.
• Security - We handle security patches.
• Instant Setup - No need to mess with Debian commands.

With UniHosted, you get all the power of a self-hosted controller, without the maintenance. Learn more at UniHosted.

Frequently Asked Questions

1. Can I run UniFi on Raspberry Pi?

Yes, but the performance will be limited. You’ll want at least 2GB of RAM.

2. How many devices can a self-hosted controller handle?

With 2GB of RAM, you can manage 20-30 devices. With 4GB of RAM, you can manage 50+ devices.

3. Can I run UniFi in a Docker container?

Yes! But you’ll need to set up Docker and use the "jacobalberty/unifi" image.

Final Thoughts

Setting up a self-hosted UniFi Controller on Debian is a great way to take control of your network. You’ll save money, improve your privacy, and gain valuable server skills. Follow the steps in this guide, and you’ll be up and running in no time.

If you’d rather avoid the hassle, UniHosted offers a managed UniFi solution with instant setup, backups, and security updates. If you would like me to personally walk you through UniHosted, you can schedule a call with me here.