Install on AWS ECS

A CloudFormation template deploys Sentinel on ECS Fargate with an Application Load Balancer already wired up — a good fit if your infrastructure is already on AWS.

Prerequisites

• An active AWS account.
• The AWS CLI installed and configured.
• A local copy of the template from altcha-org/altcha-sentinel-deploy-aws.

What the stack creates

• An ECS service (Fargate launch type).
• An internet-facing Application Load Balancer (ALB).
• Optional persistent EFS storage volume for Sentinel's /data, if EnablePersistence is set.
• Optional custom domain configuration.

Step 1 — Deploy the stack

A minimal deployment:

aws cloudformation deploy \
  --template-file altcha-sentinel-aws-ecs.yml \
  --stack-name altcha-sentinel-stack \
  --capabilities CAPABILITY_IAM

With a custom domain, ACM certificate, and larger task size:

aws cloudformation deploy \
  --template-file altcha-sentinel-aws-ecs.yml \
  --stack-name altcha-sentinel-stack \
  --capabilities CAPABILITY_IAM \
  --parameter-overrides \
      DomainName=sentinel.example.com \
      CertificateArn=arn:aws:acm:us-east-1:123456789012:certificate/xxxx-xxxx-xxxx \
      TaskCPU=4096 \
      TaskMemory=8192

Configuring a database

By default the stack runs Sentinel with its own embedded storage — nothing else to configure, but enable EnablePersistence so that storage survives task recreation. For an external database instead, set DatabaseUrl and DatabaseUrlVarName:

aws cloudformation deploy \
  --template-file altcha-sentinel-aws-ecs.yml \
  --stack-name altcha-sentinel-stack \
  --capabilities CAPABILITY_IAM \
  --parameter-overrides \
      DatabaseUrl="postgresql://user:password@your-db-host:5432/altcha_sentinel" \
      DatabaseUrlVarName=POSTGRES_URL

DatabaseUrlVarName selects which environment variable the connection string is passed as, matching the engine — POSTGRES_URL (default), MYSQL_URL, MARIADB_URL, MSSQL_URL, or LIBSQL_URL. See Databases for engine details.

Other configuration

• SecretSeed — derives Sentinel's internal secrets (JWT_SECRET, ALTCHA_HMAC_SECRET, CODE_CHALLENGE_SECRET, EXOTDB_HMAC_SECRET, HASHING_SALT) deterministically from one fixed value. Without it, these are auto-generated randomly on startup, which invalidates sessions on every task restart — set it for anything beyond a quick test.

• LicenseKey — your Sentinel license key. See License.

• RedisUrl — connection string for an external Redis/Valkey instance. See Databases.

• NodeId — a unique node identifier.

• BaseUrl — base URL Sentinel uses for absolute links.

• AllowedHosts — comma-separated, wildcard-supported list of hostnames Sentinel will accept requests for.

• ExtraEnvName1/2/3 / ExtraEnvValue1/2/3 — three generic slots for any other environment variable the named parameters don't cover:

  --parameter-overrides ExtraEnvName1=SOME_VAR ExtraEnvValue1=some-value

Any parameter left at its default (empty string) is simply not passed to the container — Sentinel falls back to its own defaults or auto-generated values.

All parameters

Step 2 — Access the application

Once the stack is up, Sentinel is reachable through the ALB:

• Web interface: https://[your-alb-dns].elb.amazonaws.com/
• API: https://[your-alb-dns].elb.amazonaws.com/v1
• API documentation: https://[your-alb-dns].elb.amazonaws.com/v1/docs

Or at your custom domain, if you set DomainName and CertificateArn.

Sign in with the default credentials root / root and change the password immediately.

Production configuration

Production deployments should run multiple replicas for high availability, which needs four parameters set identically across every task:

aws cloudformation deploy \
  --template-file altcha-sentinel-aws-ecs.yml \
  --stack-name altcha-sentinel-stack \
  --capabilities CAPABILITY_IAM \
  --parameter-overrides \
      SecretSeed="<a long random string, identical on every node>" \
      LicenseKey="<license key>" \
      DatabaseUrl="postgresql://user:password@your-db-host:5432/altcha_sentinel" \
      DatabaseUrlVarName=POSTGRES_URL \
      RedisUrl="redis://default@your-redis-host:6379"

See Clustering for what each variable does, and ENV Variables for the full reference.

Upgrading Sentinel

Redeploy the stack with a pinned ImageURI:

aws cloudformation deploy \
  --template-file altcha-sentinel-aws-ecs.yml \
  --stack-name altcha-sentinel-stack \
  --capabilities CAPABILITY_IAM \
  --parameter-overrides \
      ImageURI=public.ecr.aws/n6m6b4n8/altcha-org/sentinel:1.2.3

Updates roll out with zero downtime. Prefer pinning an explicit version tag over latest so upgrades are deliberate — see Releases for available versions.

Next steps

• Configure — set up your first Security Group and API Key.
• Monitoring & Logging — track Sentinel's health once it's live.