AWS Deployment

WhoDB provides CloudFormation templates for deploying on AWS. They're ordered from simplest to most fully-featured:

Prerequisites

• AWS CLI configured with credentials (aws configure)
• An AWS account with permissions to create VPC, ECS, and IAM resources
• An ACM certificate in the same region as your stack (required for the production stack, optional for self-hosted)

Production Stack

The fastest way to get WhoDB running on AWS. No options to think about — HTTPS, private Fargate tasks, and AWS database discovery are baked in.

What's included

Deploy

Parameters

Tear down

No deletion protection — just delete:

aws cloudformation delete-stack --stack-name whodb-prod

Self-Hosted Stack

More flexibility than the production stack. Supports using an existing VPC, HTTP-only mode, internal ALBs, and toggling AWS discovery. Use this when the production stack's baked-in defaults don't fit your environment.

Deployment modes

Deploy

Parameters

Demo Stack

The demo stack deploys WhoDB alongside RDS PostgreSQL, ElastiCache Redis, and DocumentDB, with production hardening enabled by default. Use this for demos, evaluations, and showcasing.

What's included

Deploy

Parameters

Retrieve generated credentials

Credentials are stored in Secrets Manager and used automatically by WhoDB's AWS provider for discovery. To retrieve them manually:

aws secretsmanager get-secret-value \
  --secret-id $(aws cloudformation describe-stacks --stack-name whodb-demo \
    --query 'Stacks[0].Outputs[?OutputKey==`DBSecretArn`].OutputValue' --output text) \
  --query 'SecretString' --output text | jq .

Tear down

Deletion protection is enabled by default. Disable it before deleting:

# Disable deletion protection
aws cloudformation update-stack \
  --stack-name whodb-demo \
  --use-previous-template \
  --capabilities CAPABILITY_IAM \
  --parameters \
    ParameterKey=CertificateArn,UsePreviousValue=true \
    ParameterKey=DeletionProtection,ParameterValue=false

# Wait for update, then delete
aws cloudformation wait stack-update-complete --stack-name whodb-demo
aws cloudformation delete-stack --stack-name whodb-demo

AWS auto-discovery

When AWS discovery is enabled (production and self-hosted stacks), WhoDB automatically discovers:

• RDS instances (PostgreSQL, MySQL, MariaDB)
• ElastiCache clusters (Redis)
• DocumentDB clusters (MongoDB-compatible)

Discovered databases appear on WhoDB's login page. You still need to provide credentials to connect — discovery only finds the endpoints.

Alarm notifications

The demo and self-hosted stacks include CloudWatch alarms. By default, alarms change state but don't notify anyone. To receive alerts, create an SNS topic and pass it:

# Create an SNS topic and subscribe your email
SNS_ARN=$(aws sns create-topic --name whodb-alarms --query TopicArn --output text)
aws sns subscribe --topic-arn $SNS_ARN --protocol email --notification-endpoint you@example.com

# Pass it during stack creation
--parameters ParameterKey=AlarmSNSTopicArn,ParameterValue=$SNS_ARN

Security considerations

Browser clients authenticate via an HttpOnly session cookie, with database credentials encrypted server-side; Authorization headers are only used by the desktop app and CLI. Production security still comes from network controls:

• HTTPS — encrypts all traffic between users and the ALB
• AllowedCIDR — restricts who can reach the ALB by IP range
• Private subnets — Fargate tasks run in private subnets, not directly accessible from the internet
• Internal ALB — optionally make the ALB accessible only within the VPC (self-hosted stack)
• Security groups — databases only accept connections from WhoDB's security group
• Invalid header dropping — ALBs drop malformed HTTP headers to prevent header injection
• ECS Exec disabled — container shell access is blocked, preventing unauthorized access via IAM

Troubleshooting

Template files

All templates are in the dev/ directory: