Ubiquiti UniFi, Network Server on a VPS

Self hosted UniFi Network Server for an external portal

This is the architecture VoqadoWiFi’s own UniFi runbook recommends for groups: one Network Server on a small VPS, one site per venue, and access points at each venue that call home. No venue opens a port, and every location in the dashboard shares one controller address.

Print my UniFi settings All UniFi controllers

How do I run a self hosted UniFi controller for an external captive portal?

Install the UniFi Network Server on a VPS with a domain and certificate, open TCP 8443, TCP 8080 and UDP 3478, create one site per venue and adopt each venue’s access points over layer 3. Then set each site’s hotspot to External Portal Server www.voqadowifi.com and save the shared controller address with each site’s id in the dashboard.

At a glance

Controller address: https://unifi.example.com:8443
Login the integration uses: /api/login, no path prefix
Ports to open on the VPS: TCP 8443, TCP 8080, UDP 3478
Ports to open at each venue: None
Per venue in the dashboard: Only the site id differs

Checked against the VoqadoWiFi integration code on 7 October 2026. Controller menu labels move between firmware releases; the setting names above are the ones the setup wizard prints.

Step by step

Provision the VPS and install the Network Server
Use a current Ubuntu LTS image, give the server a domain name such as unifi.example.com, install the UniFi Network Server, and put a free automated certificate on it.
Open exactly three ports
TCP 8443 for management and the API, which is the address VoqadoWiFi calls for every guest and so must stay reachable from the internet; TCP 8080 for device inform; UDP 3478 for STUN. Keep the database bound to localhost.
Create one site per venue and note each id
UniFi generates an internal id for every new site, such as m8en8ejk. Only the first site is default, and renaming a site changes its display name, never its id. The id is the segment in /manage/site/<id>/.
Adopt each venue’s access points over layer 3
Either SSH to each access point and run set-inform http://unifi.example.com:8080/inform, or add a DNS record named unifi on the venue LAN that points at the server so factory reset access points find it. Then move each access point into its venue’s site.
Configure the hotspot per site
In each site, enable the hotspot portal on the guest SSID, choose External Portal Server with www.voqadowifi.com, add www.voqadowifi.com and voqadowifi.com to Pre-Authorization Access, and leave HTTPS Redirection off.
Create one local admin for the platform
Add a local admin with access to the Network application and no two factor prompt, for example voqado-portal. One account can serve every site it has access to.
Save each venue in the dashboard
Every location gets the same controller URL and the same login, and its own UniFi Site id. Test Connection lists every site as id and display name; click the venue’s site to fill the field.

What breaks on this controller

The display name in the site field

A location saved with the display name instead of the id fails on every guest. The guest entry route answers “No venue is linked to UniFi site” with the name it looked for, and authorize calls return api.err.NoSiteContext. Use Test Connection to pick the id.

Leaving out :8443

The Network Server answers on 8443. An address without the port reaches nothing on the server and Test Connection times out.

Account cannot see the site

If Test Connection succeeds but the venue’s site is missing from the list, the local admin has no access to that site. Grant it, then pick the site again.

Access points that lose their inform connection

An access point that stops reaching 8080 keeps broadcasting the SSID but stops being managed. Portal changes stop reaching it. Check that every site’s devices show as connected after any server change.

Why this is the recommended pattern for more than one venue

UniFi authorization uses a stored login, not a token, so VoqadoWiFi has to reach the Network application from the internet for every guest. With a controller at each venue that means a forwarded port or a tunnel per venue. With one server on a VPS, the controller is on the internet already and the venues only make outbound connections.

Onboarding a new venue becomes: create a site, adopt its access points, set the hotspot, add the location with the new site id. Nothing is installed at the venue except access points.

Ubiquiti’s Site Manager API at api.ui.com lists hosts and devices but cannot authorize guests, so it is not an alternative to a reachable Network application.

Questions

Does the integration need a valid certificate on the server?

No. It accepts self signed certificates by default, because UniFi controllers ship with them. A real certificate is still worth having for your own admin sessions.

Which console type should I choose?

Leave it on Auto-detect. A self hosted server answers the root of its address with a redirect to /manage, which the integration recognizes as the older controller and logs in at /api/login.

Can one login serve every venue?

Yes. The same local admin can authorize guests on every site it can access. Each location in the dashboard differs only by its site id.

What should I monitor?

That the service is up, that the disk has headroom, and that each site’s devices show as connected. Copy the controller’s automatic backups off the server.

Deeper reading

Longer articles from the blog that cover this controller. Where an article and this page disagree, this page is the one checked against the current integration.

One controller, every venue: UniFi on a VPS. Sizing, hardening and operations in more depth.
Guest VLAN segmentation
Guest bandwidth management

Keep reading

UniFi setup hub UniFi Cloud Key setup Portal loads but the WiFi never unlocks Walled garden domains

Sources: docs/unifi-setup-guide.md (Option A, ports, layer 3 adoption, site ids) and lib/unifi/api.ts, read on the date above. Ubiquiti and UniFi are trademarks of Ubiquiti Inc. VoqadoWiFi is not affiliated with or endorsed by either vendor.

Run your UniFi portal free

One location and 25 guest logins a month on the Starter plan, no card. The dashboard prints the finished portal URL for this controller.