Skip to content

⭐️⭐️⭐️ Open-source, self-hosted alternative to Linear and Plane. Project management and issue tracking where teams and AI agents work side by side to plan and ship products.

docs: add the Railway deploy guide and button (#153)

Croff208935f929b7
diff --git a/README.md b/README.md
index cfbb62c0..dc859a99 100644
--- a/README.md
+++ b/README.md
@@ -76,6 +76,16 @@ stable release.
## Getting started
+### Deploy on Railway — recommended
+
+[![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/deploy/its-a-plan?referralCode=lQ5O6i&utm_medium=integration&utm_source=button&utm_campaign=itsaplan)
+
+The whole stack in one click, no server to run. You supply two hostnames and Railway
+generates every secret. A domain of your own is required — see
+[the guide](docs/railway.md) for why, and for the steps after the deploy.
+
+### Run it on your own server
+
Requirements: Docker and a domain behind a TLS-terminating reverse proxy.
```bash
@@ -88,6 +98,7 @@ docker compose up -d --build
One command brings up the whole stack: Postgres, MinIO, api, worker, bot, and web. The
first account registered becomes the instance admin.
+- [Deploy on Railway](docs/railway.md) — one-click hosted deploy from the template
- [Self-hosting](docs/self-hosting.md) — the full production setup, secrets, and updates
- [Deploy on Coolify](docs/coolify.md) — the same stack on a Coolify instance
- [Local development](docs/development.md) — running the apps on the host, and the tests
diff --git a/docs/coolify.md b/docs/coolify.md
index ef32ca6b..2a8c8b58 100644
--- a/docs/coolify.md
+++ b/docs/coolify.md
@@ -58,4 +58,5 @@ are generated on the first deploy and stay stable across later ones — nothing
hand. Optional variables from `.env.example` — legal document URLs, telemetry opt-out,
worker tuning — go in **Configuration → Environment Variables**.
-To run the same stack outside Coolify, see [self-hosting.md](self-hosting.md).
+To run the same stack outside Coolify, see [self-hosting.md](self-hosting.md) or
+[railway.md](railway.md).
diff --git a/docs/railway.md b/docs/railway.md
new file mode 100644
index 00000000..3bd197a3
--- /dev/null
+++ b/docs/railway.md
@@ -0,0 +1,63 @@
+# Deploy on Railway
+
+Railway builds the stack from source and generates the secrets itself. You supply two
+hostnames; everything else is wired by the template.
+
+[![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/deploy/its-a-plan?referralCode=lQ5O6i&utm_medium=integration&utm_source=button&utm_campaign=itsaplan)
+
+The template provisions six resources: Postgres with a volume, a storage bucket for
+attachments, and the api, web, worker and bot services, each built from its own Dockerfile
+in this repository. It tracks the `release` branch, so a deploy gets the latest published
+release.
+
+## 1. A domain of your own is required
+
+Railway's generated `*.up.railway.app` hostnames are on the Public Suffix List, which makes
+the browser treat every service as a separate site and reject the session cookie: sign-in
+returns 200 and then bounces straight back to the login page. Two hostnames under one
+registrable domain — `api.example.com` and `app.example.com` — fix this, because the cookie
+is issued on their shared parent.
+
+## 2. Deploy
+
+Press the button and fill in the two fields on the **web** service:
+
+| Field | Example |
+| --------- | ------------------------- |
+| `API_URL` | `https://api.example.com` |
+| `APP_URL` | `https://app.example.com` |
+
+Full origins, including `https://`. The api reads both by reference, and web bakes the api
+origin into its bundle at build time.
+
+## 3. Attach the hostnames
+
+After the deploy, add each hostname under **Settings → Networking → Custom Domain**:
+
+| Service | Hostname | Port |
+| ------- | ----------------- | ---- |
+| api | `api.example.com` | 3000 |
+| web | `app.example.com` | 3001 |
+
+Here Railway wants the bare hostname, without a scheme — unlike the variables above.
+It then gives you a CNAME and a TXT record to add at your DNS provider. Behind Cloudflare,
+keep both records unproxied.
+
+The first account registered becomes the instance admin. SMTP, AI provider keys and the
+Telegram bot token are configured in the interface after sign-in, not through environment
+variables.
+
+## Changing a hostname later
+
+Edit `API_URL` or `APP_URL` **on the web service**. Web rebuilds, which is what has to
+happen: Next.js inlines the api origin at build time, so a restart alone would keep serving
+the old address. The api picks the new value up by reference and only restarts.
+
+## Notes
+
+Secrets — auth secret, encryption key, worker token, database password — are generated per
+deploy and never stored in the template. Attachments go to the Railway bucket, which is why
+`S3_FORCE_PATH_STYLE` is `false` here; MinIO in the Compose stack needs the default.
+
+To run the same stack elsewhere, see [self-hosting.md](self-hosting.md) or
+[coolify.md](coolify.md).
diff --git a/docs/self-hosting.md b/docs/self-hosting.md
index b82a3eb1..dbd4dda8 100644
--- a/docs/self-hosting.md
+++ b/docs/self-hosting.md
@@ -31,4 +31,5 @@ docker compose up -d --build
Changing `API_URL` needs a rebuild too, for the same build-time inlining reason.
-For a Coolify instance, see [coolify.md](coolify.md).
+For a Coolify instance, see [coolify.md](coolify.md). For a hosted deploy without a
+server of your own, see [railway.md](railway.md).