
Deploy Homepage | (Just Updated) Self-Hosted Application Dashboard, Service Links and Widgets, Login Password Generated
Homepage self-hosted app dashboard, service links and widgets, with a login
homepage
Just deployed
/app/config
Deploy and Host Homepage on Railway
Built for an LLM agent to deploy and use. The deploy form has no fields to fill: the login password is generated, the whole dashboard sits behind that login, and the YAML config lives on a volume. Homepage is a self-hosted application dashboard: service links, status checks, bookmarks and widgets for 100+ services on one fast start page, a free alternative to Heimdall, Dashy and Homarr.
About Hosting Homepage
This template runs one service, homepage: the upstream Homepage v2.8.0 image, pinned by digest, through a thin wrapper, with a volume at /app/config that holds services.yaml, settings.yaml, bookmarks.yaml and widgets.yaml. One public domain serves the dashboard. The login proxy listens on Railway's injected PORT, and the healthcheck is GET /healthz.
What the wrapper fixes. A stock Homepage container answers every request, health probes included, with 400 Host validation failed until HOMEPAGE_ALLOWED_HOSTS names the domain, so a plain Railway deploy never goes healthy; and it has no login of its own, so once the host is allowed anyone with the URL reads the dashboard. The wrapper builds the allowed-hosts list from Railway's own variables (public domain, private domain, the healthcheck host), runs Homepage on a loopback port, and puts a login proxy in front: user admin, password from the ADMIN_PASSWORD variable. It refuses to start if ADMIN_PASSWORD is empty. Measured on Homepage v2.8.0 in a container with the variable unset: 400 on every path including /api/healthcheck. Not reproduced on a Railway control of the incumbent listing.
Using it. Open the domain, your browser asks for a login, and you sign in as admin with ADMIN_PASSWORD. Upstream's sample config is seeded on first start. To change the dashboard, edit the YAML files on the volume, or set SERVICES_YAML, SETTINGS_YAML, BOOKMARKS_YAML or WIDGETS_YAML to a complete file: a set variable replaces its file at every boot. For a custom domain, add it to a HOMEPAGE_ALLOWED_HOSTS variable; it is appended to the generated list. Secrets used in widgets go in HOMEPAGE_VAR_* variables.
Agent contract
- Public URL:
https://RAILWAY_PUBLIC_DOMAIN(the generated domain of thehomepageservice) - Private URL:
http://homepage.railway.internal:8080(send theAuthorizationheader there too) - Credentials: the variable
ADMIN_PASSWORDon thehomepageservice is the password of the useradmin - Auth: HTTP Basic (
adminand the password) orAuthorization: Bearer ADMIN_PASSWORD(the variable value) on every request except the health route; without it every path answers 401 with aWWW-Authenticateheader. Homepage has no sign-up. - Health:
GET /healthzreturns 200 without credentials
#!/bin/sh
# needs: RAILWAY_PUBLIC_DOMAIN, ADMIN_PASSWORD (variables of the homepage service); also curl, grep.
# signup: none - Homepage has no account registration; the only user is `admin`, created from ADMIN_PASSWORD
R="https://$RAILWAY_PUBLIC_DOMAIN"
n=0; until [ "$(curl -s -o /dev/null -w '%{http_code}' "$R/healthz")" = 200 ]; do n=$((n+1)); [ "$n" -le 60 ] || break; sleep 5; done
curl -s -o /dev/null -w "health: %{http_code}\n" "$R/healthz"
# a stranger gets nothing: no page, no services list
curl -s -o /dev/null -w "page without key: %{http_code}\n" "$R/"
curl -s -o /dev/null -w "services without key: %{http_code}\n" "$R/api/services"
# write without the key, and with a wrong one, is refused
curl -s -X POST -H "Content-Type: application/json" -d '{}' -o /dev/null -w "write without key: %{http_code}\n" "$R/api/services"
curl -s -X POST -H "Authorization: Bearer not-the-password" -d '{}' -o /dev/null -w "write with wrong key: %{http_code}\n" "$R/api/services"
# the generated password opens the dashboard and its data
curl -s -u "admin:$ADMIN_PASSWORD" -o /dev/null -w "page with key: %{http_code}\n" "$R/"
curl -s -H "Authorization: Bearer $ADMIN_PASSWORD" -o /dev/null -w "services with key: %{http_code}\n" "$R/api/services"
if curl -s -u "admin:$ADMIN_PASSWORD" "$R/api/services" | grep -q '"services"'; then echo "services listed: found"; else echo "services listed: MISSING"; fi
Expected output against a fresh deploy (measured on a Railway deploy of the generated draft):
health: 200
page without key: 401
services without key: 401
write without key: 401
write with wrong key: 401
page with key: 200
services with key: 200
services listed: found
The refusals are the contract: page without key: 401, services without key: 401, write without key: 401 and write with wrong key: 401. Homepage has no account registration, so the signup line in the snippet says so.
Why Deploy Homepage 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 Homepage 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 the instance is healthy, a stranger sees nothing, and the generated password opens the dashboard.
- Works on first deploy - the host validation that makes a stock container answer 400 is already configured.
- Private by default - every page and API route sits behind a login instead of being open to the internet.
- Settings survive redeploys - the YAML config lives on a volume.
- Pinned - the upstream image is pinned by digest and the wrapper by tag and digest.
Common Use Cases
- Personal start page - links, bookmarks and weather for one person on a private domain.
- Homelab and service launcher - one page that links and checks every self-hosted service you run.
- Team landing page - a shared page of internal tools behind one login.
- Status board - widget data from services you already run, kept off the public internet.
Dependencies for Homepage Hosting
- The homepage service with its volume, created by the template. A custom domain is optional; add it to
HOMEPAGE_ALLOWED_HOSTSif you use one.
Deployment Dependencies
Template Content
