Deploy and Host Nezha on Railway

Nezha (哪吒) is a lightweight, open-source, self-hosted dashboard for monitoring your servers and websites: uptime, load, traffic, latency and alerts, with small agents reporting from each machine. This template deploys the Nezha dashboard with your admin account secured at start-up. It is a community-maintained template and is not affiliated with the Nezha project.

About Hosting Nezha

Nezha's dashboard serves a web UI and its agent gRPC endpoint on a single port, and on a fresh database it seeds a well-known admin/admin account — which, on a public URL, can be claimed by whoever opens it first. It stores its data and auto-generated secrets in SQLite on disk.

This template runs Nezha on Railway with the admin secured at first boot (the default admin/admin is replaced with a generated password), the data and secrets persisted on a volume, and the port, health check and networking wired. Because agent traffic is gRPC — which does not traverse an HTTP edge — the template provisions both a public HTTPS domain for the web UI and a TCP proxy for the agents, on the same port. Both run from the official image, pinned by digest.

Common Use Cases

A private, self-hosted status dashboard for your fleet of servers and websites.
Uptime and resource monitoring with alerting for a homelab or a small team.
A lightweight alternative to heavier observability stacks, with per-machine agents.

Dependencies for Nezha Hosting

Nothing external — the dashboard is self-contained and stores its data on a volume.
To monitor a machine, install the Nezha agent on it (a small separate program) and point it at the TCP proxy.

Deployment Dependencies

Nezha: https://github.com/nezhahq/nezha (Apache-2.0)
Nezha agent (installed on the machines you monitor): https://github.com/nezhahq/agent
Template repository, image and tests: https://github.com/youssefsiam38/nezha-railway

Implementation Details

Nezha runs upstream's official dashboard binary — which embeds the web frontends — pinned by digest, re-based on a small Alpine image with curl so a start-up wrapper can secure the admin. On first boot the wrapper logs in with the default admin/admin and changes the password to the generated OWNER_PASSWORD (username admin) via the profile API, using a mode-600 file so the password never touches a command line. The web UI is on the HTTPS domain; agents connect over gRPC through a Railway TCP proxy on the same port 8008 with TLS disabled. SQLite, the config and the auto-minted JWT/agent secrets persist on the /dashboard/data volume.

Tested in CI and on a live deployment of this template: the dashboard is healthy, admin/admin is secured, the owner logs in while a wrong password is refused, an authenticated API call works, the admin survives a redeploy, and a gRPC call reaches the agent handler through the TCP proxy.

After deploying, copy OWNER_PASSWORD from the nezha service's variables and sign in at the app's domain (username admin). To monitor a machine, add a server in the dashboard and install the Nezha agent pointing at the service's TCP-proxy address (shown in the Railway UI) with TLS off.

Why Deploy Nezha 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 Nezha 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.