# Bellona Remote — Production AWS Deployment (180.C.25.09)

Production-ready Terraform for the Bellona Remote Gateway on AWS: an
internet-facing Application Load Balancer, the gateway on ECS Fargate, RDS
PostgreSQL, ElastiCache Redis, an S3 artifact bucket, CloudWatch logs/alarms, a
coturn TURN relay on EC2, automated backups, and a smoke test.

> **Honesty note.** This Terraform IS the deliverable and is validated with
> `terraform init`, `terraform validate`, and `terraform fmt -check` (all pass —
> AWS provider `~> 5.0`). The live `terraform apply` is account/credential-gated
> and is **not** run here — it would create real, billable AWS resources. After
> a real apply, run the [smoke test](../smoke/smoke-test.sh) against the ALB; it
> **fails loud** (exit non-zero) without a deployed URL and never fabricates a
> pass.

## Topology

```
                     internet
                        │ 80 → 301 → 443 (ACM cert)
                        ▼
              ┌──────────────────┐  public subnets (2 AZ)
              │   ALB (HTTPS/WSS) │
              └─────────┬─────────┘
        target group :4070 (IP targets, /health check, sticky)
                        ▼
              ┌──────────────────┐  private subnets (2 AZ)
              │ ECS Fargate       │──┬─ RDS Postgres (multi-AZ, encrypted, backups)
              │ gateway tasks x2  │  ├─ ElastiCache Redis (TLS, failover)
              └──────────────────┘  └─ S3 artifacts (versioned, lifecycle)
                        │ secrets from Secrets Manager, logs → CloudWatch
                        │
   ┌──────────────────┐ EC2 + Elastic IP, public subnet
   │ coturn TURN relay │  3478/5349 + relay 49160-49200  (180.C.25.04)
   └──────────────────┘
```

- **ALB** is the only public HTTP edge; it forwards `:4070` to the gateway
  target group and only the ALB security group can reach the gateway.
- **Gateway** runs as Fargate tasks in private subnets, egress via NAT.
- **RDS** and **Redis** accept connections only from the gateway security group.
- **S3** blocks all public access; versioning + lifecycle are enabled.
- **TURN** runs on EC2 with a stable Elastic IP (Fargate can't host a wide UDP
  relay range well).

## Files

| File                       | Contents                                                           |
| -------------------------- | ------------------------------------------------------------------ |
| `versions.tf`              | Terraform + provider pins (`aws ~> 5.0`), S3 backend (commented).  |
| `variables.tf`             | All inputs (sizes, domain, secrets, retention).                    |
| `network.tf`               | VPC, public/private subnets, IGW, NAT, route tables.               |
| `security.tf`              | SG-referenced rules (alb→gateway→rds/redis; turn public).          |
| `data-plane.tf`            | RDS Postgres, ElastiCache Redis, S3 bucket + versioning/lifecycle. |
| `gateway.tf`               | ALB, target group, listeners, ECS cluster/service/task, IAM, logs. |
| `turn.tf`                  | coturn EC2 + Elastic IP + cloud-init.                              |
| `secrets.tf`               | Secrets Manager secret + generated RDS password.                   |
| `monitoring.tf`            | CloudWatch alarms (ALB/ECS/RDS/EC2) + SNS + dashboard.             |
| `outputs.tf`               | ALB DNS, gateway URL, TURN IP, endpoints, log group, SNS ARN.      |
| `terraform.tfvars.example` | Example variables (copy → `terraform.tfvars`).                     |

## Env wiring (mirrors the gateway config)

The ECS task definition (`gateway.tf`) sets the gateway env from
`apps/bellona/remote-gateway/src/config.ts`:

- Non-secret env: `NODE_ENV`, `BELLONA_REMOTE_GATEWAY_HOST=0.0.0.0`,
  `BELLONA_REMOTE_GATEWAY_PORT`, `…_LOG_LEVEL`, `…_HOST_TOKEN_TTL_MS`, plus the
  S3/TURN coordinates.
- **Secrets** (`secrets` block, from Secrets Manager — never plaintext):
  `BELLONA_REMOTE_GATEWAY_HOST_TOKEN_SIGNING_SECRET`, `BELLONA_DATABASE_URL`
  (`…?sslmode=require`), `REDIS_URL` (`rediss://`),
  `BELLONA_TURN_STATIC_AUTH_SECRET`.

