Skip to content

About

Thin Go authoring helpers for Railway Infrastructure as Code

Resources

Contributing

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

Thin Railway Infrastructure as Code authoring helpers for Go.

Module: github.com/railwayapp/railway-go-sdk (import name railway).

Author .railway/railway.go using this module, then railway config plan / railway config apply. One repository (or monorepo) for the whole environment: one file describing every resource. One repository per service: one file per repository, each with a named partial (see Multi-repo projects).

package main

import "github.com/railwayapp/railway-go-sdk"

func Railway() railway.Project {
  db := railway.Postgres("db")
  web := railway.ServiceNamed("web", railway.ServiceConfig{
    "source": railway.Github("org/app"),
    "start":  "./app",
    "env": map[string]any{
      "DATABASE_URL": db.Env("DATABASE_URL"),
    },
    // Per-environment tracing switches; omit the block to leave tracing off.
    "tracing": map[string]any{"enabled": true, "autoInstrumentation": true},
  })
  return railway.ProjectNamed("my-app", []any{db, web})
}

Put a go.mod next to .railway/railway.go (the CLI go runs from that directory):

module railway-config

go 1.22

require github.com/railwayapp/railway-go-sdk v0.6.0

Config as Code migration: railway config migrate --lang go.

Image auto updates

Docker Hub and GHCR image sources can follow new image tags automatically. Pass a railway.AutoUpdates value as the autoUpdates option of railway.Image: Type is the policy (railway.AutoUpdatesPatch, railway.AutoUpdatesMinor or railway.AutoUpdatesDisabled) and Schedule the weekly UTC maintenance windows updates may run in. Each railway.AutoUpdateWindow has a Day (0 Sunday through 6 Saturday), a StartHour (0 to 23, inclusive) and an EndHour (1 to 24, exclusive, after StartHour). The windows are validated when the file is evaluated, so a bad day or hour fails railway config plan instead of the apply.

nginx := railway.ServiceNamed("nginx", railway.ServiceConfig{
  "source": railway.Image("nginx:latest", map[string]any{
    "autoUpdates": railway.AutoUpdates{
      Type: railway.AutoUpdatesPatch,
      // Saturdays 02:00 to 06:00 UTC and Sundays 02:00 to 06:00 UTC.
      Schedule: []railway.AutoUpdateWindow{
        {Day: 6, StartHour: 2, EndHour: 6},
        {Day: 0, StartHour: 2, EndHour: 6},
      },
    },
  }),
})

autoUpdates only applies to Docker Hub and GHCR images (nginx:latest, docker.io/library/nginx, ghcr.io/acme/api); railway.Image panics for other registries and railway.Github never accepts it. The raw map[string]any form that railway config pull writes out is still accepted and validated the same way.

CDN

CDN caching is set per service and per environment, for the service's public domains. The settings live on the edge and apply without a deploy. Pass a railway.ServiceCdn value as the cdn option of a service:

web := railway.ServiceNamed("web", railway.ServiceConfig{
  "cdn": railway.ServiceCdn{Enabled: true},
})

swr := false
docs := railway.ServiceNamed("docs", railway.ServiceConfig{
  "cdn": railway.ServiceCdn{
    Enabled:              true,
    DefaultTtlSeconds:    86400,
    HtmlCaching:          railway.ServiceCdnHtmlCachingForce,
    StaleWhileRevalidate: &swr,
    PurgeOnDeploy:        railway.ServiceCdnPurgeOnDeployAll,
  },
})

Enabled caches responses from the service's public domains at Railway's edge. It needs a public domain and cannot be combined with Railway Authentication. The other knobs tune the cache and each has a default:

  • DefaultTtlSeconds: how long the edge keeps a cacheable response without Cache-Control headers of its own, in seconds. Defaults to 7200.
  • HtmlCaching: whether HTML documents are cached. railway.ServiceCdnHtmlCachingAuto follows the response headers, Force caches them regardless, Never leaves them uncached. Defaults to auto.
  • StaleWhileRevalidate: honour stale-while-revalidate Cache-Control directives, serving a stale copy while the edge refreshes it. A *bool because the default is true; nil leaves the default.
  • PurgeOnDeploy: what a successful deploy purges from the cache. railway.ServiceCdnPurgeOnDeployHtml keeps immutable assets warm, All clears everything, Off purges nothing. Defaults to html.

