Overview

HyperSaaS deploys to AWS: the backend and frontend run as containers on ECS Fargate, behind one load balancer, with PostgreSQL (RDS), Valkey (ElastiCache) and a private S3 bucket. Terraform defines all of it, and GitHub Actions deploys every merge to main.

• AWS: first deployment takes you from an empty AWS account to a working staging site, in 10 steps.
• AWS: running it covers deploys, rollbacks, logs, keys, backups, costs and going to production.

The repository also has docker-compose.production.yml, which runs everything on one server behind Traefik. It builds the same images, but these docs cover AWS.

The AWS layout

flowchart TB
    internet(["Internet"])
    subgraph vpc["VPC 10.20.0.0/16, two availability zones"]
        igw["Internet gateway"]
        subgraph public["Public subnets"]
            alb["Load balancer<br/>accepts 80 and 443 from anywhere"]
            tasks["ECS tasks: web, worker, beat, frontend<br/>public IP, but accept traffic<br/>only from the load balancer"]
        end
        subgraph private["Private subnets (no internet route)"]
            rds[("RDS PostgreSQL<br/>port 5432, from the tasks only")]
            cache[("Valkey<br/>port 6379, from the tasks only")]
        end
    end
    aws_services(["S3, ECR, Secrets Manager,<br/>CloudWatch, AI providers, Stripe"])

    internet --> igw --> alb
    alb -- "5000 (web), 3000 (frontend)" --> tasks
    tasks --> rds
    tasks --> cache
    tasks -- "outbound" --> igw --> aws_services

The tasks sit in public subnets with public IP addresses. That lets them reach ECR, Secrets Manager and the AI providers without a NAT gateway. Their security group accepts connections only from the load balancer, so nothing on the internet can reach them directly. The database and the cache sit in private subnets with no route to the internet, and accept connections only from the tasks.

Who can do what (IAM)

No long-lived AWS keys exist anywhere: not in GitHub, and not in the containers.

flowchart LR
    subgraph github["GitHub Actions"]
        release["Release workflow<br/>(main branch)"]
        deploy["Deploy workflow<br/>(staging environment, main only)"]
    end
    oidc["GitHub OIDC provider<br/>(in IAM)"]
    publisher["image publisher role"]
    deployrole["staging deploy role"]
    ecr[("ECR")]
    ecs["ECS: task definitions,<br/>services, one-off tasks"]

    subgraph task["Each running task"]
        execution["execution role<br/>pull the image, read the secrets,<br/>write logs"]
        taskrole["task role<br/>S3 bucket, ECS Exec"]
    end

    release -- "short-lived token" --> oidc --> publisher -- "push images" --> ecr
    deploy -- "short-lived token" --> oidc --> deployrole -- "register, run, update" --> ecs
    ecs -. "starts tasks with" .-> task

• The image publisher role (from the bootstrap stack) can push to the image repositories. Only workflows on the main branch of your two repositories can use it.

• Each environment's deploy role can, in that environment's cluster only:

  • register task definitions
  • run the migration task
  • update the services
  • read the migration logs

  Only jobs running in the matching GitHub environment can use it, and that environment only accepts the main branch.

• The task role gives the backend its S3 access. Django uses it automatically, with no AWS keys set.

• Repositories are named by number. GitHub's tokens name repositories by their numeric IDs (owner@<id>/repo@<id>), and the roles trust those IDs. A renamed account, or a new repository with an old name, can't take a role over.

Infrastructure

The CloudWatch alarms fire on:

• more than 10 server errors in 5 minutes
• an unhealthy web or frontend task for 3 minutes
• database CPU above 80% for 15 minutes
• less than 2 GB of free database storage

Why ECS on Fargate, compared with the alternatives:

Why there's no NAT gateway: a NAT gateway costs about $35 a month per zone, plus data charges, only so that private tasks can reach the internet. Public IP addresses cost about $3.65 a month each, and the security groups still keep the tasks unreachable from outside.

Why there are two backend images: Docling, PyTorch and their models add about 3 GB, and only the worker needs them. Fargate pulls the whole image every time a task starts. Without them, the web image (about 1 GB) starts faster and uses less memory.

CI/CD

flowchart LR
    merge(["Merge to main"]) --> ci["CI<br/>tests"]
    ci -- "passed" --> images["Release<br/>build images"]
    images -- "push, tagged with the commit" --> ecr[("ECR")]
    images --> register["Deploy<br/>new task definition revisions"]
    register --> migrate["Run migrations<br/>(one-off task)"]
    migrate -- "succeeded" --> update["Update the services"]
    update --> wait{"Rollout<br/>completed?"}
    wait -- "yes" --> done(["Live on staging"])
    wait -- "no: ECS rolled back" --> failed(["Job fails;<br/>the old version keeps running"])
    migrate -- "failed" --> stopped(["Job fails;<br/>nothing changed"])

Two rules of the pipeline:

• Terraform owns the settings, and Deploy owns the image. Deploy copies the latest task definition revision of each process and changes only the image. A setting changed in Terraform (an environment variable, CPU, memory) reaches the running services at the next deploy.
• Migrations run while the old version still serves traffic. Each migration must work with the code before it. Add a column in one release and use it in the next; drop a column only once no running code reads it.

Local development

Locally, Docker Compose runs everything (docker-compose.local.yml; see Docker):

Settings

config/settings/
    ├── base.py        # Shared settings (apps, middleware, DRF, sign-in and tokens, Celery)
    ├── local.py       # DEBUG=True, Mailpit, LocMemCache, eager Celery
    ├── production.py  # gunicorn, S3 for files, WhiteNoise for static files, Sentry, secure cookies, logging
    └── test.py        # Fast password hashing, in-memory email

Select the settings module via DJANGO_SETTINGS_MODULE:

# Local
DJANGO_SETTINGS_MODULE=config.settings.local

# Production
DJANGO_SETTINGS_MODULE=config.settings.production

# Tests
DJANGO_SETTINGS_MODULE=config.settings.test

Key dependencies

Python version

Python 3.12 is required. Docling and PyTorch don't support 3.13 yet.