`HOST=0.0.0.0` is safe because the gateway SG only admits the ALB on `:4070`.

## Deploy

### 1. Prerequisites

- An ACM **public certificate** for `gateway_domain` in `aws_region`,
  DNS-validated (for auto-renewal). Paste its ARN into `acm_certificate_arn`.
- The gateway image pushed to ECR (or another registry your account can pull).
- A remote state backend (uncomment the `backend "s3"` block in `versions.tf`
  and pre-create the bucket + lock table — see
  `deploy/terraform/backend-bootstrap`).

### 2. Configure

```sh
cd infra/bellona-remote/aws
cp terraform.tfvars.example terraform.tfvars   # KEEP OUT OF GIT (.gitignore'd)
# Fill in: gateway_domain, acm_certificate_arn, gateway_image, and the two
# secrets. Generate secrets with: openssl rand -base64 48
$EDITOR terraform.tfvars
```

### 3. Plan + apply

```sh
terraform init
terraform plan
terraform apply
```

### 4. DNS

Point `gateway_domain` at the ALB using the outputs:

```sh
terraform output alb_dns_name   # CNAME target (or Route 53 alias → alb_zone_id)
```

### 5. Smoke test

```sh
BELLONA_SMOKE_BASE_URL="$(terraform output -raw gateway_base_url)" ../smoke/smoke-test.sh
```

Asserts `/health`, `/ready`, the `/v1/pairing/exchange` rejection, and
`/v1/devices`. Without `BELLONA_SMOKE_BASE_URL` it exits non-zero.

## Backups

- **RDS**: automated daily snapshots retained `postgres_backup_retention_days`
  (default 14), `copy_tags_to_snapshot`, a final snapshot on delete, and
  `deletion_protection`. Point-in-time restore is available within the window.
- **S3**: versioning enabled + a lifecycle rule expiring prior versions after 90
  days and aborting dangling multipart uploads after 7 days, so an
  overwritten/deleted artifact is recoverable.
- **Redis**: daily snapshots retained 7 days.

## Monitoring & logs

- **Logs**: the gateway logs to CloudWatch group `/bellona/<env>/remote-gateway`
  (retention `log_retention_days`); RDS exports `postgresql` logs to CloudWatch.
- **Alarms** (→ SNS `alarms_sns_topic_arn`; subscribe email/PagerDuty): ALB
  no-healthy-hosts, ALB 5xx, ECS CPU, RDS CPU, RDS low storage, TURN EC2 status
  check.
- **Dashboard**: `${name_prefix}-${environment}-gateway` (ALB requests/5xx +
  healthy hosts).

## TURN / TLS notes

`turn.tf` cloud-init installs coturn with the shared static-auth-secret and the
instance's Elastic IP as `external-ip`. For TURN-over-TLS (`:5349`), install a
certificate for `gateway_domain` on the instance (ACM-exported or certbot) and
add `cert=`/`pkey=` lines, then restart coturn. The gateway derives short-lived
TURN credentials from the same `turn_static_auth_secret`, and the WebRTC
direct-vs-relay metric (`180.C.25.04`) records this server as the relay when a
session falls back to it.

## Limitations (honest)

- `terraform apply` is **not** run here (account-gated, billable). The config is
  validated for syntax + consistency (`terraform validate` / `fmt -check` pass).
- The gateway ships a first-stage JSON store today; RDS/Redis/S3 are provisioned
  and wired (correct SGs, endpoints, secrets) ahead of the gateway's
  persistence/artifact code paths consuming them. On Fargate, that JSON store is
  per-task ephemeral until those paths land — run a single task, or front it
  with the RDS store, for durable state until then.
- TURN TLS requires a one-time cert install on the EC2 instance (documented
  above); the relay itself (STUN/TURN/UDP) works from cloud-init as written.
- A live WebRTC media-relay smoke (an actual relayed session through coturn)
  needs real peers and is outside the smoke script; the metric classification it
  feeds is unit-tested in `libs/bellona/remote-protocol/src/stream.test.ts`.
