IntrepidDeveloper.Aspire.Hosting.Railway 13.5.0-preview.12

Aspire Hosting for Railway

Aspire 13.5 hosting so aspire publish, aspire deploy, and aspire destroy can target Railway. Local aspire run stays the normal Aspire model and never needs a Railway token.

Status

Preview on nuget.org. Pack also publishes a GitHub Release and GitHub Packages. nuget.org uses Trusted Publishing (OIDC, no stored key). Current version: 13.5.0-preview.12 (from Directory.Build.props). MIT. Pinned to Aspire.Hosting 13.5.0 / net10.0. See CHANGELOG.md.

Packages

AppHost extensions live in Aspire.Hosting. Resource types live in Aspire.Hosting.Railway / .PostgreSQL / .Redis / .Storage. Official Postgres and Redis templates are volume-backed, so Railway replicas cannot be used with them.

Quick start

using Aspire.Hosting.Railway;

var builder = DistributedApplication.CreateBuilder(args);

var ghcr = builder.AddContainerRegistry("ghcr", "ghcr.io", "intrepid-developer/playground");
var railway = builder.AddRailwayEnvironment("railway")
    .WithContainerRegistry(ghcr);

var db = builder.AddPostgres("postgres").PublishAsRailwayPostgres(s =>
{
    s.VolumeBackupDaily = true;
    s.VolumeBackupWeekly = true;
});
var cache = builder.AddRedis("redis").PublishAsRailwayRedis();
var uploads = builder.AddRailwayBucket("uploads");

builder.AddProject<Projects.Api>("api")
    .WithReplicas(2)
    .WithHttpHealthCheck("/health")
    .WithReference(db)
    .WithReference(cache)
    .WithReference(uploads)
    .WaitFor(db)
    .WithExternalHttpEndpoints()
    .PublishAsRailwayService(s =>
    {
        s.Region = RailwayRegion.UsWest2;
        s.Cpu = 1;
        s.MemoryGb = 2;
        s.HealthcheckTimeoutSeconds = 120;
        s.RestartPolicy = RailwayRestartPolicy.OnFailure;
        s.RestartPolicyMaxRetries = 10;
        s.CustomDomains.Add("api.example.com");
    });

builder.Build().Run();

AddContainerRegistry is required (GHCR or Docker Hub; Railway has no registry). Pass owner/repo as the third argument. Aspire marks the registry APIs experimental (ASPIRECOMPUTE003). See Getting started for the rest.

In the API project:

builder.AddNpgsqlDataSource("postgres");
builder.AddRedisClient("redis");
builder.AddRailwayBucketClient("uploads"); // IAmazonS3

Restore from nuget.org. No extra feed or PAT. These are prerelease packages, so use --prerelease or pin the version in PackageReference as below.

dotnet add package IntrepidDeveloper.Aspire.Hosting.Railway --prerelease
dotnet add package IntrepidDeveloper.Aspire.Hosting.Railway.PostgreSQL --prerelease
dotnet add package IntrepidDeveloper.Aspire.Hosting.Railway.Redis --prerelease
dotnet add package IntrepidDeveloper.Aspire.Hosting.Railway.Storage --prerelease
dotnet add package IntrepidDeveloper.Aspire.Railway.Storage --prerelease

GitHub Packages feed: see Getting started. Do not commit PATs or packageSourceCredentials.

AppHost (IntrepidDeveloper.Aspire.Hosting.Railway*):

<PackageReference Include="IntrepidDeveloper.Aspire.Hosting.Railway" Version="13.5.0-preview.12" />
<PackageReference Include="IntrepidDeveloper.Aspire.Hosting.Railway.PostgreSQL" Version="13.5.0-preview.12" />
<PackageReference Include="IntrepidDeveloper.Aspire.Hosting.Railway.Redis" Version="13.5.0-preview.12" />
<PackageReference Include="IntrepidDeveloper.Aspire.Hosting.Railway.Storage" Version="13.5.0-preview.12" />

