Railway

RequirementsCopy Anchor Link

TopologyCopy Anchor Link

General rules for ports and the node channel certificate: Ports, reverse proxy, and trusted proxies.

1. Create the projectCopy Anchor Link

On the Railway Dashboard, click New Project → Empty project.

2. Add PostgreSQLCopy Anchor Link

1. On the project canvas, top right: Create → Database → Add PostgreSQL.
2. Postgres service, Settings → Source: the image is ghcr.io/railwayapp-templates/postgres-ssl:18.
3. For an earlier major version: Database → Config → Major Version Upgrade → Upgrade to PostgreSQL 18.

3. Add the console serviceCopy Anchor Link

1. On the project canvas: Create → Docker Image, enter ghcr.io/marvinli001/edgeweir:20260929-a1b2c3d (replace with the target tag) in Image name, and press Enter.
2. Right-click the service card → Update Info, rename it to edgeweir.

The service is staged and deployed in step 7.

4. Expose 3000 and 8443Copy Anchor Link

edgeweir service, Settings → Networking, in this order:

Networking changes apply immediately and are not staged. Generate Domain is hidden while the service has a TCP proxy: delete the TCP proxy, generate the domain, then add the TCP proxy again. A service has at most one TCP proxy; one created again gets a new domain and port, so do this before enrolling nodes.

5. Generate the master keyCopy Anchor Link

On your machine:

umask 077
openssl rand -base64 32 > edgeweir-master-key

Use the output as is. Store edgeweir-master-key offline, apart from database backups; see Backup and recovery.

6. Set variablesCopy Anchor Link

1. edgeweir service, Variables → Raw Editor, enter and save:

   Copy Text

   PORT=3000
   DATABASE_URL=${{Postgres.DATABASE_URL}}
   EDGEWEIR_PUBLIC_URL=https://${{RAILWAY_PUBLIC_DOMAIN}}
   EDGEWEIR_NODE_API_URL=https://${{RAILWAY_TCP_PROXY_DOMAIN}}:${{RAILWAY_TCP_PROXY_PORT}}
   EDGEWEIR_MASTER_KEY=<contents of edgeweir-master-key>

2. ⋮ menu of the EDGEWEIR_MASTER_KEY row → Seal.

A sealed value no longer appears in the Railway UI, API, or CLI and cannot be unsealed; the Raw Editor no longer edits it, use the ⋮ menu instead; duplicated environments and services and PR environments do not get sealed variables. Each variable is described under Variables.

7. Deployment settingsCopy Anchor Link

1. In the edgeweir service, set:

   Setting	Location	Value
   Healthcheck Path	Settings → Deploy	/healthz
   Serverless	Settings → Deploy → Enable Serverless	Off
   Restart Policy	Settings → Deploy	Always; not offered on the Free plan or trials, keep the default On Failure there
   Draining Time	Settings → Deploy, or the variable RAILWAY_DEPLOYMENT_DRAINING_SECONDS	10: the time the old deployment gets after SIGTERM; the console needs up to 8 seconds
   Regions	Settings → Scale	Same as the Postgres service

2. Click Deploy in the staged-changes banner at the top of the canvas to apply all changes from steps 3, 6, and 7.

8. Run setupCopy Anchor Link

An uninitialized console logs the same setup token on every start.

1. edgeweir service, Deployments → current deployment → Deploy Logs, filter by "first-run setup".
2. The line's setupToken field is the setup token; its url field is the setup wizard address (<EDGEWEIR_PUBLIC_URL>/setup).
3. Open the wizard and enter the setup token; see Quick start.

CLI deploymentCopy Anchor Link

Equivalent to steps 1–8. Seal is available only in the web console.

1. Create the project, PostgreSQL, and the console service:

   Copy Text

   railway init --name edgeweir
   railway add --database postgres
   railway add --service edgeweir --image ghcr.io/marvinli001/edgeweir:20260929-a1b2c3d

2. Expose 3000 and 8443:

   Copy Text

   railway domain --service edgeweir --port 3000
   railway tcp-proxy create --service edgeweir --port 8443

