Add UniFi Network Controller role

roles/unifi/README.md

@@ -0,0 +1,48 @@
+# UniFi Controller
+
+Deploys the [UniFi Network Controller](https://ui.com/) via rootless Podman using the [`jacobalberty/unifi`](https://github.com/jacobalberty/unifi-docker) image (embedded MongoDB, no external DB required).
+
+## Configuration
+
+See [defaults/main.yml](defaults/main.yml) for all variables.
+
+### Required variables (inventory)
+
+| Variable | Description | Example |
+|---|---|---|
+| `unifi_bind_address` | LAN IP for AP communication | `192.168.2.1` |
+
+### Optional variables
+
+| Variable | Description | Default |
+|---|---|---|
+| `unifi_admin_address` | Bind address for web UI (8443) | `unifi_bind_address` |
+
+Set `unifi_admin_address` to a WireGuard IP to restrict admin access to VPN only while keeping AP ports on the LAN.
+
+```yaml
+# Example: LAN for APs, VPN-only admin
+unifi_bind_address: 192.168.2.1     # lan1 — APs reach this
+unifi_admin_address: 192.168.20.4   # wg0 — admin via VPN only
+```
+
+## Firewall ports
+
+On `unifi_bind_address` (LAN):
+
+| Port | Protocol | Purpose |
+|---|---|---|
+| 8080 | TCP | Device inform |
+| 3478 | UDP | STUN |
+| 10001 | UDP | AP discovery |
+
+On `unifi_admin_address` (defaults to `unifi_bind_address`):
+
+| Port | Protocol | Purpose |
+|---|---|---|
+| 8443 | TCP | Web UI |
+
+## AP adoption
+
+APs on the same L2 network discover the controller automatically via port 10001/udp. For L3 adoption, configure the AP inform URL: `http://<unifi_bind_address>:8080/inform`.
+

roles/unifi/defaults/main.yml

@@ -0,0 +1,24 @@
+---
+# UniFi Controller version to deploy
+unifi_version: "latest"
+
+# Container image
+unifi_image: docker.io/jacobalberty/unifi
+
+# Storage location for persistent data (MongoDB, config, backups)
+unifi_data_dir: "{{ podman_projects_dir }}/unifi/data"
+
+# Network binding — REQUIRED, must be set in inventory
+# IP address of the LAN interface for AP communication (inform, STUN, discovery).
+# APs must be able to reach this address.
+# unifi_bind_address: ""
+
+# Firewall — sources allowed to reach UniFi ports
+unifi_firewall_allowed_sources:
+  - 192.168.0.0/16
+
+# Timezone
+unifi_timezone: UTC
+
+# JVM configuration
+unifi_jvm_max_heap_size: 1024M

roles/unifi/handlers/main.yml

@@ -0,0 +1,19 @@
+---
+- name: Reload systemd
+  ansible.builtin.systemd:
+    daemon_reload: true
+
+- name: Reload systemd user
+  ansible.builtin.systemd:
+    daemon_reload: true
+    scope: user
+  become: false
+  become_user: "{{ ansible_user }}"
+
+- name: Restart unifi
+  ansible.builtin.systemd:
+    name: unifi.service
+    state: restarted
+    scope: user
+  become: false
+  become_user: "{{ ansible_user }}"

roles/unifi/meta/main.yml

@@ -0,0 +1,3 @@
+---
+dependencies:
+  - role: podman

roles/unifi/tasks/main.yml

@@ -0,0 +1,117 @@
+---
+- name: Validate required variables are set
+  ansible.builtin.assert:
+    that:
+      - unifi_bind_address is defined
+      - unifi_bind_address | length > 0
+    fail_msg: |
+      unifi_bind_address is required (IP of the interface to bind to).
+      See roles/unifi/defaults/main.yml for configuration instructions.
+    success_msg: "Variable validation passed"
+
+- name: Create unifi project directory
+  ansible.builtin.file:
+    path: "{{ podman_projects_dir | default('/opt/podman') }}/unifi"
+    state: directory
+    owner: "{{ ansible_user }}"
+    group: "{{ ansible_user }}"
+    mode: "0755"
+
+- name: Create unifi data directory
+  ansible.builtin.file:
+    path: "{{ unifi_data_dir }}"
+    state: directory
+    owner: "{{ ansible_user }}"
+    group: "{{ ansible_user }}"
+    mode: "0755"
+
+- name: Pull UniFi container image
+  ansible.builtin.command: "podman pull {{ unifi_image }}:{{ unifi_version }}"
+  changed_when: pull_result.stdout is search('Writing manifest')
+  register: pull_result
+  become: false
+  become_user: "{{ ansible_user }}"
+
+- name: Deploy Kubernetes YAML for unifi
+  ansible.builtin.template:
+    src: unifi.yaml.j2
+    dest: "{{ podman_projects_dir | default('/opt/podman') }}/unifi/unifi.yaml"
+    owner: "{{ ansible_user }}"
+    group: "{{ ansible_user }}"
+    mode: "0644"
+  notify: Restart unifi
+
+- name: Get home directory for {{ ansible_user }}
+  ansible.builtin.getent:
+    database: passwd
+    key: "{{ ansible_user }}"
+
+- name: Set user home directory fact
+  ansible.builtin.set_fact:
+    user_home_dir: "{{ ansible_facts['getent_passwd'][ansible_user][4] }}"
+
+- name: Create systemd user directory for unifi
+  ansible.builtin.file:
+    path: "{{ user_home_dir }}/.config/systemd/user"
+    state: directory
+    owner: "{{ ansible_user }}"
+    group: "{{ ansible_user }}"
+    mode: "0755"
+
+- name: Create systemd service for unifi (user scope)
+  ansible.builtin.template:
+    src: unifi.service.j2
+    dest: "{{ user_home_dir }}/.config/systemd/user/unifi.service"
+    owner: "{{ ansible_user }}"
+    group: "{{ ansible_user }}"
+    mode: "0644"
+  notify: Reload systemd user
+
+- name: Enable lingering for user {{ ansible_user }}
+  ansible.builtin.command: "loginctl enable-linger {{ ansible_user }}"
+  when: ansible_user != 'root'
+
+- name: Setup firewall rules for UniFi (TCP)
+  community.general.ufw:
+    rule: allow
+    src: "{{ item.0 }}"
+    port: "{{ item.1.port }}"
+    proto: tcp
+    direction: in
+    comment: "UniFi {{ item.1.name }}"
+  loop: "{{ unifi_firewall_allowed_sources | product(unifi_tcp_ports) }}"
+  vars:
+    unifi_tcp_ports:
+      - { port: "8080", name: "device inform" }
+      - { port: "8443", name: "web interface" }
+  retries: 5
+  delay: 2
+  register: ufw_result
+  until: ufw_result is succeeded
+
+- name: Setup firewall rules for UniFi (UDP)
+  community.general.ufw:
+    rule: allow
+    src: "{{ item.0 }}"
+    port: "{{ item.1.port }}"
+    proto: udp
+    direction: in
+    comment: "UniFi {{ item.1.name }}"
+  loop: "{{ unifi_firewall_allowed_sources | product(unifi_udp_ports) }}"
+  vars:
+    unifi_udp_ports:
+      - { port: "3478", name: "STUN" }
+      - { port: "10001", name: "device discovery" }
+  retries: 5
+  delay: 2
+  register: ufw_result
+  until: ufw_result is succeeded
+
+- name: Enable and start unifi service (user scope)
+  ansible.builtin.systemd:
+    name: unifi.service
+    enabled: true
+    state: started
+    scope: user
+  become: false
+  become_user: "{{ ansible_user }}"

roles/unifi/templates/nginx-vhost.conf.j2

@@ -0,0 +1,56 @@
+# UniFi Controller vhost with Let's Encrypt (Certbot)
+# Managed by Ansible - DO NOT EDIT MANUALLY
+
+server {
+    listen 80;
+    listen [::]:80;
+    server_name {{ unifi_nginx_hostname }};
+
+    # Certbot webroot for ACME challenges
+    location /.well-known/acme-challenge/ {
+        root /var/www/certbot;
+    }
+
+    # Redirect to HTTPS
+    location / {
+        return 301 https://$server_name$request_uri;
+    }
+}
+
+server {
+    listen 443 ssl;
+    listen [::]:443 ssl;
+    server_name {{ unifi_nginx_hostname }};
+
+    # Let's Encrypt certificates (managed by Certbot)
+    ssl_certificate /etc/letsencrypt/live/{{ unifi_nginx_hostname }}/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/{{ unifi_nginx_hostname }}/privkey.pem;
+
+    # SSL configuration
+    ssl_protocols {{ nginx_ssl_protocols | default('TLSv1.3') }};
+    ssl_prefer_server_ciphers on;
+
+{% if nginx_log_backend | default('journald') == 'journald' %}
+    access_log syslog:server=unix:/dev/log,nohostname,tag=nginx_unifi;
+    error_log syslog:server=unix:/dev/log,nohostname,tag=nginx_unifi;
+{% else %}
+    access_log /var/log/nginx/{{ unifi_nginx_hostname }}_access.log main;
+    error_log /var/log/nginx/{{ unifi_nginx_hostname }}_error.log;
+{% endif %}
+
+    location / {
+        proxy_pass https://{{ unifi_bind_address }}:{{ unifi_port_https }};
+        proxy_set_header Host $http_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
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+
+        proxy_read_timeout 600s;
+        proxy_send_timeout 600s;
+    }
+}