Deployment System Requirements¶
Use this sheet to choose the smallest deployment shape that still matches the workflow you need.
Summary Matrix¶
| Deployment method | Minimum compute | Storage | Database | Network exposure | Best fit |
|---|---|---|---|---|---|
| Native development | 4 CPU cores, 8 GB RAM recommended | 5 GB free | SQLite by default | Localhost | Fastest code iteration |
| Local Compose | 2 CPU cores, 4 GB RAM minimum | 5 GB free | SQLite | Localhost/container ports | Personal testing |
| Local Auth Compose | 2 CPU cores, 4 GB RAM minimum | 5 GB free | SQLite | Localhost/container ports + Clerk | Auth flow testing |
| Enterprise Compose | 4 CPU cores, 8 GB RAM minimum | 20 GB free | Compose PostgreSQL | Host ports or reverse proxy | Single-host team deployment |
| Enterprise Compose + monitoring | 4-8 CPU cores, 16 GB RAM recommended | 40 GB free | Compose PostgreSQL | Host ports or reverse proxy | Single-host production with observability |
AWS dev-ec2 local |
t3.small default |
40 GB gp3 default | SQLite | Public EC2 ports 3000/8080/8000 | Disposable AWS dev box |
AWS dev-ec2 enterprise |
t3.medium recommended |
60 GB gp3 recommended | Compose PostgreSQL on EC2 | Public EC2 ports 3000/8080/8000 | Single-box cloud profile testing |
AWS dev-fargate |
1 API task + 1 web task, 512 CPU/1024 MiB each | RDS 20 GB | RDS PostgreSQL | Public ALB | Low-cost ECS parity |
| AWS staging | 1+ API task + 1+ web task | RDS 20+ GB | RDS PostgreSQL | Public ALB, optional TLS | Managed pre-production |
| AWS production | 2+ API tasks + 2+ web tasks | RDS 100+ GB | Multi-AZ RDS PostgreSQL recommended | Public ALB with TLS | Managed production |
Azure dev-container-apps |
0-1 API replicas + 0-1 web replicas, 0.5 CPU/1 GiB each | PostgreSQL 32 GB | PostgreSQL Flexible Server | Public Container Apps FQDNs | Low-cost Azure parity |
| Azure staging | 1+ API replica + 1+ web replica | PostgreSQL 32+ GB | PostgreSQL Flexible Server | Public Container Apps FQDNs | Managed Azure pre-production |
| Azure production | 2+ API replicas + 2+ web replicas | PostgreSQL 128+ GB | Zone-redundant PostgreSQL Flexible Server recommended | Public Container Apps FQDNs, optional edge routing | Managed Azure production |
Local And Compose¶
| Method | Requirements |
|---|---|
| Native development | Python 3.12, Node.js 20, pnpm, Git, 4 CPU cores, 8 GB RAM recommended, 5 GB free disk. |
| Local Compose | Docker Engine v24+ or Podman v4.7+, Docker Compose v2 or podman compose, 2 CPU cores, 4 GB RAM, 5 GB free disk. |
| Local Auth Compose | Same as Local Compose, plus a Clerk application and Clerk publishable/JWKS/issuer settings. |
| Enterprise Compose | Docker/Podman Compose runtime, 4 CPU cores, 8 GB RAM minimum, 20 GB free disk, PostgreSQL container volume, production-grade secrets. |
| Enterprise + monitoring | Enterprise Compose requirements plus 16 GB RAM recommended and 40 GB free disk for Prometheus, Grafana, Loki, and logs. |
Use Compose for local and single-host deployments when you want the simplest operational surface and can tolerate host-level scaling limits.
AWS Dev EC2¶
dev-ec2 provisions one EC2 instance and runs the existing Docker Compose profiles on that instance. It does not use RDS.
| Profile | Instance guidance | Dependencies |
|---|---|---|
local |
t3.small, 40 GB gp3 |
SQLite and all containers on the instance. |
local-auth |
t3.small, 40 GB gp3 |
SQLite, Clerk settings, and all containers on the instance. |
enterprise |
t3.medium, 60 GB gp3 recommended |
Compose-managed PostgreSQL and all app containers on the instance. |
AWS requirements:
- AWS account with permissions for EC2, VPC, IAM, SSM, CloudWatch Logs, and Elastic IPs.
- Terraform installed locally or available in CI.
- Optional EC2 key pair for SSH; SSM Session Manager is enabled through the instance profile.
- Inbound CIDRs restricted for real use. The examples default to open access for disposable testing.
Operational notes:
- Bootstrap logs are written to
/var/log/skillmeat-user-data.logand/var/log/cloud-init-output.log. - Secrets in
secret_env_varsare written into Terraform state and EC2 user data before being rendered to/opt/skillmeat/.env. - This method is for development and profile validation, not high availability.
AWS Fargate And RDS¶
dev-fargate, staging, and production use ECS Fargate for API/web containers and RDS PostgreSQL for the enterprise database.
| Environment | Compute | Database | Network | Notes |
|---|---|---|---|---|
dev-fargate |
1 API task and 1 web task, 512 CPU/1024 MiB each | db.t4g.micro, 20 GB, deletion protection off |
Public ECS tasks behind ALB, no NAT | Lowest-cost ECS parity. |
staging |
1+ API task and 1+ web task | db.t4g.micro or larger |
ALB, optional TLS/DNS | Pre-production validation. |
production |
2+ API tasks and 2+ web tasks recommended | db.t4g.small or larger, Multi-AZ recommended, backups enabled |
ALB with TLS, private ECS/RDS networking | Production baseline. |
AWS requirements:
- AWS account with permissions for VPC, EC2 networking, ALB, ECS, IAM, CloudWatch Logs, RDS, Secrets Manager, and Route53/ACM when DNS/TLS is enabled.
- Terraform installed locally or available in CI.
- Published API and web container images. Prefer immutable GHCR tags over
latest. - Optional Secrets Manager repository credentials if image pulls require registry authentication.
- Secure remote Terraform state before applying shared environments.
Azure Container Apps And PostgreSQL¶
dev-container-apps, staging, and production use Azure Container Apps for API/web containers and Azure Database for PostgreSQL Flexible Server for the enterprise database.
| Environment | Compute | Database | Network | Notes |
|---|---|---|---|---|
dev-container-apps |
Scale-to-zero API/web replicas, 0.5 CPU/1 GiB each | B_Standard_B1ms, 32 GB |
Public Container Apps ingress, private PostgreSQL subnet | Lowest-cost Azure managed parity. |
staging |
1+ API replica and 1+ web replica | B_Standard_B1ms or larger |
Public Container Apps ingress, private PostgreSQL subnet | Pre-production validation. |
production |
2+ API replicas and 2+ web replicas recommended | GP_Standard_D2s_v3 or larger, zone-redundant HA recommended |
Public Container Apps ingress, private PostgreSQL subnet | Production baseline. |
Azure requirements:
- Azure subscription with permissions for resource groups, VNets/subnets, Container Apps, managed identities, Key Vault, Log Analytics, and PostgreSQL Flexible Server.
- Terraform installed locally or available in CI.
- Published API and web container images. Prefer immutable GHCR tags over
latest. - Optional registry credentials if image pulls require GHCR authentication.
- Secure remote Terraform state before applying shared environments.
External Services¶
| Service | Required when |
|---|---|
| Clerk | local-auth, enterprise auth, or any deployment with SKILLMEAT_AUTH_ENABLED=true. |
| GitHub token | Recommended for marketplace/discovery usage to avoid low unauthenticated rate limits. |
| DNS + ACM certificate | Recommended for public AWS staging/production. |
| DNS + Azure Front Door/Application Gateway | Optional when Azure environments need one public hostname or edge TLS/routing. |
| Remote Terraform backend | Required before shared AWS or Azure environments are treated as durable infrastructure. |
Capacity Guidance¶
Start small for dev and scale only after metrics show pressure:
- Increase API task CPU/memory when request latency or migrations are CPU-bound.
- Increase web task CPU/memory when Next.js startup or SSR routes are slow.
- Increase RDS class/storage when database CPU, IOPS, or connection counts approach limits.
- Increase PostgreSQL Flexible Server SKU/storage when database CPU, IOPS, or connection counts approach limits.
- Add NAT or private ECS subnets when the environment must avoid public task networking.
- Move from EC2 dev mode to Fargate/RDS when you need production-parity networking, IAM, and service isolation.