Skip to content

armgit / spree

Public Imported from GitHub
0

Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.

Update Render and AWS recommended production sizing

Damian Legawiec76be9832bfd4
diff --git a/docs/developer/deployment/aws.mdx b/docs/developer/deployment/aws.mdx
index ab3e5c08fd..c9b82b658c 100644
--- a/docs/developer/deployment/aws.mdx
+++ b/docs/developer/deployment/aws.mdx
@@ -3,24 +3,24 @@ title: Amazon Web Services (AWS)
description: Learn how to deploy your Spree application on Amazon Web Services (AWS).
---
-Amazon Web Services offers reliable, scalable, and inexpensive cloud computing services. AWS is also one of the most popular choices for hosting a Spree application.
+Amazon Web Services offers reliable, scalable, and inexpensive cloud computing services. AWS is also one of the most popular choices for hosting a Spree application.
We recommend using AWS ECS Fargate to host your Spree application via [Docker image](/developer/deployment/docker).
-## Required AWS services
+## Required AWS Services
To fully run your Spree application on AWS, you will need the following services:
| Service | Description |
|---------|-------------|
-| [AWS ECS Fargate](https://aws.amazon.com/fargate/) | Amazon Elastic Container Service (ECS) is a fully managed container orchestration service that allows you to run and scale containerized applications without managing the underlying infrastructure. |
-| [AWS RDS](https://aws.amazon.com/rds/) | Amazon Relational Database Service makes it easy to set up, operate, and scale a relational database in the cloud. Spree works great with multiple databases: [Amazon Aurora both MySQL and PostgreSQL variants](https://aws.amazon.com/rds/aurora/), [RDS PostgreSQL](https://aws.amazon.com/rds/postgresql/), [RDS MySQL](https://aws.amazon.com/rds/mysql/) and [RDS MariaDB](https://aws.amazon.com/rds/mariadb/) |
-| [AWS ElastiCache](https://aws.amazon.com/elasticache/redis/?nc=sn&loc=2&dn=1) | Valkey or Redis instance for background jobs (Sidekiq), [caching](/developer/deployment/caching), and Action Cable. |
-| [AWS S3](https://aws.amazon.com/s3/) | Object storage service to store and read your uploaded files such as Product images, etc. [More information](/developer/deployment/assets#aws-s3). |
-| [AWS CloudFront](https://aws.amazon.com/cloudfront/) | Fast content delivery network CDN to speed up your asset images/stylesheets/javascript delivery. This will greatly enhance your application responsiveness. |
-| [AWS Route 53](https://aws.amazon.com/route53/) | Domain name system (DNS) service to manage your domain names and DNS records. |
-| [AWS Certificate Manager](https://aws.amazon.com/certificate-manager/) | AWS Certificate Manager is a service that provides you with SSL/TLS certificates that you can use to secure your application. Spree in production works only with HTTPS. |
-| [AWS ECR](https://aws.amazon.com/ecr/) | Amazon Elastic Container Registry is a fully managed Docker container registry that makes it easy to store, manage, and deploy Docker container images. |
+| [AWS ECS Fargate](https://aws.amazon.com/fargate/) | Fully managed container orchestration — run and scale containers without managing infrastructure. |
+| [AWS RDS](https://aws.amazon.com/rds/) | Managed relational database. Spree works with [Aurora PostgreSQL](https://aws.amazon.com/rds/aurora/), [Aurora MySQL](https://aws.amazon.com/rds/aurora/), [RDS PostgreSQL](https://aws.amazon.com/rds/postgresql/), [RDS MySQL](https://aws.amazon.com/rds/mysql/), and [RDS MariaDB](https://aws.amazon.com/rds/mariadb/). |
+| [AWS ElastiCache](https://aws.amazon.com/elasticache/) | Valkey or Redis for background jobs (Sidekiq), [caching](/developer/deployment/caching), and Action Cable. We recommend separate instances for jobs and cache. |
+| [AWS S3](https://aws.amazon.com/s3/) | Object storage for uploaded files (product images, etc.). [More information](/developer/deployment/assets#aws-s3). |
+| [AWS CloudFront](https://aws.amazon.com/cloudfront/) | CDN for asset delivery (images, stylesheets, JavaScript). |
+| [AWS Route 53](https://aws.amazon.com/route53/) | DNS service for domain name management. |
+| [AWS Certificate Manager](https://aws.amazon.com/certificate-manager/) | Free SSL/TLS certificates. Spree requires HTTPS in production. |
+| [AWS ECR](https://aws.amazon.com/ecr/) | Docker container registry for storing your application images. |
## Docker Image
@@ -203,23 +203,47 @@ This action requires secrets to be set in your GitHub repository. You can find t
| `SUBNET_ID_2` | Second subnet ID |
| `SECURITY_GROUP_ID` | Security group ID |
-## Environment variables
+## Environment Variables
-For a full list of Docker environment variables, please refer to the [Environment variables](/developer/deployment/environment_variables) page.
+Store secrets in [AWS Secrets Manager](https://aws.amazon.com/secrets-manager/) and reference them in your task definitions. Non-sensitive configuration goes in the `environment` array directly.
-## ECS tasks
+For a full list of available variables, see [Environment Variables](/developer/deployment/environment_variables).
-You will need to create two ECS task definitions: one for the web service and one for the worker service.
+### Secrets Manager
-### Web service
+Create the following secrets in AWS Secrets Manager:
+
+| Secret Name | Variable | Description |
+|---|---|---|
+| `spree/database-url` | `DATABASE_URL` | PostgreSQL connection URL |
+| `spree/redis-url` | `REDIS_URL` | Redis URL for background jobs and Action Cable |
+| `spree/redis-cache-url` | `REDIS_CACHE_URL` | Redis URL for caching (separate instance recommended) |
+| `spree/secret-key-base` | `SECRET_KEY_BASE` | Generate with `bin/rails secret` |
+
+Optional secrets for email delivery, file storage, and error tracking:
+
+| Secret Name | Variable | Description |
+|---|---|---|
+| `spree/smtp-password` | `SMTP_PASSWORD` | SMTP auth password |
+| `spree/sentry-dsn` | `SENTRY_DSN` | Sentry DSN for error tracking |
+
+<Tip>
+ S3 file storage credentials are not needed as environment variables when your ECS task role has the appropriate S3 permissions. Use IAM roles instead of access keys when possible.
+</Tip>
+
+## ECS Task Definitions
+
+You will need two ECS task definitions: one for the web service and one for the worker service. Save these as `.aws/web-task-definition.json` and `.aws/worker-task-definition.json` in your repository.
+
+### Web Service
```json
{
"family": "spree-web",
"networkMode": "awsvpc",
"requiresCompatibilities": ["FARGATE"],
- "cpu": "512",
- "memory": "1024",
+ "cpu": "1024",
+ "memory": "4096",
"executionRoleArn": "arn:aws:iam::${AWS_ACCOUNT_ID}:role/ecsTaskExecutionRole",
"taskRoleArn": "arn:aws:iam::${AWS_ACCOUNT_ID}:role/ecsTaskRole",
"containerDefinitions": [
@@ -241,6 +265,22 @@ You will need to create two ECS task definitions: one for the web service and on
{
"name": "PORT",
"value": "3000"
+ },
+ {
+ "name": "RAILS_MAX_THREADS",
+ "value": "3"
+ },
+ {
+ "name": "WEB_CONCURRENCY",
+ "value": "auto"
+ },
+ {
+ "name": "RAILS_LOG_LEVEL",
+ "value": "info"
+ },
+ {
+ "name": "AWS_BUCKET",
+ "value": "your-spree-bucket"
}
],
"secrets": [
@@ -252,6 +292,10 @@ You will need to create two ECS task definitions: one for the web service and on
"name": "REDIS_URL",
"valueFrom": "arn:aws:secretsmanager:${AWS_REGION}:${AWS_ACCOUNT_ID}:secret:spree/redis-url"
},
+ {
+ "name": "REDIS_CACHE_URL",
+ "valueFrom": "arn:aws:secretsmanager:${AWS_REGION}:${AWS_ACCOUNT_ID}:secret:spree/redis-cache-url"
+ },
{
"name": "SECRET_KEY_BASE",
"valueFrom": "arn:aws:secretsmanager:${AWS_REGION}:${AWS_ACCOUNT_ID}:secret:spree/secret-key-base"
@@ -277,15 +321,15 @@ You will need to create two ECS task definitions: one for the web service and on
}
```
-### Worker service
+### Worker Service
```json
{
"family": "spree-worker",
"networkMode": "awsvpc",
"requiresCompatibilities": ["FARGATE"],
- "cpu": "256",
- "memory": "512",
+ "cpu": "512",
+ "memory": "2048",
"executionRoleArn": "arn:aws:iam::${AWS_ACCOUNT_ID}:role/ecsTaskExecutionRole",
"taskRoleArn": "arn:aws:iam::${AWS_ACCOUNT_ID}:role/ecsTaskRole",
"containerDefinitions": [
@@ -298,6 +342,10 @@ You will need to create two ECS task definitions: one for the web service and on
{
"name": "RAILS_ENV",
"value": "production"
+ },
+ {
+ "name": "RAILS_LOG_LEVEL",
+ "value": "info"
}
],
"secrets": [
@@ -333,3 +381,88 @@ You will need to create two ECS task definitions: one for the web service and on
]
}
```
+
+## Production Sizing
+
+The task definitions above are sized for production. Here is a summary and scaling guidance:
+
+| Service | Fargate CPU | Fargate Memory | Instances |
+|---|---|---|---|
+| **Web** | 1 vCPU | 4 GB | 2+ (use ECS Service Auto Scaling) |
+| **Worker** | 0.5 vCPU | 2 GB | 1+ |
+| **RDS (PostgreSQL)** | — | `db.r6g.large` (2 vCPU, 16 GB) | 1 primary + read replica |
+| **ElastiCache (jobs)** | — | `cache.r6g.large` (13 GB) | 1 |
+| **ElastiCache (cache)** | — | `cache.r6g.large` (13 GB) | 1 |
+
+### Auto Scaling
+
+Use [ECS Service Auto Scaling](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/service-auto-scaling.html) to scale the web service based on CPU or memory utilization:
+
+```bash
+# Register a scalable target (min 2, max 6 tasks)
+aws application-autoscaling register-scalable-target \
+ --service-namespace ecs \
+ --resource-id service/spree-cluster/spree-web \
+ --scalable-dimension ecs:service:DesiredCount \
+ --min-capacity 2 \
+ --max-capacity 6
+
+# Scale based on average CPU utilization (target 70%)
+aws application-autoscaling put-scaling-policy \
+ --service-namespace ecs \
+ --resource-id service/spree-cluster/spree-web \
+ --scalable-dimension ecs:service:DesiredCount \
+ --policy-name spree-web-cpu-scaling \
+ --policy-type TargetTrackingScaling \
+ --target-tracking-scaling-policy-configuration '{
+ "TargetValue": 70.0,
+ "PredefinedMetricSpecification": {
+ "PredefinedMetricType": "ECSServiceAverageCPUUtilization"
+ },
+ "ScaleInCooldown": 300,
+ "ScaleOutCooldown": 60
+ }'
+```
+
+## After Deployment
+
+### Admin Dashboard
+
+Access your admin panel at:
+
+```
+https://<your-domain>/admin
+```
+
+Default credentials are created during `db:seed`. Change them immediately after first login.
+
+### Database Migrations
+
+The GitHub Actions workflow above runs migrations automatically on deploy. To run migrations manually:
+
+```bash
+aws ecs run-task \
+ --cluster spree-cluster \
+ --task-definition spree-web \
+ --overrides '{
+ "containerOverrides": [{
+ "name": "web",
+ "command": ["bundle", "exec", "rails", "db:migrate"]
+ }]
+ }' \
+ --launch-type FARGATE \
+ --network-configuration '{
+ "awsvpcConfiguration": {
+ "subnets": ["subnet-xxx", "subnet-yyy"],
+ "securityGroups": ["sg-xxx"],
+ "assignPublicIp": "DISABLED"
+ }
+ }'
+```
+
+## Next Steps
+
+- [Asset Storage](/developer/deployment/assets) — configure S3 for product images and uploads
+- [Configure CDN](/developer/deployment/cdn) — set up CloudFront for asset delivery
+- [Configure caching](/developer/deployment/caching) — use ElastiCache for application caching
+- [Set environment variables](/developer/deployment/environment_variables) — SMTP, Sentry, SSL, etc.
diff --git a/docs/developer/deployment/render.mdx b/docs/developer/deployment/render.mdx
index d1fd13b57c..6b70b9b83f 100644
--- a/docs/developer/deployment/render.mdx
+++ b/docs/developer/deployment/render.mdx
@@ -63,7 +63,7 @@ The free/starter plans work for trying Spree. For production workloads, we recom
| Service | Plan | Resources | Auto-scaling |
|---|---|---|---|
-| **Web** | Pro | 4 GB RAM, 2 CPU | 2–3 instances |
+| **Web** | Pro | 4 GB RAM, 2 CPU | 1–2 instances |
| **Worker** | Standard | 2 GB RAM, 1 CPU | — |
| **PostgreSQL** | Pro 4 GB | 4 GB RAM, 1 CPU | — |
| **Redis** (jobs) | Standard | 1 GB RAM | — |