jokester/ansible-playbooks
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add UniFi Network Controller role

Browse Source
This commit is contained in:
Clément Désiles
2026-07-03 00:09:02 +02:00
parent 501f4e1f87
commit 75d6aae668
6 changed files with 267 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
roles/unifi/README.md
+48
View File
@@ -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
+24
View File
@@ -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
+19
View File
@@ -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
+3
View File
@@ -0,0 +1,3 @@
---
dependencies:
- role: podman
roles/unifi/tasks/main.yml
+117
View File
@@ -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
+56
View File
@@ -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;
}
}