Railway.Networking reference

CustomDomain

Source: packages/railway/src/CustomDomain.ts

A Railway.CustomDomain is a user hostname on a CustomDomainService. Railway issues a Let’s Encrypt certificate once DNS is verified.

CustomDomain: Attach a hostname

Pass the parent Service, the environment id, and the hostname. Yield the CustomDomain next to the Service. Publish the records listed in dnsRecords (the routing CNAME and the verificationDnsHost / verificationToken TXT) at your DNS host.

const site = yield* Railway.Project("Site");
const api = yield* Railway.Service("Api", {
  project: site,
  image: "hashicorp/http-echo",
});
const www = yield* Railway.CustomDomain("Www", {
  service: api,
  environment: site,
  domain: "www.example.com",
});

Changing domain, service, or environment replaces the CustomDomain

The old hostname is deleted. The new hostname is created.

CustomDomain: Target port

targetPort is optional and updates in place. Railway’s edge forwards HTTPS on 443 to this port on the Service.

const www = yield* Railway.CustomDomain("Www", {
  service: api,
  environment: site,
  domain: "www.example.com",
  targetPort: 8080,
});

CustomDomain: Module-scope declarations

Declare the CustomDomain once. Resource-valued props accept the resource or an Effect producing it.

src/domain.ts

import * as Railway from "@alchemy.run/railway";
import { Api } from "./api.ts";
import { Site } from "./project.ts";

export const Www = Railway.CustomDomain("Www", {
  service: Api,
  environment: Site,
  domain: "www.example.com",
});

PrivateNetwork

Source: packages/railway/src/PrivateNetwork.ts

Enable Railway’s platform-managed private network for an environment. This resource manages the environment’s networking setting, not a separately created network. Use one PrivateNetwork resource per environment.

Destroy restores the setting captured before reconciliation. A network that was already enabled stays enabled; one enabled by this resource is disabled. Platform network objects follow the environment’s lifecycle.

Named networks are no longer supported

Railway removed named-network creation. Remove legacy named-network declarations before adding this environment-managed resource. Custom names are rejected rather than silently mapped to the platform network.

PrivateNetwork: Enable private networking

Pass a Project or Environment. dnsName is Railway’s network DNS label.

const site = yield* Railway.Project("Site");
const net = yield* Railway.PrivateNetwork("Mesh", {
  environment: site,
});

PrivateNetwork: Endpoints

Configure a deployed service’s DNS prefix via PrivateNetworkEndpoint.

const endpoint = yield* Railway.PrivateNetworkEndpoint("ApiDns", {
  network: net,
  service: { serviceId: "deployed-service-id" },
  name: "api",
});

PrivateNetwork: Module-scope declarations

Resource-valued props accept the resource or an Effect producing it.

src/network.ts

import * as Railway from "@alchemy.run/railway";

export const Site = Railway.Project("Site");
export const Mesh = Railway.PrivateNetwork("Mesh", {
  environment: Site,
});

TcpProxy

Source: packages/railway/src/TcpProxy.ts

A Railway.TcpProxy exposes a service over public TCP. Identity is the Railway proxy id. There is no in-place update — changing service, postgres, redis, environment, or applicationPort replaces the proxy.

Needed so laptop tests and ConnectPostgres from outside the private network can reach Postgres/Redis.

TcpProxy: Postgres

Attach a proxy to a Postgres service on 5432. domain and proxyPort are the public endpoint ({domain}:{proxyPort}).

const site = yield* Railway.Project("Site");
const db = yield* Railway.Postgres("Db", { project: site });
const proxy = yield* Railway.TcpProxy("DbProxy", {
  postgres: db,
  environment: site,
  applicationPort: 5432,
});

Changing applicationPort replaces the proxy

Railway has no TCP-proxy update API. A new proxy is created, then the old one is deleted.

TcpProxy: Redis

Same shape on 6379.

const site = yield* Railway.Project("Site");
const cache = yield* Railway.Redis("Cache", { project: site });
const proxy = yield* Railway.TcpProxy("CacheProxy", {
  redis: cache,
  environment: site,
  applicationPort: 6379,
});

TcpProxy: Any service

Pass a Railway.Service or a { serviceId } stub.

const site = yield* Railway.Project("Site");
const proxy = yield* Railway.TcpProxy("ApiProxy", {
  service: { serviceId: "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" },
  environment: site,
  applicationPort: 8080,
});

Changing service or environment replaces the proxy

The proxy is created on the new service/environment. The old proxy is deleted.

TcpProxy: Module-scope declarations

Resource-valued props accept the resource or an Effect producing it.

src/db.ts

import * as Railway from "@alchemy.run/railway";

export const Site = Railway.Project("Site");
export const Db = Railway.Postgres("Db", { project: Site });
export const DbProxy = Railway.TcpProxy("DbProxy", {
  postgres: Db,
  environment: Site,
  applicationPort: 5432,
});