Deploy on AWS

ECS Fargate is a good fit for the Node backend SDK because it runs a normal long-lived process and supports either transport mode. The Farther Shore pieces are the same in both cases: Node 22+, FS_RUNTIME_TOKEN, strict request verification, and graceful fs.shutdown() on termination.

Build the container correctly#

Build and install dependencies on the target Linux architecture. The embedded tunnel runner uses a platform-specific optional cloudflared package, so do not copy a macOS node_modules directory into the image or omit optional dependencies.

docker build --platform linux/amd64 -t application-api .
docker tag application-api:latest \
  <account>.dkr.ecr.<region>.amazonaws.com/application-api:latest
docker push <account>.dkr.ecr.<region>.amazonaws.com/application-api:latest

The container should listen on port 3000 (or its configured PORT) and expose an unsigned /healthz before SDK middleware.

Direct mode behind an ALB#

1. Run the task as an ECS service behind an Application Load Balancer.
2. Terminate HTTPS with an ACM certificate for a domain you control.
3. Point the target-group health check at /healthz.
4. Give only the ALB permission to reach the container port where practical.
5. Copy the stable HTTPS origin.

farthershore backend create my-business \
  --name "AWS API" \
  --slug api \
  --transport direct \
  --origin-url https://api.example.com \
  --idempotency-key <persisted-backend-create-attempt-key> \
  --default

farthershore backend tokens create my-business --format json --idempotency-key <persisted-backend-tokens-create-attempt-key>

Store the one-time token in AWS Secrets Manager and map it to the container as FS_RUNTIME_TOKEN through the ECS task definition. The task execution role needs permission to read only that secret.

Tunnel mode without inbound traffic#

Run the task without a load balancer or inbound security-group rule. It still needs outbound HTTPS connectivity so the embedded runner and SDK can reach the platform.

farthershore backend create my-business \
  --name "AWS Private API" \
  --slug api \
  --transport tunnel \
  --runner embedded \
  --idempotency-key <persisted-backend-create-attempt-key> \
  --default

farthershore backend tokens create my-business \
  --backend <backend-id> \
  --operations gateway_verification,metering,health,tunnel \
  --idempotency-key <persisted-backend-tokens-create-attempt-key> \
  --format json

Store the tunnel-capable token as FS_RUNTIME_TOKEN. Start the HTTP listener, then call await fs.start(); no ALB origin is bound for this mode.

Environments and deployments#

Each branch environment inherits the production backend unless you create a concrete override with --env <name-or-id>. A business-scoped runtime token can bootstrap all environment rows for the same business from one deployment; an environment-scoped or backend-scoped token isolates them when you run separate ECS services.

farthershore backend list my-business --format json

When changing an ECS-injected token, force a new deployment so every running task receives the new value. For a planned cutover, create a second token, deploy it, verify all tasks, then revoke the old token. backend tokens rotate revokes the old token immediately.

Use AWS-native database migrations and deployment health gates for your application. Farther Shore provisions routing and verifies traffic; it does not run your application migrations.