API / consuming project (AddRailwayBucketClient plus the usual Aspire clients):

<PackageReference Include="IntrepidDeveloper.Aspire.Railway.Storage" Version="13.5.0-preview.12" />
<PackageReference Include="Aspire.Npgsql" Version="13.5.0" />
<PackageReference Include="Aspire.StackExchange.Redis" Version="13.5.0" />

Auth

Use an account or workspace token. Project tokens cannot call projectCreate.

Local aspire run needs no token.

Publish vs deploy

AddRailwayEnvironment is the Railway project (compute environment). The Railway environment name is mapped from Aspire --environment: Production → production, Staging → staging (lowercase). Override with WithRailwayEnvironmentName.

Limits

• Railway has no image registry. Push to GHCR or Docker Hub, then deploy sets source.image.
• This integration does not shell out to railway up. Railpack has no .NET support; use an image or a Dockerfile.
• aspire destroy tears down resources this integration created in the mapped Railway environment (production / staging). Adopted resources (AsExisting(), railway-project-id / railway-environment-id, or a live name match) are skipped. The Railway project is not deleted. Buckets are skipped — public GraphQL has no bucketDelete. This is not in-deploy overlap/drain.
• PR / ephemeral Railway environments are not in this release.
• MySQL, MongoDB, and HA / PgBouncer are later. PITR enable is HA-only and is not in this slice.
• Railway buckets are private. Use S3 credentials or presigned URLs. They are not on private DNS.

Full mapping and constraints (5-minute cron floor, no replicas with volumes, cron vs replicas/serverless, DNS TXT for custom domains, image start is exec form / wrap $PORT) live in Publish and deploy.

Kitchen-sink service: region, CPU/RAM, sleep-when-idle, healthcheck timeout, restart, start / pre-deploy, overlap / drain, and a custom hostname. Image start is exec form — wrap $PORT.

builder.AddProject<Projects.Api>("api")
    .WithReplicas(2)
    .WithHttpHealthCheck("/health")
    .WithComputeEnvironment(railway)
    .PublishAsRailwayService(s =>
    {
        s.Region = RailwayRegion.EuropeWest4;
        s.Cpu = 1;
        s.MemoryGb = 2;
        s.Serverless = true;
        s.HealthcheckTimeoutSeconds = 120;
        s.RestartPolicy = RailwayRestartPolicy.OnFailure;
        s.RestartPolicyMaxRetries = 10;
        s.StartCommand = "/bin/sh -c \"exec dotnet MyApp.dll --urls http://*:$PORT\"";
        s.PreDeployCommand = "dotnet MyApp.dll --migrate";
        s.OverlapSeconds = 60;
        s.DrainingSeconds = 10;
        s.CustomDomains.Add("api.example.com");
    });

Cron worker: five-field crontab, UTC. The service must exit. Do not combine with replicas greater than 1 or Serverless.

builder.AddProject<Projects.Worker>("nightly")
    .PublishAsRailwayService(s =>
    {
        s.CronSchedule = "0 3 * * *"; // 03:00 UTC
    });

Multi-region: ReplicaRegions wins over WithReplicas + Region.

builder.AddProject<Projects.Api>("api")
    .WithComputeEnvironment(railway)
    .PublishAsRailwayService(s =>
    {
        s.ReplicaRegions = new()
        {
            [RailwayRegion.UsWest2] = 2,
            [RailwayRegion.EuropeWest4] = 1
        };
        s.Serverless = false;
    });

Docs

• Getting started — restore, AppHost, first publish/deploy, token setup
• Publish and deploy — pipeline, plan vs apply, adopt, staging, images, settings
• Storage — buckets, local S3Mock, IAmazonS3, connection strings
• GraphQL — confirmed operations only
• CHANGELOG.md — preview.11 and later
• AGENTS.md — contract for coding agents working this repo
• SECURITY.md — never commit secrets; how to report issues

License

MIT