Plugins@notation/factory-railway

@notation/factory-railway

@notation/factory-railway runs the Notation Factory hub (Vault, Router and Deployer) and repository outposts inside a shared Railway project with persistent /data volumes and private networking. Imported in factory.infra.ts from @notation/factory-railway.

 add -d @notation/factory-railway

Vault, Router & Deployer

Provision the hub and outpost builder in a Railway project:

factory.infra.ts
import * as claude from "@notation/factory-claude";
import * as railway from "@notation/factory-railway";
import { sources } from "@notation/std/resources";

const vault = new railway.Vault("vault"); // <-- sealed shared variables in the router's project

const router = new railway.Router("router", { vault }); // <-- only a railway.Vault

const claudeToken = new sources.Env("claude-oauth-token", {
  config: { key: "CLAUDE_CODE_OAUTH_TOKEN", track: "scrypt" },
});
const claudeAccount = new claude.Account("claude", {
  auth: vault.secret({ id: "claude-oauth-token", value: claudeToken.credentials.value }),
});

new railway.Deployer("deployer", {
  router,
  vault,
  accounts: [claudeAccount],
});
ResourceRailway resources provisioned
railway.VaultOne sealed shared variable in the router's project for each secret declared in the vault. Values are never shown in the dashboard or returned by the API. The router gives it its project, so pass it to a railway.Router before anything adds a secret to it
railway.Router<app>--<stage>--<id> Railway project + public factory-router service with /data volume and webhook domain. Its config is a file on that volume (/data/config.json). It generates router.rootKey with a RandomKey, keeps it in the vault, and binds it as FACTORY_ROOT_KEY. router.bind(secret, name?) adds a variable to the router service
railway.DeployerPrivate, scale-to-zero factory-deployer service inside the router's project, and a project token of its own to manage outpost services. It keeps the token in the vault and binds it as RAILWAY_TOKEN. Railway has no API that gives a token a new value, so when deploy needs the value again, plan fails and asks for a token with --credential. It binds router.rootKey as FACTORY_ROOT_KEY, and each account's secrets under their env var names, such as CLAUDE_CODE_OAUTH_TOKEN

Secrets

Each secret in the vault is a sealed shared variable named <app>__<stage>__<id>, with each character other than a letter, a digit or _ replaced by _. For example, the root key of the prod stage of an app named acme is acme__prod__router_root_key. Two secret ids that map to the same name, such as a-b and a_b, are rejected, and so is a second secret with the same id.

The router and deployer services each get one variable for every secret they bind. The variable is named after the binding name, and its value is a reference to the sealed variable:

FACTORY_ROOT_KEY = ${{shared.acme__prod__router_root_key}}

Railway resolves the reference when it deploys the service. So a changed secret reaches a service only when the service redeploys. See Known gaps.

Environment variables

VariablePurpose
RAILWAY_API_TOKENAuthenticates factory infra up and factory infra down