---
title: "Deploy Homarr | (Just Updated) Self-Hosted Dashboard, REST API, Admin and API Key Generated"
description: "Homarr dashboard with REST API, admin and API key preset, data kept"
category: "Other"
url: https://railway.com/deploy/homarr-or-just-updated-self-hosted-dashb
---

# Deploy Homarr | (Just Updated) Self-Hosted Dashboard, REST API, Admin and API Key Generated

Homarr dashboard with REST API, admin and API key preset, data kept

**[Deploy Homarr | (Just Updated) Self-Hosted Dashboard, REST API, Admin and API Key Generated on Railway](https://railway.com/template/homarr-or-just-updated-self-hosted-dashb)**

Machine-readable deploy manifest (JSON, validated by TemplateCI): https://railway.com/deploy/homarr-or-just-updated-self-hosted-dashb/manifest.json

- **Creator:** SuperSlowSloth
- **Category:** Other

## Template content

### homarr

- **Image:** ghcr.io/bon5co/homarr-railway:2.13.1@sha256:b63df22c0aa8db1a5aa958b9520a2597a0e5050e37c5d180599ba21344a67711
- **Health check:** /api/health/live
- **Public domain:** Yes

## Documentation

# Deploy and Host Homarr on Railway

**Built for an LLM agent to deploy and use.** The deploy form has no fields to fill: the encryption key, the administrator's credential and a REST API key are generated, the onboarding wizard is completed at first boot, public sign-up is closed, and the database sits on a volume. Homarr is the open-source, self-hosted dashboard for a homelab or team: boards of apps, widgets and integrations, with a REST API.

## About Hosting Homarr

This template runs one service, **homarr**: the upstream Homarr 2.13.1 image (pinned by digest) through a thin wrapper, with a volume at `/appdata` holding the SQLite database, the internal Redis dump and trusted certificates. The volume survives redeploys, so boards, apps, users and integrations persist. nginx in the image listens on Railway's injected `PORT`, and the healthcheck is `GET /api/health/live`.

**What the wrapper fixes.** A fresh upstream Homarr serves an onboarding wizard to the first visitor, who becomes the administrator, and it creates no API key, so a public deploy is either claimable by a stranger or waits for a person. The wrapper keeps the public port closed while it completes the wizard on loopback, creates the administrator `admin` from the generated credential, seeds the API key `agent` from the generated token, and only then opens the port. If that bootstrap fails, the port stays closed and the deploy is reported failed instead of serving an unclaimed wizard. It also stops Next.js from binding Railway's port directly, which would bypass nginx.

**Using it.** Sign in at the public URL as `admin` with the value of `HOMARR_ADMIN_PASSWORD`, or call the API with the header `ApiKey: agent.TOKEN` (TOKEN is the value of `HOMARR_API_TOKEN`). Further users are created by invitation from the administrator's side. Integrations that need secrets use `SECRET_ENCRYPTION_KEY`; keep that value, because secrets already stored cannot be read with a different one. To rename the administrator, add a `HOMARR_ADMIN_USERNAME` variable before the first deploy.

### Agent contract

- Public URL: `https://RAILWAY_PUBLIC_DOMAIN` (the generated domain of the `homarr` service)
- Private URL: `http://homarr.railway.internal:8080`
- Credentials: the variable `HOMARR_API_TOKEN` on the `homarr` service is the REST API token (key id `agent`); `HOMARR_ADMIN_PASSWORD` is the password of the user `admin` for the web interface; `SECRET_ENCRYPTION_KEY` encrypts stored integration secrets and is not a login
- Auth: send `ApiKey: agent.TOKEN` (the key id, a dot, then the value of `HOMARR_API_TOKEN`) on every API call. A request with no key or a wrong key answers 401. Public sign-up is closed: registration needs an invitation.
- Health: `GET /api/health/live` returns 200

```bash
#!/bin/sh
# needs: RAILWAY_PUBLIC_DOMAIN, HOMARR_API_TOKEN (variables of the homarr service; the key id is agent); also curl, sed. Creates one throwaway app and deletes it.
R="https://$RAILWAY_PUBLIC_DOMAIN"; J="Content-Type: application/json"; K="ApiKey: agent.$HOMARR_API_TOKEN"
n=0; until [ "$(curl -s -o /dev/null -w '%{http_code}' "$R/api/health/live")" = 200 ]; do n=$((n+1)); [ "$n" -le 60 ] || break; sleep 5; done
curl -s -o /dev/null -w "health: %{http_code}\n" "$R/api/health/live"
# read with the key
curl -s -o /dev/null -w "read info: %{http_code}\n" -H "$K" "$R/api/info"
# write with the key: create an app, read it back, delete it
ID=$(curl -s -X POST -H "$J" -H "$K" -d '{"name":"agent-contract-check","description":null,"iconUrl":"https://example.com/icon.png","href":null,"pingUrl":null}' "$R/api/apps" | sed -n 's/.*"id":"\([^"]*\)".*/\1/p')
if [ -n "$ID" ]; then echo "write app: created"; else echo "write app: FAILED"; fi
curl -s -o /dev/null -w "read app: %{http_code}\n" -H "$K" "$R/api/apps/$ID"
curl -s -o /dev/null -w "delete app: %{http_code}\n" -X DELETE -H "$K" "$R/api/apps/$ID"
# refusals: no key, wrong key, public sign-up, onboarding wizard
curl -s -o /dev/null -w "write without key: %{http_code}\n" -X POST -H "$J" -d '{"name":"x","description":null,"iconUrl":"https://example.com/icon.png","href":null,"pingUrl":null}' "$R/api/apps"
curl -s -o /dev/null -w "write wrong key: %{http_code}\n" -X POST -H "$J" -H "ApiKey: agent.not-the-token" -d '{"name":"x","description":null,"iconUrl":"https://example.com/icon.png","href":null,"pingUrl":null}' "$R/api/apps"
curl -s -o /dev/null -w "public signup: %{http_code}\n" -X POST -H "$J" -d '{"json":{"inviteId":"none","token":"none","username":"intruder","password":"intruder-0000-0000","confirmPassword":"intruder-0000-0000"}}' "$R/api/trpc/user.register"
curl -s -o /dev/null -w "onboarding claim: %{http_code}\n" -X POST "$R/api/onboarding/claim"
```

Expected output against a fresh deploy (measured on a Railway deploy of this template):

```text
health: 200
read info: 200
write app: created
read app: 200
delete app: 200
write without key: 401
write wrong key: 401
public signup: 403
onboarding claim: 409
```

The refusals are the contract: `write without key: 401`, `write wrong key: 401`, `public signup: 403` (registration without an invitation is refused) and `onboarding claim: 409` (the setup wizard cannot be claimed again). The first five lines show the API key works for reads and writes.

## Why Deploy Homarr 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 Homarr 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, the API key can read and write, and unauthenticated writes, sign-ups and a second setup are refused.
- **Setup done for you** - the administrator and the API key are created from generated variables before the public port opens, so nobody can claim the wizard.
- **Sign-up closed** - nobody else can register on the public URL.
- **Data survives redeploys** - the database and certificates live on a volume.
- **Pinned** - the upstream image is pinned by digest and the wrapper by tag and digest.

## Common Use Cases

- **Self-hosted homelab dashboard** - one board with links, status checks and widgets for every service you run.
- **Start page for a team** - shared boards with per-user permissions.
- **Dashboard for an AI agent to maintain** - a REST API to add apps, boards and links without a person clicking.
- **Replacement for Heimdall, Homepage or Dashy** - a dashboard with a built-in editor and user management.

## Dependencies for Homarr Hosting

- The homarr service with its volume, created by the template. A custom domain is optional.

### Deployment Dependencies

- [Homarr repository](https://github.com/homarr-labs/homarr)
- [Homarr documentation](https://homarr.dev/docs/)
- [Wrapper image source](https://github.com/bon5co/homarr-railway)


## Similar templates

- [Rocky Linux](https://railway.com/deploy/rocky-linux) — Hosted Rocky Linux 9 workspace with SSH and persistent storage. 🚀
- [Foundry Virtual Tabletop](https://railway.com/deploy/X5tR6G) — Self-hosted virtual tabletop for role-playing games (license required)
- [Double Commander in your browser](https://railway.com/deploy/double-commander-in-your-browser) — The Double Commander file manager in the cloud, from any device

Open this page in a browser: https://railway.com/deploy/homarr-or-just-updated-self-hosted-dashb
