From ea5a9def757913a93be0339cfacb8beaf9af79b5 Mon Sep 17 00:00:00 2001 From: Conrad Hofmeyr Date: Thu, 19 Feb 2026 17:58:37 -0600 Subject: [PATCH 1/2] AWS ECS guide updates --- maintenance-ops/self-hosting/aws-ecs.mdx | 539 ++++++++++++----------- 1 file changed, 276 insertions(+), 263 deletions(-) diff --git a/maintenance-ops/self-hosting/aws-ecs.mdx b/maintenance-ops/self-hosting/aws-ecs.mdx index c21ece46..05d8ff7b 100644 --- a/maintenance-ops/self-hosting/aws-ecs.mdx +++ b/maintenance-ops/self-hosting/aws-ecs.mdx @@ -566,282 +566,295 @@ aws ecs create-cluster \ ### Register Task Definition -Generate the task definition using your environment variables: - -```bash -cat > task-definition.json < - - - -For production deployments, run separate replication and API processes to enable zero-downtime rolling updates. This allows independent scaling of API containers. - The task definitions below allocate **2 vCPU and 2GB memory** per container. You can adjust resources based on your workload — see [Deployment Architecture](/maintenance-ops/self-hosting/deployment-architecture) for scaling guidance (recommended baseline: 1 vCPU, 1GB memory). -**Step 1: Create Replication Task Definition** + -```bash -cat > replication-task-definition.json < + + For production deployments, run separate replication and API processes to enable zero-downtime rolling updates. This allows independent scaling of API containers. + + **Create Replication Task Definition** + + ```bash + cat > replication-task-definition.json < api-task-definition.json < api-task-definition.json < + - + + + This basic setup runs both replication and API processes in the same container. This is not recommended for production. + + Generate the task definition using your environment variables: + + ```bash + cat > task-definition.json < 1`) will cause **Sync Rule lock errors during rolling updates** when deploying new task definitions. + + -```bash -aws ecs create-service \ - --cluster powersync-cluster \ - --service-name powersync-service \ - --task-definition powersync-service \ - --desired-count 1 \ - --launch-type FARGATE \ - --network-configuration "awsvpcConfiguration={ - subnets=[$PRIVATE_SUBNET_1,$PRIVATE_SUBNET_2], - securityGroups=[$ECS_SG], - assignPublicIp=DISABLED - }" \ - --load-balancers "targetGroupArn=$TG_ARN,containerName=powersync,containerPort=8080" \ - --health-check-grace-period-seconds 120 \ - --deployment-configuration "minimumHealthyPercent=0,maximumPercent=100" -``` +## 7. Deploy ECS Service -**Verify Basic Deployment:** +Create the ECS service to run PowerSync tasks -```bash -# Check service status -aws ecs describe-services \ - --cluster powersync-cluster \ - --services powersync-service \ - --query 'services[0].[serviceName,status,runningCount,desiredCount]' \ - --output table + -# Wait for task to be running (takes 2-3 minutes) -echo "Waiting for tasks to start..." -sleep 60 + + + For production deployments, run separate replication and API processes to enable zero-downtime rolling updates. This allows independent scaling of API containers. + + **Deploy Replication Service (1 Instance)** + + ```bash + aws ecs create-service \ + --cluster powersync-cluster \ + --service-name powersync-replication \ + --task-definition powersync-replication \ + --desired-count 1 \ + --launch-type FARGATE \ + --network-configuration "awsvpcConfiguration={ + subnets=[$PRIVATE_SUBNET_1,$PRIVATE_SUBNET_2], + securityGroups=[$ECS_SG], + assignPublicIp=DISABLED + }" \ + --deployment-configuration "minimumHealthyPercent=0,maximumPercent=100" + ``` + + **Deploy API Service (2+ Instances)** + + ```bash + aws ecs create-service \ + --cluster powersync-cluster \ + --service-name powersync-api \ + --task-definition powersync-api \ + --desired-count 2 \ + --launch-type FARGATE \ + --network-configuration "awsvpcConfiguration={ + subnets=[$PRIVATE_SUBNET_1,$PRIVATE_SUBNET_2], + securityGroups=[$ECS_SG], + assignPublicIp=DISABLED + }" \ + --load-balancers "targetGroupArn=$TG_ARN,containerName=powersync-api,containerPort=8080" \ + --health-check-grace-period-seconds 120 \ + --deployment-configuration "minimumHealthyPercent=100,maximumPercent=200" + ``` + + **Verify HA Deployment:** + + ```bash + # Check replication service status + aws ecs describe-services \ + --cluster powersync-cluster \ + --services powersync-replication \ + --query 'services[0].[serviceName,status,runningCount,desiredCount]' \ + --output table + + # Check API service status + aws ecs describe-services \ + --cluster powersync-cluster \ + --services powersync-api \ + --query 'services[0].[serviceName,status,runningCount,desiredCount]' \ + --output table + + # Wait for tasks to be running (takes 2-3 minutes) + echo "Waiting for tasks to start..." + sleep 60 + + # Test endpoint (replace with your domain) + curl https://$POWERSYNC_DOMAIN/probes/liveness + + # View API logs + aws logs tail /ecs/powersync-api --follow + + # View replication logs + aws logs tail /ecs/powersync-replication --follow + ``` -# Test endpoint (replace with your domain) -curl https://$POWERSYNC_DOMAIN/probes/liveness + -# View logs -aws logs tail /ecs/powersync --follow -``` + + + This basic setup runs both replication and API processes in the same container. Running multiple instances (`desired-count > 1`) will cause **Sync Rule lock errors during rolling updates** when deploying new task definitions. A single-instance setup is not recommended for production. + + ```bash + aws ecs create-service \ + --cluster powersync-cluster \ + --service-name powersync-service \ + --task-definition powersync-service \ + --desired-count 1 \ + --launch-type FARGATE \ + --network-configuration "awsvpcConfiguration={ + subnets=[$PRIVATE_SUBNET_1,$PRIVATE_SUBNET_2], + securityGroups=[$ECS_SG], + assignPublicIp=DISABLED + }" \ + --load-balancers "targetGroupArn=$TG_ARN,containerName=powersync,containerPort=8080" \ + --health-check-grace-period-seconds 120 \ + --deployment-configuration "minimumHealthyPercent=0,maximumPercent=100" + ``` + + **Verify Basic Deployment:** + + ```bash + # Check service status + aws ecs describe-services \ + --cluster powersync-cluster \ + --services powersync-service \ + --query 'services[0].[serviceName,status,runningCount,desiredCount]' \ + --output table + + # Wait for task to be running (takes 2-3 minutes) + echo "Waiting for tasks to start..." + sleep 60 + + # Test endpoint (replace with your domain) + curl https://$POWERSYNC_DOMAIN/probes/liveness + + # View logs + aws logs tail /ecs/powersync --follow + ``` - + ## Production Enhancements @@ -958,23 +971,23 @@ aws events put-targets \ -### Auto Scaling +### Auto Scaling (High-Availability Setup) - -**High Availability Setup**: If you deployed using the HA setup, configure autoscaling for the `powersync-api` service instead of `powersync-service`. The replication service (`powersync-replication`) should remain at 1 instance. - + + The auto-scaling configuration below only scales basd on CPU usage. We are working on expanding this page with additional details on how to also auto-scale based on the number of concurrent connections per API pod. As seen in the [Deployment Architecture](/maintenance-ops/self-hosting/deployment-architecture) documentation, it is recommended to have 1 API pod per 100 concurrent client connections. + ```bash aws application-autoscaling register-scalable-target \ --service-namespace ecs \ - --resource-id service/powersync-cluster/powersync-service \ + --resource-id service/powersync-cluster/powersync-api \ --scalable-dimension ecs:service:DesiredCount \ --min-capacity 2 \ --max-capacity 10 aws application-autoscaling put-scaling-policy \ --service-namespace ecs \ - --resource-id service/powersync-cluster/powersync-service \ + --resource-id service/powersync-cluster/powersync-api \ --scalable-dimension ecs:service:DesiredCount \ --policy-name cpu-scaling \ --policy-type TargetTrackingScaling \ From 3f30e9c678ab0d20f11a190f55349b751dfe9df2 Mon Sep 17 00:00:00 2001 From: Conrad Hofmeyr Date: Thu, 19 Feb 2026 18:08:56 -0600 Subject: [PATCH 2/2] Typo --- maintenance-ops/self-hosting/aws-ecs.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/maintenance-ops/self-hosting/aws-ecs.mdx b/maintenance-ops/self-hosting/aws-ecs.mdx index 05d8ff7b..c486e154 100644 --- a/maintenance-ops/self-hosting/aws-ecs.mdx +++ b/maintenance-ops/self-hosting/aws-ecs.mdx @@ -974,7 +974,7 @@ aws events put-targets \ ### Auto Scaling (High-Availability Setup) - The auto-scaling configuration below only scales basd on CPU usage. We are working on expanding this page with additional details on how to also auto-scale based on the number of concurrent connections per API pod. As seen in the [Deployment Architecture](/maintenance-ops/self-hosting/deployment-architecture) documentation, it is recommended to have 1 API pod per 100 concurrent client connections. + The auto-scaling configuration below only scales based on CPU usage. We are working on expanding this page with additional details on how to also auto-scale based on the number of concurrent connections per API pod. As seen in the [Deployment Architecture](/maintenance-ops/self-hosting/deployment-architecture) documentation, it is recommended to have 1 API pod per 100 concurrent client connections. ```bash