Railway serialises the block only while caching is on, and only the knobs that differ from the defaults. Leaving the block out, Enabled: false and nil all mean the same thing: no caching, and no drift in railway config plan. ServiceCdn{Enabled: true} is a service caching with the defaults, so a knob set to its default does not plan as drift either. The raw map[string]any form that railway config pull writes out is accepted and validated the same way.

Requires a Railway CLI that compiles cdn. Older CLIs drop the block when compiling the config.

Functions

A Railway Function is a single file of TypeScript that runs on the Bun runtime image with no repository or build step. railway.Fn takes the path of that file under codeFile, reads it when the config is evaluated, and compiles it into the function image plus a base64-encoded start command, the same shape the dashboard and railway functions push produce:

// .railway/railway.go, with the source in .railway/hook.ts
hook := railway.Fn("hook", railway.ServiceConfig{
  "codeFile": "hook.ts",
  "env":      map[string]any{"SECRET": railway.Shared("WEBHOOK_SECRET")},
})

A relative codeFile is resolved against the directory of the Go file that calls Fn, so paths are relative to railway.go no matter where railway config plan runs. runtime picks the image from railway.FunctionImages and defaults to "bun". To pin another image version pass source instead:

railway.Fn("hook", railway.ServiceConfig{
  "codeFile": "hook.ts",
  "source":   railway.Image("ghcr.io/railwayapp/function-bun:1.2.16"),
})

The source is limited to 98,295 bytes of UTF-8 (railway.FunctionSourceMaxBytes, just under 96 KB): the whole payload is one argument of the start command, the kernel caps a single argument at 128 KiB, and the base64 has to fit after the ./run.sh prefix. Fn panics past that, with the same error Railway returns on apply. codeFile and start are mutually exclusive — railway.FunctionStartCommand(code) builds the start command from a string on its own.

Multi-repo projects

A named partial lets each repository manage its own slice of a Railway environment. Declare const Partial = "<name>" in railway.go (same role as export const partial in TypeScript and PARTIAL in Python). The CLI records which partial owns each resource; omitting a resource then only deletes it if your partial owns it. A partial name is 1 to 64 characters from a-z, A-Z, 0-9, ., _, and -.

An api repository owns the API service and its database:

// api/.railway/railway.go
package main

import "github.com/railwayapp/railway-go-sdk"

const Partial = "api"

func Railway() railway.Project {
  db := railway.Postgres("postgres")
  api := railway.ServiceNamed("api", railway.ServiceConfig{
    "env": map[string]any{
      "DATABASE_URL": db.Env("DATABASE_URL"),
    },
  })
  return railway.ProjectNamed("acme", []any{api, db})
}

A web repository owns the frontend service:

// web/.railway/railway.go
package main

import "github.com/railwayapp/railway-go-sdk"

const Partial = "web"

func Railway() railway.Project {
  web := railway.ServiceNamed("web", railway.ServiceConfig{})
  return railway.ProjectNamed("acme", []any{web})
}

After both repositories apply, partial api owns service.api and database.postgres, and partial web owns service.web. Removing db from the api file deletes the database on the next api apply. Nothing the web file does can touch it.

Ownership rules the CLI enforces on every plan and apply:

  • A resource declared in a file whose partial does not own it fails with Cannot manage service "api": already managed by partial "web". Move the declaration to the owning repository, or remove it from the owner first.
  • A file without Partial fails in an environment that already has named partials. Once any partial has a name, every file targeting that environment must declare one.
  • A named partial only deletes resources it owns. Resources owned by other partials, or not yet owned by any, are left alone when missing from your file.
  • The first railway config apply from a partial claims ownership of every resource the file declares, even when the plan shows no configuration changes.
  • Do not rename a partial after apply. The resources stay owned by the old name and the renamed file fails the foreign-resource check.

Apply from each repository's own pipeline; Railway does not read .railway/ during deploys.

See https://docs.railway.com/infrastructure-as-code

About

Thin Go authoring helpers for Railway Infrastructure as Code

Resources

Contributing

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages