Deploy and Host UniFi Network Application on Railway

Built for an LLM agent to deploy and use. The deploy form has no fields to fill: the controller's administrator password and the MongoDB passwords are generated at deploy time, the setup wizard is completed before the web interface opens, and the controller database lives on a volume. UniFi Network Application is Ubiquiti's controller for UniFi access points, switches and gateways: a self-hosted UniFi Controller with sites, networks, WiFi settings, clients and statistics, and a REST API that the web interface itself uses.

About Hosting UniFi Network Application

This template runs two services: unifi (the UniFi Network Application 10.6.109 from the LinuxServer.io image, with a volume at /config for the site data, backups and settings) and mongo (MongoDB 8.0 with a volume at /data/db). The controller listens for HTTPS only on port 8443 with a self-signed certificate, which Railway's edge cannot reach, so an nginx gateway inside the unifi container publishes it on the public domain over Railway's own certificate.

Ready from boot. A stock UniFi controller serves an open setup wizard, and the first visitor to the URL becomes its owner. This template creates the administrator admin with the generated UNIFI_ADMIN_PASSWORD and marks the controller installed before the gateway opens, so no one can claim it. If the bootstrap fails the gateway stays closed and the deploy logs say why. MongoDB credentials are generated and shared between the two services by reference.

Using it. Sign in at the public URL as admin, or POST /api/login for a session cookie and an X-Csrf-Token header, then call the controller API under /api/s/default/. Data survives redeploys of either service.

Device adoption: read this first. UniFi devices report to the controller on TCP port 8080, which this template publishes through a Railway TCP proxy (the proxy host and port are shown in the unifi service's networking tab). Railway gives that proxy a random public port, so point a device at it with set-inform http://PROXY_HOST:PROXY_PORT/inform and set the controller's Inform Host override to the same host and port, or devices fall back to the internal address after adoption. Railway has no UDP, so L2 discovery on UDP 10001, STUN on 3478 and the speed test port are unavailable. This template is for managing the controller and its API, labs and remote sites that you can set-inform by hand; it is not a drop-in for a controller on the same LAN as your devices.

Agent contract

Public URL: https://RAILWAY_PUBLIC_DOMAIN (the generated domain of the unifi service)
Private URL: http://unifi.railway.internal:3000
Credentials: the variable UNIFI_ADMIN_PASSWORD on the unifi service; the username is admin, fixed in the image
Auth: POST /api/login with a JSON body {"username","password"} returns a session cookie and an X-Csrf-Token header; send the cookie on every call and the token on writes. A write without a session answers 401 and a wrong password answers 400.
Health: GET /status returns 200

#!/bin/sh
# needs: RAILWAY_PUBLIC_DOMAIN, UNIFI_ADMIN_PASSWORD (variables of the unifi service); the username is admin; also curl
B="https://$RAILWAY_PUBLIC_DOMAIN"
J="Content-Type: application/json"
JAR=$(mktemp)
curl -s -o /dev/null -w "health: %{http_code}\n" "$B/status"
curl -s -o /dev/null -w "login: %{http_code}\n" -c "$JAR" -D "$JAR.h" -X POST -H "$J" -d "{\"username\":\"admin\",\"password\":\"$UNIFI_ADMIN_PASSWORD\",\"remember\":false}" "$B/api/login"
CSRF=$(sed -n 's/^[Xx]-[Cc]srf-[Tt]oken: *\([^[:space:]]*\).*/\1/p' "$JAR.h")
G='{"name":"agent-check","qos_rate_max_down":-1,"qos_rate_max_up":-1}'
curl -s -o /dev/null -w "write with session: %{http_code}\n" -b "$JAR" -H "X-Csrf-Token: $CSRF" -X POST -H "$J" -d "$G" "$B/api/s/default/rest/usergroup"
curl -s -o /dev/null -w "write without key: %{http_code}\n" -X POST -H "$J" -d "$G" "$B/api/s/default/rest/usergroup"
curl -s -o /dev/null -w "login with wrong password: %{http_code}\n" -X POST -H "$J" -d "{\"username\":\"admin\",\"password\":\"${UNIFI_ADMIN_PASSWORD}x\"}" "$B/api/login"
curl -s -o /dev/null -w "read without key: %{http_code}\n" "$B/api/s/default/rest/usergroup"
curl -s -o /dev/null -w "read with session: %{http_code}\n" -b "$JAR" "$B/api/s/default/rest/usergroup"
curl -s -o /dev/null -w "setup wizard open: %{http_code}\n" -X POST -H "$J" -d '{"cmd":"add-default-admin","name":"intruder"}' "$B/api/cmd/sitemgr"
rm -f "$JAR" "$JAR.h"

A fresh deploy prints health: 200, login: 200, write with session: 200, write without key: 401, login with wrong password: 400, read without key: 401, read with session: 200 and setup wizard open: 401.

Why Deploy UniFi Network Application on Railway?

Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it.

By deploying UniFi Network Application on Railway, you are one step closer to supporting a complete full-stack application with minimal burden. Host your servers, databases, AI agents, and more on Railway.

Agent-ready - no deployer fields, a contract block and one script that proves login, a write, the refusal of a write without a session and the closed setup wizard.
Not claimable - the first-visit setup wizard is completed with a generated password before the gateway opens.
Data survives redeploys - the controller database sits in MongoDB on a volume and the site data on a second volume.
Pinned - the UniFi and MongoDB images are pinned by digest.
Honest about limits - the device inform port is published, and the missing UDP ports are stated up front.

Common Use Cases

Remote UniFi controller - manage access points, switches and gateways from a hosted UniFi Controller instead of a machine at home.
Lab and staging controller - spin up a throwaway UniFi Network Application to test settings, firmware and the API.
Agent-driven network automation - create networks, WiFi settings and clients over the controller REST API from scripts or an LLM agent.
Remote site management - adopt devices at sites you can reach with set-inform and keep one hosted controller for all of them.

Dependencies for UniFi Network Application Hosting

The unifi service and a MongoDB service with a volume, both created by the template. A custom domain is optional.

Deploy UniFi Network | (Just Updated) Ubiquiti Controller, Admin Preset, API Ready, Data Survives Redeploys