App Hosting service

Railway

The Railway integration deploys an app from a git source — such as a GitHub repository — to Railway, polls the deployment to completion, then reports the live deployment URL and status back to Dreambase.

Railway is a container hosting provider for the App Hosting service. It follows the same shape as the Vercel provider, but talks to Railway's public GraphQL API instead of Vercel's REST API. It handles its own webhook route:

POST/railway/webhook
Deploy & manage a git-sourced app on Railway

What it does

On DEPLOYMENT_CREATEDthe service resolves (or creates) a Railway project and environment, creates a service wired to the project's git source, applies the build/deploy overrides and the environment variables Dreambase resolved for the deployment (including any injected by connected dependencies), provisions a public domain, then triggers a deployment and polls it to completion before reporting the live url back to the Dreambase API.

Unlike Vercel, a Railway service is a long-lived, mutable resource. On DEPLOYMENT_ENV_CHANGED the service reuses the same Railway project and service — recorded in the deployment outputs — upserts the new environment variables and triggers a fresh deployment; Railway supersedes the previous one on its own, so there is no old deployment to reap. On DEPLOYMENT_DELETED, and on DEPLOYMENT_STATUS_CHANGED to STOPPED, the Railway service is deleted.

Inputs

InputRequiredDescription
gitOwneryesRepository owner, organization, or username (e.g. my-org).
gitRepoyesRepository name to deploy (e.g. my-app).
railwayTokenyesA Railway API token with deploy access. Accepts a {{env.KEY}} reference to keep the secret out of the canvas.
gitProvideroptionalGit host: github (default) or gitlab.
gitBranchoptionalBranch to deploy. Defaults to main.
environmentoptionalRailway environment to deploy into. Defaults to production.
projectName, serviceNameoptionalRailway project and service names. Both default to the repository name.
railwayProjectIdoptionalExisting Railway project id to deploy into. Leave empty to create a new project.
railwayTeamIdoptionalRailway team/workspace id the project belongs to.
builder, dockerfilePathoptionalBuild strategy: NIXPACKS (default) or DOCKERFILE. When building from a Dockerfile, dockerfilePath sets its path (via RAILWAY_DOCKERFILE_PATH).
rootDirectory, buildCommand, startCommand, healthcheckPath, numReplicasoptionalDeploy overrides. Leave empty to let Railway auto-detect.

Outputs

  • url — the live URL of the Railway deployment.
  • railwayDeploymentId — the deployment's id on Railway.
  • railwayServiceId — the service's id on Railway, used to reuse the service on a redeploy and to delete it on DEPLOYMENT_DELETED or a DEPLOYMENT_STATUS_CHANGED to STOPPED.

Environment variables flow through

Outputs from services this app depends on — a database connection string, an API key — are mapped to environment variables by the connector between them. They are seeded onto the deployment when it is created and set on Railway during deployment, so your hosted app comes up already wired to the rest of the project. If a dependency later publishes new outputs, Dreambase emits DEPLOYMENT_ENV_CHANGED and the service redeploys with the updated values.

Events it handles

  • WEBHOOK_CHALLENGE — verify the webhook endpoint.
  • DEPLOYMENT_CREATED — create a project/service from the git source (with its environment variables) and report its URL and status.
  • DEPLOYMENT_DELETED — remove the service from Railway.
  • DEPLOYMENT_ENV_CHANGED — upsert the updated environment variables onto the existing service and redeploy.
  • DEPLOYMENT_STATUS_CHANGED — reconcile the hosted resource; when the status becomes STOPPED, remove the service from Railway.
  • HEALTH_CHECK — confirm the hosted deployment is reachable.

Configuration

The service calls back into the API at DREAMBASE_API_URL (default http://localhost:3005) and talks to Railway at RAILWAY_API_URL (default https://backboard.railway.com/graphql/v2). It runs on PORT 3007 locally.

Run it on a long-lived host

The deploy poll holds state in memory for the life of a build, so run the App Hosting service on a long-lived, single-replica host rather than serverless — a serverless maxDuration would cut the poll short on longer Railway builds.