3. Generate the master key and set the variables; commands with --skip-deploys do not deploy, the last command does:

   Copy Text

   umask 077
   openssl rand -base64 32 > edgeweir-master-key
   railway variable set --service edgeweir --skip-deploys EDGEWEIR_MASTER_KEY --stdin < edgeweir-master-key
   railway variable set --service edgeweir PORT=3000 \
     'DATABASE_URL=${{Postgres.DATABASE_URL}}' \
     'EDGEWEIR_PUBLIC_URL=https://${{RAILWAY_PUBLIC_DOMAIN}}' \
     'EDGEWEIR_NODE_API_URL=https://${{RAILWAY_TCP_PROXY_DOMAIN}}:${{RAILWAY_TCP_PROXY_PORT}}' \
     RAILWAY_DEPLOYMENT_DRAINING_SECONDS=10

4. The deployment settings of step 7:

   Copy Text

   railway environment edit \
     --service-config edgeweir deploy.healthcheckPath /healthz \
     --service-config edgeweir deploy.sleepApplication false \
     --service-config edgeweir deploy.restartPolicyType ALWAYS

   On the Free plan or a trial, leave out the restartPolicyType line. Set the region with railway scale. Complete the Seal from step 6 in the web console.

5. Read the setup token:

   Copy Text

   railway logs --service edgeweir --lines 500 --json | grep setupToken

VariablesCopy Anchor Link

ROLE, HOST, and NODE_API_PORT keep the image defaults all, 0.0.0.0, and 8443. All variables: Environment variables.

VerificationCopy Anchor Link

openssl s_client -connect <name>.proxy.rlwy.net:<port> -servername <name>.proxy.rlwy.net </dev/null 2>/dev/null \
  | openssl x509 -noout -text | grep -E 'Issuer:|Subject:|DNS:'

Expected:

        Issuer: CN=Edgeweir Node Channel CA, O=Edgeweir
        Subject: CN=edgeweir-node-api, O=Edgeweir
                DNS:localhost, IP Address:127.0.0.1, IP Address:0:0:0:0:0:0:0:1, DNS:<container host name>, DNS:<name>.proxy.rlwy.net

Any other issuer means a device in the path terminates TLS.

Custom domainsCopy Anchor Link

Complete this before enrolling nodes.

1. Web console: edgeweir service, Settings → Networking → + Custom Domain, enter console.example.com, port 3000; add the CNAME and TXT records shown there in DNS. Without the TXT record the domain returns 404.

2. Node channel: in DNS, point nodes.example.com with a CNAME to <name>.proxy.rlwy.net (no port); the port stays the one Railway assigned. On Cloudflare, turn the proxy off (DNS only).

3. Change in Variables:

   Copy Text

   EDGEWEIR_PUBLIC_URL=https://console.example.com
   EDGEWEIR_NODE_API_URL=https://nodes.example.com:<port>

4. Click Deploy in the staged-changes banner.

5. Verify: run the curl and openssl commands from Verification against the new domains.

CLI:

railway domain console.example.com --service edgeweir --port 3000
railway variable set --service edgeweir \
  EDGEWEIR_PUBLIC_URL=https://console.example.com \
  EDGEWEIR_NODE_API_URL=https://nodes.example.com:<port>

Changing the node channel address for enrolled nodes: Node channel URL and certificate.

UpgradeCopy Anchor Link

1. Back up the database; see Backup and recovery.

2. edgeweir service, Settings → Source: change the image to the new tag.

3. Click Deploy in the staged-changes banner.

4. Verify:

   Copy Text

   curl -fsS https://<name>.up.railway.app/healthz

   Expected: version is the new tag.

CLI (steps 2–3):

railway service source connect --service edgeweir --image ghcr.io/marvinli001/edgeweir:<new tag>
railway redeploy --service edgeweir --from-source --yes

Migrations, signature verification, and rollback: Versions, upgrades, and rollback.

LimitsCopy Anchor Link