Expand AWS integration docs with ECS launch types and EC2 storage guide (#4734)

Links to new updated AWS deployment code: https://github.com/electric-sql/electric-aws

Author: magnetised

website/docs/sync/api/config.md

@@ -566,6 +566,8 @@ If provided must be one of `MEMORY` or `FAST_FILE`.
 
 Path to root folder for storing data on the filesystem.
 
+This must be persistent storage that survives restarts. See [Optimizing for disk](/docs/sync/guides/deployment#optimizing-for-disk) in the deployment guide for what to run it on.
+
 </EnvVarConfig>
 
 ## Telemetry

website/docs/sync/guides/deployment.md

@@ -129,19 +129,23 @@ You can deploy it anywhere you can run a container with a filesystem and exposed
 - [Fly.io](/docs/sync/integrations/fly)
 - [Render](/docs/sync/integrations/render)
 
+The [AWS guide](/docs/sync/integrations/aws#deploy-electric) goes into the most depth, covering how to choose an ECS launch type and storage backing. It comes with [example Terraform and Pulumi configurations](https://github.com/electric-sql/electric-aws) that provision the whole stack — database, sync service and load balancer.
+
 ### Docker container
 
 Images are deployed to Docker Hub at [electricsql/electric](https://hub.docker.com/r/electricsql/electric).
 
 ### Optimizing for disk
 
-Electric caches [Shape logs](/docs/sync/api/http#shape-log) and metadata on the filesystem. Your Electric host must provide a persistent filesystem. Ideally this should be large, fast and locally mounted, such as a NVMe SSD. If you're configuring a machine and you want to optimise it for Electric, the factors to optimise for, in order of important, are:
+Electric caches [Shape logs](/docs/sync/api/http#shape-log) and metadata on the filesystem. Your Electric host must provide a persistent filesystem. Ideally this should be large, fast and locally mounted, such as a NVMe SSD. If you're configuring a machine and you want to optimise it for Electric, the factors to optimise for, in order of importance, are:
 
 1. disk speed — low latency, high throughput reads and writes
 2. memory
 3. CPU
 
-For example, on AWS, [Storage Optimized](https://aws.amazon.com/ec2/instance-types/#Storage_Optimized) instances such as the `i3en.large`, or on Hetzner the [SX-line](https://www.hetzner.com/dedicated-rootserver/matrix-sx/) of dedicated servers would both be great choices.
+For example, on AWS, [storage optimized](https://aws.amazon.com/ec2/instance-types/#Storage_Optimized) instances such as the `i4i` family, or general purpose instances that ship local NVMe such as `m6id`, are both good choices. On Hetzner, the [SX-line](https://www.hetzner.com/dedicated-rootserver/matrix-sx/) of dedicated servers works well.
+
+For a worked example, see [ECS on EC2](/docs/sync/integrations/aws#ecs-on-ec2) in the AWS guide. It covers choosing between local NVMe and an attached EBS volume, and [preparing the disk on boot](/docs/sync/integrations/aws#bootstrapping-the-data-disk).
 
 ### Configuring storage
 

website/docs/sync/guides/upgrading.md

@@ -226,6 +226,8 @@ With `maxSurge: 1` and `maxUnavailable: 0`, Kubernetes will:
 
 This example uses EC2 launch type with a host bind mount for shared storage. Both old and new tasks share the same directory on the EC2 host.
 
+See [ECS on EC2](/docs/sync/integrations/aws#ecs-on-ec2) in the AWS guide for how to provision this. The [example configurations](https://github.com/electric-sql/electric-aws) run a single container instance per cluster, which satisfies the placement requirement below.
+
 > [!Warning] Same-host placement
 > ECS does not guarantee that the new task lands on the same host as the old one. To ensure both tasks share the same host volume, your ECS cluster must have exactly one EC2 instance matching your placement constraint, or use a custom instance attribute to pin tasks to a specific host.
 

website/docs/sync/integrations/aws.md

@@ -39,16 +39,74 @@ GRANT rds_replication TO someuser;
 
 ### Deploy Electric
 
-AWS provides a [wide range of container hosting](https://aws.amazon.com/containers). For example, you can deploy Electric to [AWS Elastic Container Service](https://aws.amazon.com/efs) using [AWS Fargate](https://aws.amazon.com/fargate).
+The recommended way to run Electric on AWS is [Elastic Container Service](https://aws.amazon.com/ecs) (ECS). We maintain example [Terraform and Pulumi configs](#examples) that stand up everything described below.
 
-You should store Shape logs to a persistent disk (not an ephemoral filesystem). For example using [Amazon Elastic File System](https://aws.amazon.com/efs).
+Electric caches [shape logs](/docs/sync/api/http#shape-log) on disk and treats them as a rebuildable cache: if the disk is lost, Electric rebuilds from Postgres. Disk speed directly drives sync performance, so the main deployment decision is where that disk lives. There are three good options on ECS:
+
+| Launch type | Storage | Characteristics |
+|---|---|---|
+| [Fargate](https://aws.amazon.com/fargate/) | Ephemeral task storage | Simplest; cache is lost on every deploy |
+| EC2, storage‑optimized instance (`i4i`, `m6id`) | Local NVMe instance store | Fastest possible disk; survives task restarts, not host replacement |
+| EC2, compute instance (`m6a`, `m6i`, `m7a`, `m7i`) | Attached gp3 EBS data volume | Cheaper; IOPS and throughput independently tunable, in place |
+
+Fargate is fine for evaluation and light workloads. For production workloads, EC2 gives you dramatically better disk for the money — this is how [Electric Cloud](/cloud/) runs.
+
+#### ECS on EC2
+
+The pattern our example configs implement is one task per host:
+
+- A **launch template** using the ECS-optimized Amazon Linux 2023 AMI, with a user-data boot script (below) that prepares the data disk and joins the instance to the cluster.
+- An **auto scaling group** (min = max = 1) with scale-in protection and a termination lifecycle hook, so ECS can drain tasks before an instance is replaced.
+- An **ECS capacity provider** with managed scaling and managed termination protection, which lets ECS drive the ASG rather than you managing instances directly.
+- A **task definition** sized to the whole host: all of its vCPUs, and its memory minus ~2 GiB for the OS, Docker and ECS agent. (Undersize this reservation and task placement fails with `RESOURCE:MEMORY` errors.) The task uses `awsvpc` networking behind an ALB targeting `/v1/health`.
+
+#### Bootstrapping the data disk
+
+Both storage options — local NVMe instance store and attached gp3 EBS — appear as non-root `/dev/nvme*` devices on Nitro instances, so a single boot script handles either. On first boot it:
+
+1. finds every non-root NVMe device, waiting up to 60s (EBS volumes attach asynchronously; instance store is present immediately)
+2. RAID0s them with `mdadm` if there's more than one (larger `i4i`/`m6id` sizes ship multiple disks)
+3. formats XFS and mounts at `/mnt/nvme` with `noatime`, by filesystem UUID rather than device path (NVMe enumeration order isn't guaranteed, and a reassembled RAID array can come back under a different name)
+4. creates a data directory owned by uid 1000 (the Electric container user) and writes the ECS cluster-join config
+
+The task then bind-mounts that directory and sets [`ELECTRIC_STORAGE_DIR`](/docs/sync/api/config#electric-storage-dir) to it. The full script is [`shared/user-data.sh.tpl`](https://github.com/electric-sql/electric-aws/blob/main/shared/user-data.sh.tpl) in the examples repo; its core is:
+
+```bash
+# Discover non-root NVMe devices (instance store or EBS — both
+# appear as /dev/nvme* on Nitro hosts).
+DEVS=$(nvme list -o json | jq -r --arg root "$ROOT_PATH" \
+  '.Devices[] | select(.DevicePath != $root) | .DevicePath')
+
+# RAID0 multiple disks, else use the single device.
+if [ "$COUNT" -gt 1 ]; then
+  mdadm --create /dev/md0 --level=0 --raid-devices="$COUNT" $DEVS
+  TARGET=/dev/md0
+fi
+
+mkfs.xfs -f "$TARGET"
+
+# Name the disk by UUID, since fstab is consulted on every later boot
+# but this script only runs on the first one. nofail keeps a blank disk
+# (instance store is wiped by a stop/start) from wedging that boot.
+FS_UUID=$(blkid -p -s UUID -o value "$TARGET")
+echo "UUID=$FS_UUID /mnt/nvme xfs defaults,noatime,nodiscard,nofail 0 2" >> /etc/fstab
+mount /mnt/nvme
+
+echo "ECS_CLUSTER=${cluster_name}" >> /etc/ecs/ecs.config
+```
+
+#### Sizing storage
+
+For **gp3 EBS**, size, IOPS and throughput are independent knobs you can raise later without downtime (`terraform apply` / `pulumi up` modifies the volume in place; size can grow but never shrink). The 3,000 IOPS / 125 MB/s baseline is free and roughly matches Fargate ephemeral storage; scale up if you see IO wait on shape recomputes or cold starts.
+
+For **NVMe instance store**, capacity comes with the instance type — e.g. 118 GB on an `m6id.large`, 468 GB on an `i4i.large`, with `i4i` giving ~4x the storage per vCPU. You can't tune it, but it's far faster than any networked volume.
+
+Either way, remember the disk contents don't need to survive host replacement — Electric re-syncs from Postgres — but replacing a host does mean re-syncing, so prefer in-place tuning over instance-type churn once you're in production.
 
 ### Deploy your app
 
 AWS provides a range of [website hosting options](https://aws.amazon.com/getting-started/hands-on/host-static-website/). For example you can deploy a static app to [AWS Amplify](https://aws.amazon.com/amplify).
 
 ## Examples
 
-### AWS Terraform
-
-We have an example Terraform repo at [electric-sql/terraform-aws](https://github.com/electric-sql/terraform-aws).
+The [electric-sql/electric-aws](https://github.com/electric-sql/electric-aws) repo contains equivalent [Terraform](https://github.com/electric-sql/electric-aws/tree/main/terraform) and [Pulumi](https://github.com/electric-sql/electric-aws/tree/main/pulumi) configs implementing everything on this page — VPC, RDS with logical replication, ECS (Fargate or EC2 with either storage option) and an ALB.