Infrastructure as Code Reference

This page documents the TypeScript authoring API for Railway Infrastructure as Code. For the workflow and CLI commands, see Infrastructure as Code.

Authoring

A Railway configuration file exports defineRailway.

Environment context

defineRailway receives a context object from the CLI. Use it to render different desired state for the Railway environment you are planning or applying to.

Available context fields include:

Field	Description
`ctx.command`	The command being run, such as `plan` or `apply`.
`ctx.projectId`	The linked Railway project ID.
`ctx.projectName`	The linked Railway project name.
`ctx.environmentId`	The target environment ID.
`ctx.environment`	The target environment name.
`ctx.environmentName`	Alias for the target environment name.
`ctx.isEnvironment(name)`	Returns `true` when the current environment name matches.

Services

Create a service with service(name, config).

Service names should match the names users see in Railway. Names with spaces are valid:

Sources

Use a GitHub source:

Use a Docker image:

Omit source when .railway/railway.ts should manage service settings but not declare a GitHub repository or Docker image:

Replicas

Use replicas for scaling intent:

For advanced placement, specify regions:

Environment variables

Set literal variables:

Reference another service or database:

Reference a shared variable defined on the environment using the context:

ctx.shared.NAME compiles to ${{shared.NAME}}. It points at an existing shared variable on the environment; it does not define or manage the shared variable itself.

Preserve an existing Railway-managed value:

preserve() is mainly used for imported secrets whose values are not available to the CLI. It means “keep the value that is already set in Railway.”

Databases

Railway provides helpers for common databases:

Reference database variables from services:

Database provisioning is handled by Railway product workflows. The configuration file describes the database intent; you do not need to attach a volume to managed database helpers yourself.

Volumes

Create a persistent volume with volume(name, config) and attach it to a service with volumeMounts:

A volume can be attached to one service. The object key in volumeMounts is the mount path inside the service container, and the value is the volume(...) resource to mount there.

Volume config supports:

Field	Description
`region`	Region where the volume is provisioned.
`sizeMB`	Requested volume size in megabytes.

Increasing sizeMB is planned as a non-destructive resize. Decreasing sizeMB, deleting a volume, detaching a mounted volume, or changing placement can affect persisted data and is treated as destructive.

railway config pull imports existing volumes and service mounts. Managed database volumes may appear in imported configuration so Railway can preserve the existing volume resource, but database helpers such as postgres("postgres") still own the database product intent.

Buckets

Create an object storage bucket:

Bucket regions cannot be changed after creation. If you need a different region, create a new bucket in that region, copy the data, update your services to use the new bucket, and then remove the old bucket when it is no longer needed.

Custom domains

Attach custom domains to a service:

Specify a target port:

Generated Railway service domains are not included in .railway/railway.ts.

Groups

Use groups to organize resources on the Railway canvas:

Groups are structural. They make large projects easier to scan in both .railway/railway.ts and the Railway canvas.