Unifi Controller

UniFi Network Controller is centralized management software for Ubiquiti UniFi devices

Network management🟡 intermediate16 min⏱️ 15-30 minutes

UniFi Network Controller is a free and open-source Network Management. Centralized management software for Ubiquiti UniFi devices

1. Prerequisites

  • Hardware Requirements:
  • CPU: 2 cores minimum (4+ cores recommended)
  • RAM: 2GB minimum (4GB+ recommended for production)
  • Storage: 10GB minimum
  • Network: 8443 ports required
  • Operating System:
  • Linux: Any modern distribution (RHEL, Debian, Ubuntu, CentOS, Fedora, Arch, Alpine, openSUSE)
  • macOS: 10.14+ (Mojave or newer)
  • Windows: Windows Server 2016+ or Windows 10 Pro
  • FreeBSD: 11.0+
  • Network Requirements:
  • Port 8443 (default unifi-network-controller port)
  • Firewall rules configured
  • Dependencies:
  • mongodb, openjdk-11-jre-headless
  • System Access: root or sudo privileges required
  • 2. Supported Operating Systems

    This guide supports installation on:

  • RHEL 8/9 and derivatives (CentOS Stream, Rocky Linux, AlmaLinux)
  • Debian 11/12
  • Ubuntu 20.04/22.04/24.04 LTS
  • Arch Linux (rolling release)
  • Alpine Linux 3.18+
  • openSUSE Leap 15.5+ / Tumbleweed
  • SUSE Linux Enterprise Server (SLES) 15+
  • macOS 12+ (Monterey and later)
  • FreeBSD 13+
  • Windows 10/11/Server 2019+ (where applicable)
  • 3. Installation

    RHEL/CentOS/Rocky Linux/AlmaLinux

    bash
    # Install EPEL repository if needed
    sudo dnf install -y epel-release
    
    # Install unifi-network-controller
    sudo dnf install -y unifi-network-controller mongodb, openjdk-11-jre-headless
    
    # Enable and start service
    sudo systemctl enable --now unifi
    
    # Configure firewall
    sudo firewall-cmd --permanent --add-service=unifi-network-controller || \
      sudo firewall-cmd --permanent --add-port={default_port}/tcp
    sudo firewall-cmd --reload
    
    # Verify installation
    unifi-network-controller --version || systemctl status unifi

    Debian/Ubuntu

    bash
    # Update package index
    sudo apt update
    
    # Install unifi-network-controller
    sudo apt install -y unifi-network-controller mongodb, openjdk-11-jre-headless
    
    # Enable and start service
    sudo systemctl enable --now unifi
    
    # Configure firewall
    sudo ufw allow 8443
    
    # Verify installation
    unifi-network-controller --version || systemctl status unifi

    Arch Linux

    bash
    # Install unifi-network-controller
    sudo pacman -S unifi-network-controller
    
    # Enable and start service
    sudo systemctl enable --now unifi
    
    # Verify installation
    unifi-network-controller --version || systemctl status unifi

    Alpine Linux

    bash
    # Install unifi-network-controller
    apk add --no-cache unifi-network-controller
    
    # Enable and start service
    rc-update add unifi default
    rc-service unifi start
    
    # Verify installation
    unifi-network-controller --version || rc-service unifi status

    openSUSE/SLES

    bash
    # Install unifi-network-controller
    sudo zypper install -y unifi-network-controller mongodb, openjdk-11-jre-headless
    
    # Enable and start service
    sudo systemctl enable --now unifi
    
    # Configure firewall
    sudo firewall-cmd --permanent --add-service=unifi-network-controller || \
      sudo firewall-cmd --permanent --add-port={default_port}/tcp
    sudo firewall-cmd --reload
    
    # Verify installation
    unifi-network-controller --version || systemctl status unifi

    macOS

    bash
    # Using Homebrew
    brew install unifi-network-controller
    
    # Start service
    brew services start unifi-network-controller
    
    # Verify installation
    unifi-network-controller --version

    FreeBSD

    bash
    # Using pkg
    pkg install unifi-network-controller
    
    # Enable in rc.conf
    echo 'unifi_enable="YES"' >> /etc/rc.conf
    
    # Start service
    service unifi start
    
    # Verify installation
    unifi-network-controller --version || service unifi status

    Windows

    powershell
    # Using Chocolatey
    choco install unifi-network-controller
    
    # Or using Scoop
    scoop install unifi-network-controller
    
    # Verify installation
    unifi-network-controller --version

    Initial Configuration

    Basic Configuration

    bash
    # Create configuration directory if needed
    sudo mkdir -p /var/lib/unifi
    
    # Set up basic configuration
    sudo tee /var/lib/unifi/unifi-network-controller.conf << 'EOF'
    # UniFi Network Controller Configuration
    -Xms1024M -Xmx2048M
    EOF
    
    # Set appropriate permissions
    sudo chown -R unifi-network-controller:unifi-network-controller /var/lib/unifi || \
      sudo chown -R $(whoami):$(whoami) /var/lib/unifi
    
    # Test configuration
    sudo unifi-network-controller --test || sudo unifi configtest

    Security Hardening

    bash
    # Create dedicated user (if not created by package)
    sudo useradd --system --shell /bin/false unifi-network-controller || true
    
    # Secure configuration files
    sudo chmod 750 /var/lib/unifi
    sudo chmod 640 /var/lib/unifi/*.conf
    
    # Enable security features
    # See security section for detailed hardening steps

    5. Service Management

    systemd (RHEL, Debian, Ubuntu, Arch, openSUSE)

    bash
    # Enable service
    sudo systemctl enable unifi
    
    # Start service
    sudo systemctl start unifi
    
    # Stop service
    sudo systemctl stop unifi
    
    # Restart service
    sudo systemctl restart unifi
    
    # Reload configuration
    sudo systemctl reload unifi
    
    # Check status
    sudo systemctl status unifi
    
    # View logs
    sudo journalctl -u unifi -f

    OpenRC (Alpine Linux)

    bash
    # Enable service
    rc-update add unifi default
    
    # Start service
    rc-service unifi start
    
    # Stop service
    rc-service unifi stop
    
    # Restart service
    rc-service unifi restart
    
    # Check status
    rc-service unifi status
    
    # View logs
    tail -f /var/log/unifi/unifi.log

    rc.d (FreeBSD)

    bash
    # Enable in /etc/rc.conf
    echo 'unifi_enable="YES"' >> /etc/rc.conf
    
    # Start service
    service unifi start
    
    # Stop service
    service unifi stop
    
    # Restart service
    service unifi restart
    
    # Check status
    service unifi status

    launchd (macOS)

    bash
    # Using Homebrew services
    brew services start unifi-network-controller
    brew services stop unifi-network-controller
    brew services restart unifi-network-controller
    
    # Check status
    brew services list | grep unifi-network-controller
    
    # View logs
    tail -f $(brew --prefix)/var/log/unifi-network-controller.log

    Windows Service Manager

    powershell
    # Start service
    net start unifi
    
    # Stop service
    net stop unifi
    
    # Using PowerShell
    Start-Service unifi
    Stop-Service unifi
    Restart-Service unifi
    
    # Check status
    Get-Service unifi
    
    # Set to automatic startup
    Set-Service unifi -StartupType Automatic

    Advanced Configuration

    Performance Optimization

    bash
    # Configure performance settings
    cat >> /var/lib/unifi/unifi-network-controller.conf << 'EOF'
    # Performance tuning
    -Xms1024M -Xmx2048M
    EOF
    
    # Apply system tuning
    sudo sysctl -w net.core.somaxconn=65535
    sudo sysctl -w net.ipv4.tcp_max_syn_backlog=65535
    echo "vm.swappiness=10" | sudo tee -a /etc/sysctl.conf
    sudo sysctl -p
    
    # Restart service to apply changes
    sudo systemctl restart unifi

    High Availability Setup

    bash
    # Configure clustering/HA (if supported)
    # This varies greatly by tool - see official documentation
    
    # Example load balancing configuration
    # Configure multiple instances on different ports
    # Use HAProxy or nginx for load balancing

    Reverse Proxy Setup

    nginx Configuration

    nginx
    upstream unifi-network-controller_backend {
        server 127.0.0.1:8443;
        keepalive 32;
    }
    
    server {
        listen 80;
        server_name unifi-network-controller.example.com;
        return 301 https://$server_name$request_uri;
    }
    
    server {
        listen 443 ssl http2;
        server_name unifi-network-controller.example.com;
    
        ssl_certificate /etc/ssl/certs/unifi-network-controller.crt;
        ssl_certificate_key /etc/ssl/private/unifi-network-controller.key;
    
        # Security headers
        add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
        add_header X-Content-Type-Options nosniff;
        add_header X-Frame-Options SAMEORIGIN;
        add_header X-XSS-Protection "1; mode=block";
    
        location / {
            proxy_pass http://unifi-network-controller_backend;
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header X-Forwarded-Proto $scheme;
            
            # WebSocket support (if needed)
            proxy_http_version 1.1;
            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection "upgrade";
            
            # Timeouts
            proxy_connect_timeout 60s;
            proxy_send_timeout 60s;
            proxy_read_timeout 60s;
        }
    }

    Apache Configuration

    apache
    <VirtualHost *:80>
        ServerName unifi-network-controller.example.com
        Redirect permanent / https://unifi-network-controller.example.com/
    </VirtualHost>
    
    <VirtualHost *:443>
        ServerName unifi-network-controller.example.com
        
        SSLEngine on
        SSLCertificateFile /etc/ssl/certs/unifi-network-controller.crt
        SSLCertificateKeyFile /etc/ssl/private/unifi-network-controller.key
        
        # Security headers
        Header always set Strict-Transport-Security "max-age=31536000; includeSubDomains"
        Header always set X-Content-Type-Options nosniff
        Header always set X-Frame-Options SAMEORIGIN
        Header always set X-XSS-Protection "1; mode=block"
        
        ProxyRequests Off
        ProxyPreserveHost On
        
        <Location />
            ProxyPass http://127.0.0.1:8443/
            ProxyPassReverse http://127.0.0.1:8443/
        </Location>
        
        # WebSocket support (if needed)
        RewriteEngine on
        RewriteCond %{HTTP:Upgrade} websocket [NC]
        RewriteCond %{HTTP:Connection} upgrade [NC]
        RewriteRule ^/?(.*) "ws://127.0.0.1:8443/$1" [P,L]
    </VirtualHost>

    HAProxy Configuration

    haproxy
    global
        maxconn 4096
        log /dev/log local0
        chroot /var/lib/haproxy
        user haproxy
        group haproxy
        daemon
    
    defaults
        log global
        mode http
        option httplog
        option dontlognull
        timeout connect 5000
        timeout client 50000
        timeout server 50000
    
    frontend unifi-network-controller_frontend
        bind *:80
        bind *:443 ssl crt /etc/ssl/certs/unifi-network-controller.pem
        redirect scheme https if !{ ssl_fc }
        
        # Security headers
        http-response set-header Strict-Transport-Security "max-age=31536000; includeSubDomains"
        http-response set-header X-Content-Type-Options nosniff
        http-response set-header X-Frame-Options SAMEORIGIN
        http-response set-header X-XSS-Protection "1; mode=block"
        
        default_backend unifi-network-controller_backend
    
    backend unifi-network-controller_backend
        balance roundrobin
        option httpchk GET /health
        server unifi-network-controller1 127.0.0.1:8443 check

    Caddy Configuration

    caddy
    unifi-network-controller.example.com {
        reverse_proxy 127.0.0.1:8443 {
            header_up Host {upstream_hostport}
            header_up X-Real-IP {remote}
            header_up X-Forwarded-For {remote}
            header_up X-Forwarded-Proto {scheme}
        }
        
        header {
            Strict-Transport-Security "max-age=31536000; includeSubDomains"
            X-Content-Type-Options nosniff
            X-Frame-Options SAMEORIGIN
            X-XSS-Protection "1; mode=block"
        }
        
        encode gzip
    }

    Security Configuration

    Basic Security Setup

    bash
    # Create dedicated user
    sudo useradd --system --shell /bin/false --home /var/lib/unifi unifi-network-controller || true
    
    # Set ownership
    sudo chown -R unifi-network-controller:unifi-network-controller /var/lib/unifi
    sudo chown -R unifi-network-controller:unifi-network-controller /var/log/unifi
    
    # Set permissions
    sudo chmod 750 /var/lib/unifi
    sudo chmod 640 /var/lib/unifi/*
    sudo chmod 750 /var/log/unifi
    
    # Configure firewall (UFW)
    sudo ufw allow from any to any port 8443 proto tcp comment "UniFi Network Controller"
    
    # Configure firewall (firewalld)
    sudo firewall-cmd --permanent --new-service=unifi-network-controller
    sudo firewall-cmd --permanent --service=unifi-network-controller --add-port={default_port}/tcp
    sudo firewall-cmd --permanent --add-service=unifi-network-controller
    sudo firewall-cmd --reload
    
    # SELinux configuration (if enabled)
    sudo setsebool -P httpd_can_network_connect on
    sudo semanage port -a -t http_port_t -p tcp 8443 || true

    SSL/TLS Configuration

    bash
    # Generate self-signed certificate (for testing)
    sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
        -keyout /etc/ssl/private/unifi-network-controller.key \
        -out /etc/ssl/certs/unifi-network-controller.crt \
        -subj "/C=US/ST=State/L=City/O=Organization/CN=unifi-network-controller.example.com"
    
    # Set proper permissions
    sudo chmod 600 /etc/ssl/private/unifi-network-controller.key
    sudo chmod 644 /etc/ssl/certs/unifi-network-controller.crt
    
    # For production, use Let's Encrypt
    sudo certbot certonly --standalone -d unifi-network-controller.example.com

    Fail2ban Configuration

    ini
    # /etc/fail2ban/jail.d/unifi-network-controller.conf
    [unifi-network-controller]
    enabled = true
    port = 8443
    filter = unifi-network-controller
    logpath = /var/log/unifi/*.log
    maxretry = 5
    bantime = 3600
    findtime = 600
    ini
    # /etc/fail2ban/filter.d/unifi-network-controller.conf
    [Definition]
    failregex = ^.*Failed login attempt.*from <HOST>.*$
                ^.*Authentication failed.*from <HOST>.*$
                ^.*Invalid credentials.*from <HOST>.*$
    ignoreregex =

    Database Setup

    PostgreSQL Backend (if applicable)

    bash
    # Create database and user
    sudo -u postgres psql << EOF
    CREATE DATABASE unifi-network-controller_db;
    CREATE USER unifi-network-controller_user WITH ENCRYPTED PASSWORD 'secure_password_here';
    GRANT ALL PRIVILEGES ON DATABASE unifi-network-controller_db TO unifi-network-controller_user;
    \q
    EOF
    
    # Configure connection in UniFi Network Controller
    echo "DATABASE_URL=postgresql://unifi-network-controller_user:secure_password_here@localhost/unifi-network-controller_db" | \
      sudo tee -a /var/lib/unifi/unifi-network-controller.env

    MySQL/MariaDB Backend (if applicable)

    bash
    # Create database and user
    sudo mysql << EOF
    CREATE DATABASE unifi-network-controller_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
    CREATE USER 'unifi-network-controller_user'@'localhost' IDENTIFIED BY 'secure_password_here';
    GRANT ALL PRIVILEGES ON unifi-network-controller_db.* TO 'unifi-network-controller_user'@'localhost';
    FLUSH PRIVILEGES;
    EOF
    
    # Configure connection
    echo "DATABASE_URL=mysql://unifi-network-controller_user:secure_password_here@localhost/unifi-network-controller_db" | \
      sudo tee -a /var/lib/unifi/unifi-network-controller.env

    SQLite Backend (if applicable)

    bash
    # Create database directory
    sudo mkdir -p /var/lib/unifi-network-controller
    sudo chown unifi-network-controller:unifi-network-controller /var/lib/unifi-network-controller
    
    # Initialize database
    sudo -u unifi-network-controller unifi-network-controller init-db

    Performance Optimization

    System Tuning

    bash
    # Kernel parameters for better performance
    cat << 'EOF' | sudo tee -a /etc/sysctl.conf
    # Network performance tuning
    net.core.somaxconn = 65535
    net.ipv4.tcp_max_syn_backlog = 65535
    net.ipv4.ip_local_port_range = 1024 65535
    net.core.netdev_max_backlog = 5000
    net.ipv4.tcp_tw_reuse = 1
    
    # Memory tuning
    vm.swappiness = 10
    vm.dirty_ratio = 15
    vm.dirty_background_ratio = 5
    EOF
    
    # Apply settings
    sudo sysctl -p
    
    # Configure system limits
    cat << 'EOF' | sudo tee -a /etc/security/limits.conf
    unifi-network-controller soft nofile 65535
    unifi-network-controller hard nofile 65535
    unifi-network-controller soft nproc 32768
    unifi-network-controller hard nproc 32768
    EOF

    Application Tuning

    bash
    # Configure application-specific performance settings
    cat << 'EOF' | sudo tee -a /var/lib/unifi/performance.conf
    # Performance configuration
    -Xms1024M -Xmx2048M
    
    # Connection pooling
    max_connections = 1000
    connection_timeout = 30
    
    # Cache settings
    cache_size = 256M
    cache_ttl = 3600
    
    # Worker processes
    workers = 4
    threads_per_worker = 4
    EOF
    
    # Restart to apply settings
    sudo systemctl restart unifi

    Monitoring

    Prometheus Integration

    yaml
    # /etc/prometheus/prometheus.yml
    scrape_configs:
      - job_name: 'unifi-network-controller'
        static_configs:
          - targets: ['localhost:8443/metrics']
        metrics_path: '/metrics'
        scrape_interval: 30s

    Health Check Script

    bash
    #!/bin/bash
    # /usr/local/bin/unifi-network-controller-health
    
    # Check if service is running
    if ! systemctl is-active --quiet unifi; then
        echo "CRITICAL: UniFi Network Controller service is not running"
        exit 2
    fi
    
    # Check if port is listening
    if ! nc -z localhost 8443 2>/dev/null; then
        echo "CRITICAL: UniFi Network Controller is not listening on port 8443"
        exit 2
    fi
    
    # Check response time
    response_time=$(curl -o /dev/null -s -w '%{time_total}' http://localhost:8443/health || echo "999")
    if (( $(echo "$response_time > 5" | bc -l) )); then
        echo "WARNING: Slow response time: ${response_time}s"
        exit 1
    fi
    
    echo "OK: UniFi Network Controller is healthy (response time: ${response_time}s)"
    exit 0

    Log Monitoring

    bash
    # Configure log rotation
    cat << 'EOF' | sudo tee /etc/logrotate.d/unifi-network-controller
    /var/log/unifi/*.log {
        daily
        rotate 14
        compress
        delaycompress
        missingok
        notifempty
        create 0640 unifi-network-controller unifi-network-controller
        postrotate
            systemctl reload unifi > /dev/null 2>&1 || true
        endscript
    }
    EOF
    
    # Test log rotation
    sudo logrotate -d /etc/logrotate.d/unifi-network-controller

    9. Backup and Restore

    Backup Script

    bash
    #!/bin/bash
    # /usr/local/bin/unifi-network-controller-backup
    
    BACKUP_DIR="/backup/unifi-network-controller"
    DATE=$(date +%Y%m%d_%H%M%S)
    BACKUP_FILE="$BACKUP_DIR/unifi-network-controller_backup_$DATE.tar.gz"
    
    # Create backup directory
    mkdir -p "$BACKUP_DIR"
    
    # Stop service (if needed for consistency)
    echo "Stopping UniFi Network Controller service..."
    systemctl stop unifi
    
    # Backup configuration
    echo "Backing up configuration..."
    tar -czf "$BACKUP_FILE" \
        /var/lib/unifi \
        /var/lib/unifi-network-controller \
        /var/log/unifi
    
    # Backup database (if applicable)
    if command -v pg_dump &> /dev/null; then
        echo "Backing up database..."
        sudo -u postgres pg_dump unifi-network-controller_db | gzip > "$BACKUP_DIR/unifi-network-controller_db_$DATE.sql.gz"
    fi
    
    # Start service
    echo "Starting UniFi Network Controller service..."
    systemctl start unifi
    
    # Clean old backups (keep 30 days)
    find "$BACKUP_DIR" -name "*.tar.gz" -mtime +30 -delete
    find "$BACKUP_DIR" -name "*.sql.gz" -mtime +30 -delete
    
    echo "Backup completed: $BACKUP_FILE"

    Restore Script

    bash
    #!/bin/bash
    # /usr/local/bin/unifi-network-controller-restore
    
    if [ $# -ne 1 ]; then
        echo "Usage: $0 <backup_file>"
        exit 1
    fi
    
    BACKUP_FILE="$1"
    
    if [ ! -f "$BACKUP_FILE" ]; then
        echo "Error: Backup file not found: $BACKUP_FILE"
        exit 1
    fi
    
    # Stop service
    echo "Stopping UniFi Network Controller service..."
    systemctl stop unifi
    
    # Restore files
    echo "Restoring from backup..."
    tar -xzf "$BACKUP_FILE" -C /
    
    # Restore database (if applicable)
    DB_BACKUP=$(echo "$BACKUP_FILE" | sed 's/.tar.gz$/_db.sql.gz/')
    if [ -f "$DB_BACKUP" ]; then
        echo "Restoring database..."
        zcat "$DB_BACKUP" | sudo -u postgres psql unifi-network-controller_db
    fi
    
    # Fix permissions
    chown -R unifi-network-controller:unifi-network-controller /var/lib/unifi
    chown -R unifi-network-controller:unifi-network-controller /var/lib/unifi-network-controller
    
    # Start service
    echo "Starting UniFi Network Controller service..."
    systemctl start unifi
    
    echo "Restore completed successfully"

    6. Troubleshooting

    Common Issues

    1. Service won't start:

    bash
    # Check service status and logs
    sudo systemctl status unifi
    sudo journalctl -u unifi -n 100 --no-pager
    
    # Check for port conflicts
    sudo ss -tlnp | grep 8443
    sudo lsof -i :8443
    
    # Verify configuration
    sudo unifi-network-controller --test || sudo unifi configtest
    
    # Check permissions
    ls -la /var/lib/unifi
    ls -la /var/log/unifi

    2. Cannot access web interface:

    bash
    # Check if service is listening
    sudo ss -tlnp | grep unifi
    curl -I http://localhost:8443
    
    # Check firewall rules
    sudo firewall-cmd --list-all
    sudo iptables -L -n | grep 8443
    
    # Check SELinux (if enabled)
    getenforce
    sudo ausearch -m avc -ts recent | grep unifi-network-controller

    3. High memory/CPU usage:

    bash
    # Monitor resource usage
    top -p $(pgrep java)
    htop -p $(pgrep java)
    
    # Check for memory leaks
    ps aux | grep java
    cat /proc/$(pgrep java)/status | grep -i vm
    
    # Analyze logs for errors
    grep -i error /var/log/unifi/*.log | tail -50

    4. Database connection errors:

    bash
    # Test database connection
    psql -U unifi-network-controller_user -d unifi-network-controller_db -c "SELECT 1;"
    mysql -u unifi-network-controller_user -p unifi-network-controller_db -e "SELECT 1;"
    
    # Check database service
    sudo systemctl status postgresql
    sudo systemctl status mariadb

    Debug Mode

    bash
    # Enable debug logging
    echo "debug = true" | sudo tee -a /var/lib/unifi/unifi-network-controller.conf
    
    # Restart with debug mode
    sudo systemctl stop unifi
    sudo -u unifi-network-controller unifi-network-controller --debug
    
    # Watch debug logs
    tail -f /var/log/unifi/debug.log

    Performance Analysis

    bash
    # Profile CPU usage
    sudo perf record -p $(pgrep java) sleep 30
    sudo perf report
    
    # Analyze network traffic
    sudo tcpdump -i any -w /tmp/unifi-network-controller.pcap port 8443
    sudo tcpdump -r /tmp/unifi-network-controller.pcap -nn
    
    # Monitor disk I/O
    sudo iotop -p $(pgrep java)

    Integration Examples

    Docker Deployment

    yaml
    # docker-compose.yml
    version: '3.8'
    
    services:
      unifi-network-controller:
        image: unifi-network-controller:unifi-network-controller
        container_name: unifi-network-controller
        restart: unless-stopped
        ports:
          - "8443:8443"
        environment:
          - TZ=UTC
          - PUID=1000
          - PGID=1000
        volumes:
          - ./config:/var/lib/unifi
          - ./data:/var/lib/unifi-network-controller
          - ./logs:/var/log/unifi
        networks:
          - unifi-network-controller_network
        healthcheck:
          test: ["CMD", "curl", "-f", "http://localhost:8443/health"]
          interval: 30s
          timeout: 10s
          retries: 3
    
    networks:
      unifi-network-controller_network:
        driver: bridge

    Kubernetes Deployment

    yaml
    # unifi-network-controller-deployment.yaml
    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: unifi-network-controller
      labels:
        app: unifi-network-controller
    spec:
      replicas: 1
      selector:
        matchLabels:
          app: unifi-network-controller
      template:
        metadata:
          labels:
            app: unifi-network-controller
        spec:
          containers:
          - name: unifi-network-controller
            image: unifi-network-controller:unifi-network-controller
            ports:
            - containerPort: 8443
            env:
            - name: TZ
              value: UTC
            volumeMounts:
            - name: config
              mountPath: /var/lib/unifi
            - name: data
              mountPath: /var/lib/unifi-network-controller
            livenessProbe:
              httpGet:
                path: /health
                port: 8443
              initialDelaySeconds: 30
              periodSeconds: 30
            readinessProbe:
              httpGet:
                path: /ready
                port: 8443
              initialDelaySeconds: 5
              periodSeconds: 10
          volumes:
          - name: config
            configMap:
              name: unifi-network-controller-config
          - name: data
            persistentVolumeClaim:
              claimName: unifi-network-controller-data
    ---
    apiVersion: v1
    kind: Service
    metadata:
      name: unifi-network-controller
    spec:
      selector:
        app: unifi-network-controller
      ports:
      - protocol: TCP
        port: 8443
        targetPort: 8443
      type: LoadBalancer
    ---
    apiVersion: v1
    kind: PersistentVolumeClaim
    metadata:
      name: unifi-network-controller-data
    spec:
      accessModes:
        - ReadWriteOnce
      resources:
        requests:
          storage: 10Gi

    Ansible Playbook

    yaml
    ---
    # unifi-network-controller-playbook.yml
    - name: Install and configure UniFi Network Controller
      hosts: all
      become: yes
      vars:
        unifi-network-controller_version: latest
        unifi-network-controller_port: 8443
        unifi-network-controller_config_dir: /var/lib/unifi
      
      tasks:
        - name: Install dependencies
          package:
            name:
              - mongodb, openjdk-11-jre-headless
            state: present
        
        - name: Install UniFi Network Controller
          package:
            name: unifi-network-controller
            state: present
        
        - name: Create configuration directory
          file:
            path: "{{ unifi-network-controller_config_dir }}"
            state: directory
            owner: unifi-network-controller
            group: unifi-network-controller
            mode: '0750'
        
        - name: Deploy configuration
          template:
            src: unifi-network-controller.conf.j2
            dest: "{{ unifi-network-controller_config_dir }}/unifi-network-controller.conf"
            owner: unifi-network-controller
            group: unifi-network-controller
            mode: '0640'
          notify: restart unifi-network-controller
        
        - name: Start and enable service
          systemd:
            name: unifi
            state: started
            enabled: yes
            daemon_reload: yes
        
        - name: Configure firewall
          firewalld:
            port: "{{ unifi-network-controller_port }}/tcp"
            permanent: yes
            immediate: yes
            state: enabled
      
      handlers:
        - name: restart unifi-network-controller
          systemd:
            name: unifi
            state: restarted

    Terraform Configuration

    hcl
    # unifi-network-controller.tf
    resource "aws_instance" "unifi-network-controller_server" {
      ami           = var.ami_id
      instance_type = "t3.medium"
      
      vpc_security_group_ids = [aws_security_group.unifi-network-controller.id]
      
      user_data = <<-EOF
        #!/bin/bash
        # Install UniFi Network Controller
        apt-get update
        apt-get install -y unifi-network-controller mongodb, openjdk-11-jre-headless
        
        # Configure UniFi Network Controller
        systemctl enable unifi
        systemctl start unifi
      EOF
      
      tags = {
        Name = "UniFi Network Controller Server"
        Application = "UniFi Network Controller"
      }
    }
    
    resource "aws_security_group" "unifi-network-controller" {
      name        = "unifi-network-controller-sg"
      description = "Security group for UniFi Network Controller"
      
      ingress {
        from_port   = 8443
        to_port     = 8443
        protocol    = "tcp"
        cidr_blocks = ["0.0.0.0/0"]
      }
      
      egress {
        from_port   = 0
        to_port     = 0
        protocol    = "-1"
        cidr_blocks = ["0.0.0.0/0"]
      }
      
      tags = {
        Name = "UniFi Network Controller Security Group"
      }
    }

    Maintenance

    Update Procedures

    bash
    # RHEL/CentOS/Rocky/AlmaLinux
    sudo dnf check-update unifi-network-controller
    sudo dnf update unifi-network-controller
    
    # Debian/Ubuntu
    sudo apt update
    sudo apt upgrade unifi-network-controller
    
    # Arch Linux
    sudo pacman -Syu unifi-network-controller
    
    # Alpine Linux
    apk update
    apk upgrade unifi-network-controller
    
    # openSUSE
    sudo zypper ref
    sudo zypper update unifi-network-controller
    
    # FreeBSD
    pkg update
    pkg upgrade unifi-network-controller
    
    # Always backup before updates
    /usr/local/bin/unifi-network-controller-backup
    
    # Restart after updates
    sudo systemctl restart unifi

    Regular Maintenance Tasks

    bash
    # Clean old logs
    find /var/log/unifi -name "*.log" -mtime +30 -delete
    
    # Vacuum database (if PostgreSQL)
    sudo -u postgres vacuumdb --analyze unifi-network-controller_db
    
    # Check disk usage
    df -h | grep -E "(/$|unifi-network-controller)"
    du -sh /var/lib/unifi-network-controller
    
    # Update security patches
    sudo unattended-upgrade -d
    
    # Review security logs
    sudo aureport --summary
    sudo journalctl -u unifi | grep -i "error\|fail\|deny"

    Health Monitoring Checklist

  • [ ] Service is running and enabled
  • [ ] Web interface is accessible
  • [ ] Database connections are healthy
  • [ ] Disk usage is below 80%
  • [ ] No critical errors in logs
  • [ ] Backups are running successfully
  • [ ] SSL certificates are valid
  • [ ] Security updates are applied
  • Additional Resources

  • Official Documentation: https://docs.unifi-network-controller.org/
  • GitHub Repository: https://github.com/unifi-network-controller/unifi-network-controller
  • Community Forum: https://forum.unifi-network-controller.org/
  • Wiki: https://wiki.unifi-network-controller.org/
  • Docker Hub: https://hub.docker.com/r/unifi-network-controller/unifi-network-controller
  • Security Advisories: https://security.unifi-network-controller.org/
  • Best Practices: https://docs.unifi-network-controller.org/best-practices
  • API Documentation: https://api.unifi-network-controller.org/
  • Comparison with PRTG, Zabbix, LibreNMS, Observium: https://docs.unifi-network-controller.org/comparison
  • ---

    Note: This guide is part of the HowToMgr collection. Always refer to official documentation for the most up-to-date information.