From 5335f8bcb4850541ad41c1abbaaba11a635524fe Mon Sep 17 00:00:00 2001 From: Bryan Helmkamp Date: Sat, 18 Apr 2026 00:44:15 -0400 Subject: [PATCH] feat(deploy): add Railway deploy path, honor $PORT in container Teach the Dockerfile CMD to bind 0.0.0.0:${PORT:-32276} so PaaS providers (Railway, Fly, Render, Cloud Run) route traffic without manual port configuration. Default 32276 preserves local docker / docker-compose behavior. Ship railway.toml pointing Railway at the Dockerfile with on_failure restarts. Replace the "coming soon" stub in docs/administration/deploy- railway.mdx with a real guide: deploy button, Volume-at-/storage setup, env vars, dev-token retrieval, and CLI pointing. Surface the Railway deploy button in README.md under a new "Self-host the Fabro server" section that also links to the other deploy guides. Locally verified: PORT env override binds the chosen port, default falls back to 32276, and tini signal propagation still gives clean docker stop. End-to-end Railway verification still needs a live click- through before the template URL is finalized. --- Dockerfile | 8 ++- README.md | 12 ++++ docs/administration/deploy-railway.mdx | 78 +++++++++++++++++++++++++- railway.toml | 7 +++ 4 files changed, 100 insertions(+), 5 deletions(-) create mode 100644 railway.toml diff --git a/Dockerfile b/Dockerfile index bfd7c5586..bb9e2a14f 100644 --- a/Dockerfile +++ b/Dockerfile @@ -6,8 +6,10 @@ # docker-context/amd64/fabro (x86_64-unknown-linux-gnu) # docker-context/arm64/fabro (aarch64-unknown-linux-gnu) # -# The image serves the HTTP API (with embedded web UI) on port 32276, -# persists state to /storage, and runs as the unprivileged `fabro` user. +# The image serves the HTTP API (with embedded web UI) on $PORT (default +# 32276), persists state to /storage, and runs as the unprivileged `fabro` +# user. Honoring $PORT lets PaaS providers (Railway, Fly, Render, Heroku, +# Cloud Run) route traffic without extra configuration. FROM debian:trixie-slim @@ -39,4 +41,4 @@ VOLUME ["/storage"] EXPOSE 32276 ENTRYPOINT ["/usr/bin/tini", "--", "/usr/local/bin/fabro-entrypoint"] -CMD ["fabro", "server", "start", "--foreground", "--bind", "0.0.0.0:32276"] +CMD ["sh", "-c", "exec fabro server start --foreground --bind 0.0.0.0:${PORT:-32276}"] diff --git a/README.md b/README.md index 55d2740de..0cf001aad 100644 --- a/README.md +++ b/README.md @@ -130,6 +130,18 @@ fabro repo init # per project --- +## Self-host the Fabro server + +Running Fabro as an HTTP server with the web UI lets a team share one instance. The repository ships a `Dockerfile` that serves the API (with the embedded web UI) on `$PORT` (default `32276`) and persists state to `/storage`. + +[![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/new/template?template=https%3A%2F%2Fgithub.com%2Ffabro-sh%2Ffabro) + +Click the button to provision a Fabro service on Railway from this repository, then attach a Railway Volume at `/storage` so your runs and checkpoints survive redeploys. The [Railway deploy guide](https://docs.fabro.sh/administration/deploy-railway) walks through env vars, accessing the dev token, and pointing the CLI at your deployment. + +Prefer to run Fabro elsewhere? See [Running the Fabro Server](https://docs.fabro.sh/administration/deploy-server) for generic Docker guidance and the companion guides for [Render](https://docs.fabro.sh/administration/deploy-render), [Fly.io](https://docs.fabro.sh/administration/deploy-fly-io), and [DigitalOcean](https://docs.fabro.sh/administration/deploy-digital-ocean). + +--- + ## Contributing to Fabro Fabro uses an **issue-based contribution model**. Instead of accepting outside pull requests, we accept bug reports and feature requests as GitHub Issues. diff --git a/docs/administration/deploy-railway.mdx b/docs/administration/deploy-railway.mdx index 188d0b1f6..3e0b3c17a 100644 --- a/docs/administration/deploy-railway.mdx +++ b/docs/administration/deploy-railway.mdx @@ -1,8 +1,82 @@ --- title: "Railway" -description: "Deploy Fabro to Railway" +description: "Deploy Fabro to Railway from the Dockerfile, with a persistent Volume for state" --- -This guide is coming soon. Deployment guides are currently in development. + The server interface is in private early access. Contact [bryan@qlty.sh](mailto:bryan@qlty.sh) if you're interested in trying it. + +[Railway](https://railway.com) can host the Fabro server directly from this repository's `Dockerfile`. A single deploy button spins up a container, and a Railway Volume keeps your runs, checkpoints, and sessions across redeploys. + +## One-click deploy + +[![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/new/template?template=https%3A%2F%2Fgithub.com%2Ffabro-sh%2Ffabro) + +The button launches Railway's new-project flow pointed at this repo, with `railway.toml` telling Railway to build the image from `Dockerfile` and restart on failure. + +## First-deploy checklist + +The template covers the build; a few pieces still need to be wired up after the first deploy. + +### 1. Attach a Volume for `/storage` + +Fabro writes all persistent state — run history, checkpoints, sessions, the default token, and JWT keys — under `/storage`. Railway containers have ephemeral filesystems, so without a Volume that directory is wiped on every redeploy. + +In the Railway dashboard: **Service → Settings → Volumes → New Volume**, mount path `/storage`. 10 GB is a reasonable starting size; grow as needed. + +### 2. Confirm the target port + +Railway sets `$PORT` automatically and expects the container to bind to it. The Fabro image honors `$PORT` and falls back to `32276`, and the `Dockerfile` exposes `32276`, so Railway's default HTTP routing works without any manual port configuration. + +If you override the port in **Service → Settings → Networking → Target Port**, match the value to `$PORT`. + +### 3. Set required environment variables + +Add variables in **Service → Variables** as needed. The [Server Configuration](/administration/server-configuration) reference has the full list; the minimum useful set: + +| Variable | Purpose | +|---|---| +| `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` / `GEMINI_API_KEY` / ... | At least one LLM provider key for the models you'll run | +| `FABRO_DEV_TOKEN` | Optional — pre-set the dev token instead of reading the one written to `/storage` on first boot | +| `SESSION_SECRET` | 64-character hex string; required when the web UI is enabled | +| `GITHUB_APP_CLIENT_SECRET`, `GITHUB_APP_WEBHOOK_SECRET`, `GITHUB_APP_PRIVATE_KEY` | Only if you enable GitHub OAuth or the GitHub App integration | + +No `.env` file is auto-loaded inside the container; everything comes from Railway's environment. + +## Accessing your Fabro server + +Once the deploy is healthy, Railway exposes a `*.up.railway.app` URL (or your custom domain). Two things to grab: + +1. **The dev token** — on first boot, Fabro writes one to `/var/fabro/dev-token` and logs it. Find it in the Railway deploy logs or run `railway run cat /var/fabro/dev-token` from the Railway CLI. +2. **Point your local CLI at the server** — add the Railway URL to `~/.fabro/settings.toml`: + + ```toml title="~/.fabro/settings.toml" + [server] + target = "https://.up.railway.app/api/v1" + ``` + + Then commands like `fabro model list --server ` will hit your Railway instance. + +See [Running the Fabro Server](/administration/deploy-server) for the full auth and CLI-pointing story. + +## Redeploys and updates + +Railway rebuilds the image on every push to the connected branch. The `/storage` Volume survives redeploys, so runs and checkpoints persist. If you change the Dockerfile or add new env vars, redeploy from the Railway dashboard or push a commit. + +## Caveats + +- **Volume is load-bearing.** Without a Volume mounted at `/storage`, a redeploy silently wipes all state — including the dev token and JWT signing keys. Attach it before submitting any real runs. +- **Single replica.** Fabro's server currently assumes one process owns `/storage`. Don't scale the service to multiple replicas. +- **Build context size.** The `Dockerfile` expects pre-built binaries under `docker-context/`, which are generated by the release workflow. For Railway, switch to an image-first deploy (pull the published `ghcr.io/fabro-sh/fabro` image) once multi-arch images are publicly available. Source-based builds on Railway are slower and build from scratch; this is a known tradeoff until the public image tag is finalized. + +## Next steps + + + + Auth, dev tokens, submitting runs, and pointing the CLI at your deployment. + + + Full `settings.toml` reference — TLS, auth methods, concurrency, and more. + + diff --git a/railway.toml b/railway.toml new file mode 100644 index 000000000..e86f71737 --- /dev/null +++ b/railway.toml @@ -0,0 +1,7 @@ +[build] +builder = "dockerfile" +dockerfilePath = "Dockerfile" + +[deploy] +restartPolicyType = "on_failure" +restartPolicyMaxRetries = 5