Deploy

Deploying to AWS ECS

Run your backend on Amazon ECS with Fargate using a simple container image and service definition.

Guide

Prerequisites

AWS account with permissions for ECS, ECR, and IAM
AWS CLI v2 configured (aws configure)
An existing VPC with private subnets and security groups for ECS
Container registry (ECR) and your backend repository

Generate Environment Variables

Navigate to Rivet and click Connect > Manual. Copy the environment variables provided, they will be used in the task definition. They should look something like this:

RIVET_API_ENDPOINT=https://api-us-west-1.rivet.dev
RIVET_NAMESPACE=your-namespace-id
RIVET_TOKEN=your-token

Command Line

Package Your App

Create a Dockerfile in your project root:

FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
COPY . .
ENV PORT=8080
CMD ["node", "server.js"]

Dockerfile

Build and Push the Image

Authenticate to ECR, build the image, and push it. Replace the AWS account, region, and repository names with your own.

aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin 123456789012.dkr.ecr.us-east-1.amazonaws.com
docker build -t backend:latest .
docker tag backend:latest 123456789012.dkr.ecr.us-east-1.amazonaws.com/backend:latest
docker push 123456789012.dkr.ecr.us-east-1.amazonaws.com/backend:latest

Command Line

Create the Task Definition

Create backend-task.json describing the ECS task. Update the ARNs, subnets, and security groups for your environment.

{
  "family": "backend",
  "networkMode": "awsvpc",
  "cpu": "256",
  "memory": "512",
  "requiresCompatibilities": ["FARGATE"],
  "executionRoleArn": "arn:aws:iam::123456789012:role/ecsTaskExecutionRole",
  "containerDefinitions": [
    {
      "name": "backend",
      "image": "123456789012.dkr.ecr.us-east-1.amazonaws.com/backend:latest",
      "environment": [
        { "name": "RIVET_API_ENDPOINT", "value": "https://api-us-west-1.rivet.dev" },
        { "name": "RIVET_NAMESPACE", "value": "your-namespace-id" },
        { "name": "RIVET_TOKEN", "value": "your-token" }
      ]
    }
  ]
}

JSON

You do not need to expose a container port. Rivet tunnels traffic directly to your backend.

aws ecs register-task-definition --cli-input-json file://backend-task.json

Command Line

Launch the Service

Create or reuse an ECS cluster, then launch a service with the new task definition. Substitute your subnet and security group IDs.

aws ecs create-cluster --cluster-name backend
aws ecs create-service \
  --cluster backend \
  --service-name backend \
  --task-definition backend \
  --desired-count 1 \
  --launch-type FARGATE \
  --network-configuration "awsvpcConfiguration={subnets=[subnet-abc12345,subnet-def67890],securityGroups=[sg-abc12345],assignPublicIp=ENABLED}"

Command Line

Verify the Runner

Check that the task is running:

aws ecs describe-services --cluster backend --services backend --query "services[0].deployments"

Command Line

Your runner should appear as connected on the Rivet dashboard once the task is healthy.