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.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
Update deplpyment guides
Damian Legawiecdea3bf7dbe37
diff --git a/docs/developer/deployment/aws.mdx b/docs/developer/deployment/aws.mdxindex 8eaf5d212d..8e595ab5ec 100644--- a/docs/developer/deployment/aws.mdx+++ b/docs/developer/deployment/aws.mdx@@ -1,456 +1,109 @@----title: Amazon Web Services (AWS)-description: Learn how to deploy your Spree application on Amazon Web Services (AWS).+title: AWS — EC2 + RDS+sidebarTitle: EC2 + RDS+description: The simplest production Spree on AWS — one EC2 instance and a managed database.----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.+The simplest way to run Spree on AWS is the [single-node topology](/developer/deployment/quickstart#single-node-vs-distributed): **one EC2 instance running the Docker image, one RDS database**. No clusters, no load balancers, no task definitions — a complete production store for roughly the cost of a t3.small and a small RDS instance.-We recommend using AWS ECS Fargate to host your Spree application via [Docker image](/developer/deployment/docker).+Need auto-scaling, zero-downtime deploys, or CI/CD-driven infrastructure? That's the [ECS Fargate guide](/developer/deployment/aws_ecs) — it runs the same Docker image, so you can start here and graduate later without rework.-## Required AWS Services+## What You'll Create-To fully run your Spree application on AWS, you will need the following services:--| Service | Description |-|---------|-------------|-| [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/) | Optional — background jobs and caching use PostgreSQL by default. Add Valkey or Redis only for [high-traffic caching](/developer/deployment/caching). |-| [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--Build [your project's image](/developer/deployment/docker) with `spree build --production`, or use the stock `ghcr.io/spree/spree` image for deployments without customizations.--To build and deploy a custom image to AWS ECR via GitHub Actions:--```yaml-name: Deploy to AWS Fargate--on:- push:- branches: [ main ]- pull_request:- branches: [ main ]--env:- AWS_REGION: us-east-1- ECR_REPOSITORY: spree-starter- ECS_SERVICE_WEB: spree-web- ECS_SERVICE_WORKER: spree-worker- ECS_CLUSTER: spree-cluster--jobs:- build:- name: Build and Push to ECR- runs-on: ubuntu-latest-- outputs:- image: ${{ steps.build-image.outputs.image }}- image-tag: ${{ steps.build-image.outputs.image-tag }}-- steps:- - name: Checkout code- uses: actions/checkout@v4-- - name: Configure AWS credentials- uses: aws-actions/configure-aws-credentials@v4- with:- aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}- aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}- aws-region: ${{ env.AWS_REGION }}-- - name: Login to Amazon ECR- id: login-ecr- uses: aws-actions/amazon-ecr-login@v2-- - name: Build, tag, and push image to Amazon ECR- id: build-image- env:- ECR_REGISTRY: ${{ steps.login-ecr.outputs.registry }}- IMAGE_TAG: ${{ github.sha }}- run: |- # Build a docker container and push it to ECR- docker build -t $ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG .- docker push $ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG- echo "image=$ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG" >> $GITHUB_OUTPUT- echo "image-tag=$IMAGE_TAG" >> $GITHUB_OUTPUT-- deploy-web:- name: Deploy Web Service- runs-on: ubuntu-latest- needs: build- if: github.ref == 'refs/heads/main'-- steps:- - name: Checkout code- uses: actions/checkout@v4-- - name: Configure AWS credentials- uses: aws-actions/configure-aws-credentials@v4- with:- aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}- aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}- aws-region: ${{ env.AWS_REGION }}-- - name: Fill in the new image ID in the Amazon ECS task definition- id: task-def-web- uses: aws-actions/amazon-ecs-render-task-definition@v1- env:- ECR_REGISTRY: ${{ needs.build.outputs.image }}- IMAGE_TAG: ${{ needs.build.outputs.image-tag }}- AWS_ACCOUNT_ID: ${{ secrets.AWS_ACCOUNT_ID }}- with:- task-definition: .aws/web-task-definition.json- container-name: web- image: ${{ needs.build.outputs.image }}-- - name: Deploy Amazon ECS task definition for web- uses: aws-actions/amazon-ecs-deploy-task-definition@v1- with:- task-definition: ${{ steps.task-def-web.outputs.task-definition }}- service: ${{ env.ECS_SERVICE_WEB }}- cluster: ${{ env.ECS_CLUSTER }}- wait-for-service-stability: true-- deploy-worker:- name: Deploy Worker Service- runs-on: ubuntu-latest- needs: build- if: github.ref == 'refs/heads/main'-- steps:- - name: Checkout code- uses: actions/checkout@v4-- - name: Configure AWS credentials- uses: aws-actions/configure-aws-credentials@v4- with:- aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}- aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}- aws-region: ${{ env.AWS_REGION }}-- - name: Fill in the new image ID in the Amazon ECS task definition- id: task-def-worker- uses: aws-actions/amazon-ecs-render-task-definition@v1- env:- ECR_REGISTRY: ${{ needs.build.outputs.image }}- IMAGE_TAG: ${{ needs.build.outputs.image-tag }}- AWS_ACCOUNT_ID: ${{ secrets.AWS_ACCOUNT_ID }}- with:- task-definition: .aws/worker-task-definition.json- container-name: worker- image: ${{ needs.build.outputs.image }}-- - name: Deploy Amazon ECS task definition for worker- uses: aws-actions/amazon-ecs-deploy-task-definition@v1- with:- task-definition: ${{ steps.task-def-worker.outputs.task-definition }}- service: ${{ env.ECS_SERVICE_WORKER }}- cluster: ${{ env.ECS_CLUSTER }}- wait-for-service-stability: true-- migrate:- name: Run Database Migrations- runs-on: ubuntu-latest- needs: [build, deploy-web]- if: github.ref == 'refs/heads/main'-- steps:- - name: Checkout code- uses: actions/checkout@v4-- - name: Configure AWS credentials- uses: aws-actions/configure-aws-credentials@v4- with:- aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}- aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}- aws-region: ${{ env.AWS_REGION }}-- - name: Run database migrations- run: |- aws ecs run-task \- --cluster ${{ env.ECS_CLUSTER }} \- --task-definition spree-web \- --overrides '{- "containerOverrides": [{- "name": "web",- "command": ["bundle", "exec", "rails", "db:migrate"]- }]- }' \- --launch-type FARGATE \- --network-configuration '{- "awsvpcConfiguration": {- "subnets": ["'${{ secrets.SUBNET_ID_1 }}'", "'${{ secrets.SUBNET_ID_2 }}'"],- "securityGroups": ["'${{ secrets.SECURITY_GROUP_ID }}'"],- "assignPublicIp": "ENABLED"- }- }'-```--This action requires secrets to be set in your GitHub repository. You can find the full list of secrets in the [AWS ECS Deploy Task Definition](https://github.com/aws-actions/amazon-ecs-deploy-task-definition) GitHub Actions repository.--| Secret | Description |-|--------|-------------|-| `AWS_ACCESS_KEY_ID` | AWS access key ID |-| `AWS_SECRET_ACCESS_KEY` | AWS secret access key |-| `AWS_ACCOUNT_ID` | AWS account ID |-| `SUBNET_ID_1` | First subnet ID |-| `SUBNET_ID_2` | Second subnet ID |-| `SECURITY_GROUP_ID` | Security group ID |--## Environment Variables--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.--For a full list of available variables, see [Environment Variables](/developer/deployment/environment_variables).--### Secrets Manager--Create the following secrets in AWS Secrets Manager:--| Secret Name | Variable | Description |+| Resource | Purpose | Starting size ||---|---|---|-| `spree/database-url` | `DATABASE_URL` | PostgreSQL connection URL |-| `spree/secret-key-base` | `SECRET_KEY_BASE` | Generate with `bin/rails secret` |+| **EC2 instance** | Runs the Spree container (web + background jobs) | `t3.small` (2 GB) to start, `t3.medium` for comfort |+| **RDS PostgreSQL** | The only backing service — data, jobs, cache | `db.t4g.small` |+| **DNS record** | Your store's web address, e.g. `store.example.com`, pointing at the instance's Elastic IP (a free static IP — a plain EC2 IP changes on restart and would break the record) | — |+| **S3 bucket** (recommended) | Uploaded files (product images) — they shouldn't live on the instance disk. See [Asset Storage](/developer/deployment/assets) | — |-Optional secrets for email delivery, file storage, and error tracking:+## 1. Create the Database (RDS)-| 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>+Create an **RDS PostgreSQL** instance in the AWS console:-## ECS Task Definitions+- Same VPC as your EC2 instance will use+- **Public access: no** — instead, allow inbound port `5432` from the EC2 instance's security group+- Note the endpoint, username, and password — they become your `DATABASE_URL`-One task definition runs the whole app — the web server also runs background jobs in-process. Save it as `.aws/web-task-definition.json`. The worker task definition is an optional scale-out step — skip it (and the `deploy-worker` job in the workflow above) until job load deserves its own service.+Spree also runs on RDS MySQL/MariaDB and both Aurora flavors — see [Database Configuration](/developer/deployment/database). RDS takes automated daily backups by default, so the database needs no extra care.-### Web Service--```json-{- "family": "spree-web",- "networkMode": "awsvpc",- "requiresCompatibilities": ["FARGATE"],- "cpu": "1024",- "memory": "4096",- "executionRoleArn": "arn:aws:iam::${AWS_ACCOUNT_ID}:role/ecsTaskExecutionRole",- "taskRoleArn": "arn:aws:iam::${AWS_ACCOUNT_ID}:role/ecsTaskRole",- "containerDefinitions": [- {- "name": "web",- "image": "${ECR_REGISTRY}/${ECR_REPOSITORY}:${IMAGE_TAG}",- "portMappings": [- {- "containerPort": 3000,- "protocol": "tcp"- }- ],- "essential": true,- "environment": [- {- "name": "RAILS_ENV",- "value": "production"- },- {- "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": [- {- "name": "DATABASE_URL",- "valueFrom": "arn:aws:secretsmanager:${AWS_REGION}:${AWS_ACCOUNT_ID}:secret:spree/database-url"- },- {- "name": "SECRET_KEY_BASE",- "valueFrom": "arn:aws:secretsmanager:${AWS_REGION}:${AWS_ACCOUNT_ID}:secret:spree/secret-key-base"- }- ],- "logConfiguration": {- "logDriver": "awslogs",- "options": {- "awslogs-group": "/ecs/spree-web",- "awslogs-region": "${AWS_REGION}",- "awslogs-stream-prefix": "ecs"- }- },- "healthCheck": {- "command": ["CMD-SHELL", "curl -f http://localhost:3000/up || exit 1"],- "interval": 30,- "timeout": 5,- "retries": 3,- "startPeriod": 60- }- }- ]-}-```+## 2. Launch the Instance-### Worker Service (optional scale-out)+Launch an EC2 instance (Ubuntu 24.04 or Amazon Linux 2023) and open ports `80` and `443` in its security group. Give it a stable web address: associate an Elastic IP (so the instance's IP survives restarts) and create a DNS record for your domain — e.g. an `A` record for `store.example.com` — pointing at it. HTTPS depends on this: Caddy can only obtain a certificate once the domain resolves to the instance.-Splits background jobs into a dedicated service — same image, no rebuild. When you deploy it, set `SOLID_QUEUE_IN_PUMA=false` in the web task's `environment` so the web container stops running jobs. Save as `.aws/worker-task-definition.json`:+Then install Docker:-```json-{- "family": "spree-worker",- "networkMode": "awsvpc",- "requiresCompatibilities": ["FARGATE"],- "cpu": "512",- "memory": "2048",- "executionRoleArn": "arn:aws:iam::${AWS_ACCOUNT_ID}:role/ecsTaskExecutionRole",- "taskRoleArn": "arn:aws:iam::${AWS_ACCOUNT_ID}:role/ecsTaskRole",- "containerDefinitions": [- {- "name": "worker",- "image": "${ECR_REGISTRY}/${ECR_REPOSITORY}:${IMAGE_TAG}",- "command": ["bin/jobs"],- "essential": true,- "environment": [- {- "name": "RAILS_ENV",- "value": "production"- },- {- "name": "RAILS_LOG_LEVEL",- "value": "info"- }- ],- "secrets": [- {- "name": "DATABASE_URL",- "valueFrom": "arn:aws:secretsmanager:${AWS_REGION}:${AWS_ACCOUNT_ID}:secret:spree/database-url"- },- {- "name": "SECRET_KEY_BASE",- "valueFrom": "arn:aws:secretsmanager:${AWS_REGION}:${AWS_ACCOUNT_ID}:secret:spree/secret-key-base"- }- ],- "logConfiguration": {- "logDriver": "awslogs",- "options": {- "awslogs-group": "/ecs/spree-worker",- "awslogs-region": "${AWS_REGION}",- "awslogs-stream-prefix": "ecs"- }- },- "healthCheck": {- "command": ["CMD-SHELL", "pgrep -f solid_queue || exit 1"],- "interval": 30,- "timeout": 5,- "retries": 3,- "startPeriod": 60- }- }- ]-}+```bash+curl -fsSL https://get.docker.com | sh```-## 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** (optional split) | 0.5 vCPU | 2 GB | 1+ |-| **RDS (PostgreSQL)** | — | `db.r6g.large` (2 vCPU, 16 GB) | 1 |--The database also stores background jobs and cache — the sizing above accounts for it. Scaling the web service to multiple instances is safe with in-process jobs: instances coordinate through the database. Add ElastiCache (Valkey or Redis) only for [high-traffic caching](/developer/deployment/caching).--### 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:+## 3. Run Spree++Build [your project's image](/developer/deployment/docker) and push it to a registry the instance can pull from (ECR or any other) — or use the stock `ghcr.io/spree/spree:latest` image to start. Then create a `docker-compose.yml` on the instance:++```yaml docker-compose.yml+services:+ web:+ image: your-registry/my-store:latest # or ghcr.io/spree/spree:latest+ restart: unless-stopped+ environment:+ DATABASE_URL: postgres://spree:[email protected]:5432/spree_production+ SECRET_KEY_BASE: generate-with-openssl-rand-hex-64+ RAILS_HOST: store.example.com+ # Uploads to S3 (recommended) — see /developer/deployment/assets+ # AWS_REGION: eu-west-1+ # AWS_BUCKET: my-store-uploads+ # AWS_ACCESS_KEY_ID: ...+ # AWS_SECRET_ACCESS_KEY: ...+ # Email delivery — see /developer/deployment/emails+ # SMTP_HOST: smtp.resend.com+ # SMTP_USERNAME: resend+ # SMTP_PASSWORD: ...+ # SMTP_FROM_ADDRESS: [email protected]++ # Caddy terminates HTTPS with an automatic Let's Encrypt certificate+ caddy:+ image: caddy:2+ restart: unless-stopped+ ports:+ - "80:80"+ - "443:443"+ command: caddy reverse-proxy --from store.example.com --to web:3000+ volumes:+ - caddy_data:/data++volumes:+ caddy_data:+``````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- }'+docker compose up -d```-## After Deployment+The database is migrated automatically on boot. Once DNS resolves, your store is live at `https://store.example.com` — admin at `/admin`, background jobs running inside the web container ([combined mode](/developer/deployment/quickstart#web-and-worker)).-### Admin+## Updating-Access your admin panel at:+Deploying a new version is a pull and a restart:-```-https://<your-domain>/admin+```bash+docker compose pull && docker compose up -d```-Default credentials are created during `db:seed`. Change them immediately after first login.+This restarts the container with a few seconds of downtime — the point at which that matters is a good signal to consider [ECS Fargate](/developer/deployment/aws_ecs) and its rolling deploys.-### Database Migrations+## Scaling on One Box-The GitHub Actions workflow above runs migrations automatically on deploy. To run migrations manually:+Before reaching for a cluster:-```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"- }- }'-```+- **Bigger instance** — a `t3.medium` or `t3.large` carries substantial traffic; resizing is a stop/start+- **Split the worker** — add a second service to the compose file with `command: bin/jobs`, and set `SOLID_QUEUE_IN_PUMA: "false"` on `web` ([split mode](/developer/deployment/quickstart#web-and-worker))+- **Scale the database** — RDS resizes independently, and read replicas are a console click## 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) — works out of the box; add ElastiCache for high-traffic installs-- [Set environment variables](/developer/deployment/environment_variables) — SMTP, Sentry, SSL, etc.+- [Asset Storage](/developer/deployment/assets) — store uploads in S3+- [Set environment variables](/developer/deployment/environment_variables) — SMTP, Sentry, etc.+- [Configure CDN](/developer/deployment/cdn) — CloudFront in front of your assets+- [Deploy the storefront](/developer/storefront/nextjs/deployment) — the Next.js storefront ships separately, typically to Vercel+- [ECS Fargate](/developer/deployment/aws_ecs) — when you outgrow one boxdiff --git a/docs/developer/deployment/aws_ecs.mdx b/docs/developer/deployment/aws_ecs.mdxnew file mode 100644index 0000000000..312f9e4cd8--- /dev/null+++ b/docs/developer/deployment/aws_ecs.mdx@@ -0,0 +1,462 @@+---+title: AWS — ECS Fargate+sidebarTitle: ECS Fargate+description: Production-grade Spree on AWS — ECS Fargate, RDS, CI/CD, and auto-scaling.+---++This is the advanced AWS path: containers managed by ECS Fargate with auto-scaling, zero-downtime rolling deploys, CI/CD via GitHub Actions, and secrets in AWS Secrets Manager. If you're getting started or running a single store, the [EC2 + RDS guide](/developer/deployment/aws) gets you to production with a fraction of the moving parts — on the same [Docker image](/developer/deployment/docker), so you can graduate to ECS later without rework.++## Required AWS Services++The required set is smaller than an AWS architecture diagram suggests — four services run the store:++| Service | Purpose |+|---------|---------|+| [ECS Fargate](https://aws.amazon.com/fargate/) | Runs the web (and optional worker) containers — no servers to manage |+| [RDS](https://aws.amazon.com/rds/) | The database — data, background jobs, and cache all live here. PostgreSQL, MySQL/MariaDB, and both Aurora flavors work — see [Database Configuration](/developer/deployment/database) |+| [ECR](https://aws.amazon.com/ecr/) | Registry for your Docker image |+| [S3](https://aws.amazon.com/s3/) | Uploaded files (product images) — Fargate containers have no persistent disk. See [Asset Storage](/developer/deployment/assets#aws-s3) |++In front of the web service you'll put an **Application Load Balancer** with a free HTTPS certificate from [Certificate Manager](https://aws.amazon.com/certificate-manager/) — that's your public entry point.++Everything else is optional:++| Service | When |+|---------|------|+| [CloudFront](https://aws.amazon.com/cloudfront/) | [CDN](/developer/deployment/cdn) in front of assets and images |+| [ElastiCache](https://aws.amazon.com/elasticache/) | Valkey/Redis for [high-traffic caching](/developer/deployment/caching) — the default cache lives in the database |+| [Route 53](https://aws.amazon.com/route53/) | DNS — convenient on AWS, but any DNS provider works |++## Docker Image++Build [your project's image](/developer/deployment/docker) with `spree build --production`, or use the stock `ghcr.io/spree/spree` image for deployments without customizations.++To build and deploy a custom image to AWS ECR via GitHub Actions:++```yaml+name: Deploy to AWS Fargate++on:+ push:+ branches: [ main ]+ pull_request:+ branches: [ main ]++env:+ AWS_REGION: us-east-1+ ECR_REPOSITORY: spree-starter+ ECS_SERVICE_WEB: spree-web+ ECS_SERVICE_WORKER: spree-worker+ ECS_CLUSTER: spree-cluster++jobs:+ build:+ name: Build and Push to ECR+ runs-on: ubuntu-latest++ outputs:+ image: ${{ steps.build-image.outputs.image }}+ image-tag: ${{ steps.build-image.outputs.image-tag }}++ steps:+ - name: Checkout code+ uses: actions/checkout@v4++ - name: Configure AWS credentials+ uses: aws-actions/configure-aws-credentials@v4+ with:+ aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}+ aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}+ aws-region: ${{ env.AWS_REGION }}++ - name: Login to Amazon ECR+ id: login-ecr+ uses: aws-actions/amazon-ecr-login@v2++ - name: Build, tag, and push image to Amazon ECR+ id: build-image+ env:+ ECR_REGISTRY: ${{ steps.login-ecr.outputs.registry }}+ IMAGE_TAG: ${{ github.sha }}+ run: |+ # Build a docker container and push it to ECR+ docker build -t $ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG .+ docker push $ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG+ echo "image=$ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG" >> $GITHUB_OUTPUT+ echo "image-tag=$IMAGE_TAG" >> $GITHUB_OUTPUT++ deploy-web:+ name: Deploy Web Service+ runs-on: ubuntu-latest+ needs: build+ if: github.ref == 'refs/heads/main'++ steps:+ - name: Checkout code+ uses: actions/checkout@v4++ - name: Configure AWS credentials+ uses: aws-actions/configure-aws-credentials@v4+ with:+ aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}+ aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}+ aws-region: ${{ env.AWS_REGION }}++ - name: Fill in the new image ID in the Amazon ECS task definition+ id: task-def-web+ uses: aws-actions/amazon-ecs-render-task-definition@v1+ env:+ ECR_REGISTRY: ${{ needs.build.outputs.image }}+ IMAGE_TAG: ${{ needs.build.outputs.image-tag }}+ AWS_ACCOUNT_ID: ${{ secrets.AWS_ACCOUNT_ID }}+ with:+ task-definition: .aws/web-task-definition.json+ container-name: web+ image: ${{ needs.build.outputs.image }}++ - name: Deploy Amazon ECS task definition for web+ uses: aws-actions/amazon-ecs-deploy-task-definition@v1+ with:+ task-definition: ${{ steps.task-def-web.outputs.task-definition }}+ service: ${{ env.ECS_SERVICE_WEB }}+ cluster: ${{ env.ECS_CLUSTER }}+ wait-for-service-stability: true++ deploy-worker:+ name: Deploy Worker Service+ runs-on: ubuntu-latest+ needs: build+ if: github.ref == 'refs/heads/main'++ steps:+ - name: Checkout code+ uses: actions/checkout@v4++ - name: Configure AWS credentials+ uses: aws-actions/configure-aws-credentials@v4+ with:+ aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}+ aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}+ aws-region: ${{ env.AWS_REGION }}++ - name: Fill in the new image ID in the Amazon ECS task definition+ id: task-def-worker+ uses: aws-actions/amazon-ecs-render-task-definition@v1+ env:+ ECR_REGISTRY: ${{ needs.build.outputs.image }}+ IMAGE_TAG: ${{ needs.build.outputs.image-tag }}+ AWS_ACCOUNT_ID: ${{ secrets.AWS_ACCOUNT_ID }}+ with:+ task-definition: .aws/worker-task-definition.json+ container-name: worker+ image: ${{ needs.build.outputs.image }}++ - name: Deploy Amazon ECS task definition for worker+ uses: aws-actions/amazon-ecs-deploy-task-definition@v1+ with:+ task-definition: ${{ steps.task-def-worker.outputs.task-definition }}+ service: ${{ env.ECS_SERVICE_WORKER }}+ cluster: ${{ env.ECS_CLUSTER }}+ wait-for-service-stability: true++ migrate:+ name: Run Database Migrations+ runs-on: ubuntu-latest+ needs: [build, deploy-web]+ if: github.ref == 'refs/heads/main'++ steps:+ - name: Checkout code+ uses: actions/checkout@v4++ - name: Configure AWS credentials+ uses: aws-actions/configure-aws-credentials@v4+ with:+ aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}+ aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}+ aws-region: ${{ env.AWS_REGION }}++ - name: Run database migrations+ run: |+ aws ecs run-task \+ --cluster ${{ env.ECS_CLUSTER }} \+ --task-definition spree-web \+ --overrides '{+ "containerOverrides": [{+ "name": "web",+ "command": ["bundle", "exec", "rails", "db:migrate"]+ }]+ }' \+ --launch-type FARGATE \+ --network-configuration '{+ "awsvpcConfiguration": {+ "subnets": ["'${{ secrets.SUBNET_ID_1 }}'", "'${{ secrets.SUBNET_ID_2 }}'"],+ "securityGroups": ["'${{ secrets.SECURITY_GROUP_ID }}'"],+ "assignPublicIp": "ENABLED"+ }+ }'+```++This action requires secrets to be set in your GitHub repository. You can find the full list of secrets in the [AWS ECS Deploy Task Definition](https://github.com/aws-actions/amazon-ecs-deploy-task-definition) GitHub Actions repository.++| Secret | Description |+|--------|-------------|+| `AWS_ACCESS_KEY_ID` | AWS access key ID |+| `AWS_SECRET_ACCESS_KEY` | AWS secret access key |+| `AWS_ACCOUNT_ID` | AWS account ID |+| `SUBNET_ID_1` | First subnet ID |+| `SUBNET_ID_2` | Second subnet ID |+| `SECURITY_GROUP_ID` | Security group ID |++## Environment Variables++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.++For a full list of available variables, see [Environment Variables](/developer/deployment/environment_variables).++### Secrets Manager++Create the following secrets in AWS Secrets Manager:++| Secret Name | Variable | Description |+|---|---|---|+| `spree/database-url` | `DATABASE_URL` | PostgreSQL connection URL |+| `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++One task definition runs the whole app — the web server also runs background jobs in-process ([combined mode](/developer/deployment/quickstart#web-and-worker)). Save it as `.aws/web-task-definition.json`. The worker task definition is an optional scale-out step — skip it (and the `deploy-worker` job in the workflow above) until job load deserves its own service.++### Web Service++```json+{+ "family": "spree-web",+ "networkMode": "awsvpc",+ "requiresCompatibilities": ["FARGATE"],+ "cpu": "1024",+ "memory": "4096",+ "executionRoleArn": "arn:aws:iam::${AWS_ACCOUNT_ID}:role/ecsTaskExecutionRole",+ "taskRoleArn": "arn:aws:iam::${AWS_ACCOUNT_ID}:role/ecsTaskRole",+ "containerDefinitions": [+ {+ "name": "web",+ "image": "${ECR_REGISTRY}/${ECR_REPOSITORY}:${IMAGE_TAG}",+ "portMappings": [+ {+ "containerPort": 3000,+ "protocol": "tcp"+ }+ ],+ "essential": true,+ "environment": [+ {+ "name": "RAILS_ENV",+ "value": "production"+ },+ {+ "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": [+ {+ "name": "DATABASE_URL",+ "valueFrom": "arn:aws:secretsmanager:${AWS_REGION}:${AWS_ACCOUNT_ID}:secret:spree/database-url"+ },+ {+ "name": "SECRET_KEY_BASE",+ "valueFrom": "arn:aws:secretsmanager:${AWS_REGION}:${AWS_ACCOUNT_ID}:secret:spree/secret-key-base"+ }+ ],+ "logConfiguration": {+ "logDriver": "awslogs",+ "options": {+ "awslogs-group": "/ecs/spree-web",+ "awslogs-region": "${AWS_REGION}",+ "awslogs-stream-prefix": "ecs"+ }+ },+ "healthCheck": {+ "command": ["CMD-SHELL", "curl -f http://localhost:3000/up || exit 1"],+ "interval": 30,+ "timeout": 5,+ "retries": 3,+ "startPeriod": 60+ }+ }+ ]+}+```++### Worker Service (optional scale-out)++Switches to [split mode](/developer/deployment/quickstart#web-and-worker): background jobs move into a dedicated service — same image, no rebuild. When you deploy it, set `SOLID_QUEUE_IN_PUMA=false` in the web task's `environment` so the web container stops running jobs. Save as `.aws/worker-task-definition.json`:++```json+{+ "family": "spree-worker",+ "networkMode": "awsvpc",+ "requiresCompatibilities": ["FARGATE"],+ "cpu": "512",+ "memory": "2048",+ "executionRoleArn": "arn:aws:iam::${AWS_ACCOUNT_ID}:role/ecsTaskExecutionRole",+ "taskRoleArn": "arn:aws:iam::${AWS_ACCOUNT_ID}:role/ecsTaskRole",+ "containerDefinitions": [+ {+ "name": "worker",+ "image": "${ECR_REGISTRY}/${ECR_REPOSITORY}:${IMAGE_TAG}",+ "command": ["bin/jobs"],+ "essential": true,+ "environment": [+ {+ "name": "RAILS_ENV",+ "value": "production"+ },+ {+ "name": "RAILS_LOG_LEVEL",+ "value": "info"+ }+ ],+ "secrets": [+ {+ "name": "DATABASE_URL",+ "valueFrom": "arn:aws:secretsmanager:${AWS_REGION}:${AWS_ACCOUNT_ID}:secret:spree/database-url"+ },+ {+ "name": "SECRET_KEY_BASE",+ "valueFrom": "arn:aws:secretsmanager:${AWS_REGION}:${AWS_ACCOUNT_ID}:secret:spree/secret-key-base"+ }+ ],+ "logConfiguration": {+ "logDriver": "awslogs",+ "options": {+ "awslogs-group": "/ecs/spree-worker",+ "awslogs-region": "${AWS_REGION}",+ "awslogs-stream-prefix": "ecs"+ }+ },+ "healthCheck": {+ "command": ["CMD-SHELL", "pgrep -f solid_queue || exit 1"],+ "interval": 30,+ "timeout": 5,+ "retries": 3,+ "startPeriod": 60+ }+ }+ ]+}+```++## 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** (optional split) | 0.5 vCPU | 2 GB | 1+ |+| **RDS (PostgreSQL)** | — | `db.r6g.large` (2 vCPU, 16 GB) | 1 |++The database also stores background jobs and cache — the sizing above accounts for it. Scaling the web service to multiple instances is safe with in-process jobs: instances coordinate through the database. Add ElastiCache (Valkey or Redis) only for [high-traffic caching](/developer/deployment/caching).++### 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++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) — works out of the box; add ElastiCache for high-traffic installs+- [Set environment variables](/developer/deployment/environment_variables) — SMTP, Sentry, SSL, etc.+- [Deploy the storefront](/developer/storefront/nextjs/deployment) — the Next.js storefront ships separately, typically to Verceldiff --git a/docs/developer/deployment/background_jobs.mdx b/docs/developer/deployment/background_jobs.mdxnew file mode 100644index 0000000000..4cc7a6962e--- /dev/null+++ b/docs/developer/deployment/background_jobs.mdx@@ -0,0 +1,106 @@+---+title: Background Jobs+description: Spree's background jobs live in your database by default (Solid Queue) — nothing extra to run, with a Sidekiq/Redis swap for very high volume.+---++Everything that doesn't happen during a request runs as a background job: sending emails, processing images, delivering webhooks, importing and exporting catalogs, releasing expired stock reservations. Spree uses Active Job (Rails' standard job interface), so the queue backend is swappable — but the default needs nothing beyond your database.++## Solid Queue — the default++Production uses [Solid Queue](https://github.com/rails/solid_queue) — the built-in background job processor: jobs are stored in your database alongside everything else. There is nothing extra to provision, and by default the job supervisor runs **inside the web container** — one container is the whole application ([combined mode](/developer/deployment/quickstart#web-and-worker)).++When job volume grows, switch to split mode: run a dedicated worker from the same image with `bin/jobs`, and set `SOLID_QUEUE_IN_PUMA=false` on the web service. Multiple web instances and multiple workers are safe by default — they coordinate through the database.++| Variable | Default | Description |+|---|---|---|+| `SOLID_QUEUE_IN_PUMA` | `true` | Run jobs inside the web container; set `false` when a dedicated worker runs |+| `JOB_THREADS` | `3` | Worker thread count — raise it on a dedicated worker |+| `JOB_CONCURRENCY` | `1` | Worker process count — the scaling knob for dedicated workers |++## Job Dashboard++Every deployment ships [Mission Control](https://github.com/rails/mission_control-jobs) — a web UI for background jobs — at `/jobs`: inspect, retry, and discard jobs from the browser. It's guarded by HTTP Basic auth: set `MISSION_CONTROL_USER` and `MISSION_CONTROL_PASSWORD` in production (without them the dashboard stays locked).++## Recurring Jobs++Scheduled work — releasing expired stock reservations, pruning price history, queue housekeeping — is defined in `config/recurring.yml`, Solid Queue's built-in cron. Add your own:++```yaml config/recurring.yml+production:+ nightly_report:+ class: MyReportJob+ schedule: at 5am every day+```++## Queues++`config/queue.yml` lists queues in polling order: checkout-critical and operator-facing work first, bulk catalog processing second, housekeeping last. A trailing `"*"` catches any queue added later. Large CSV imports are additionally capped so they can't occupy the whole worker pool — see [`SPREE_IMPORT_JOB_CONCURRENCY`](/developer/deployment/environment_variables).++## Swapping to Sidekiq++For very high job volume, Spree works with [Sidekiq](https://sidekiq.org/) on Redis or Valkey — like any Active Job backend. This is a bigger step than the [cache swap](/developer/deployment/caching); here is the full setup.++Add the gems and switch the adapter:++```ruby+# Gemfile+gem "sidekiq"+gem "sidekiq-cron" # recurring jobs (replaces config/recurring.yml)+gem "sentry-sidekiq" # only if you use Sentry++# config/application.rb+config.active_job.queue_adapter = :sidekiq+```++Configure the queues with weights — Sidekiq's equivalent of Solid Queue's polling order (checkout-critical work first, bulk catalog processing second, housekeeping last):++```yaml config/sidekiq.yml+:concurrency: <%= Integer(ENV.fetch('SIDEKIQ_CONCURRENCY', '10')) %>+:queues:+ - [default, 5]+ - [spree_imports, 5]+ - [spree_payment_webhooks, 5]+ - [mailers, 5]+ - [spree_events, 3]+ - [spree_exports, 3]+ - [spree_images, 3]+ - [spree_products, 3]+ - [spree_reports, 3]+ - [spree_variants, 3]+ - [spree_taxons, 3]+ - [spree_stock_location_stock_items, 3]+ - [spree_coupon_codes, 3]+ - [spree_addresses, 3]+ - [spree_gift_cards, 3]+ - [spree_webhooks, 3]+ - [spree_api_keys, 3]+ - [spree_search, 3]+ - [active_storage_transform, 3]+ - [active_storage_analysis, 1]+ - [active_storage_purge, 1]+```++Move the `config/recurring.yml` schedules to sidekiq-cron (it auto-loads `config/schedule.yml`):++```yaml config/schedule.yml+expire_stock_reservations:+ cron: "* * * * *"+ class: Spree::StockReservations::ExpireJob+```++The `/jobs` dashboard is Solid Queue-specific — mount [Sidekiq's Web UI](https://github.com/sidekiq/sidekiq/wiki/Monitoring) instead:++```ruby+# config/routes.rb+require "sidekiq/web"++Sidekiq::Web.use Rack::Auth::Basic do |user, password|+ ActiveSupport::SecurityUtils.secure_compare(user, ENV["SIDEKIQ_USER"].to_s) &+ ActiveSupport::SecurityUtils.secure_compare(password, ENV["SIDEKIQ_PASSWORD"].to_s)+end+mount Sidekiq::Web => "/sidekiq"+```++Finally: point Sidekiq at your Redis/Valkey via `REDIS_URL`, run `bundle exec sidekiq` as a dedicated worker service (set `RAILS_MAX_THREADS` to at least `SIDEKIQ_CONCURRENCY` there so the database pool covers every worker thread), and remove the `SOLID_QUEUE_IN_PUMA` setting — with Sidekiq, web and worker are always separate processes.++Reach for this when a dedicated Solid Queue worker with raised `JOB_THREADS`/`JOB_CONCURRENCY` no longer keeps up — for most stores, that point never arrives.diff --git a/docs/developer/deployment/caching.mdx b/docs/developer/deployment/caching.mdxindex aca3427ad6..ef039ab3ec 100644--- a/docs/developer/deployment/caching.mdx+++ b/docs/developer/deployment/caching.mdx@@ -7,7 +7,7 @@ Caching improves performance by storing the results of expensive computations. S## Solid Cache — the default-Production uses [Solid Cache](https://github.com/rails/solid_cache): the cache lives in your PostgreSQL database alongside everything else. There is nothing to configure, provision, or monitor — it works out of the box in every deployment.+Production uses [Solid Cache](https://github.com/rails/solid_cache) — the built-in cache store: the cache lives in your PostgreSQL database alongside everything else. There is nothing to configure, provision, or monitor — it works out of the box in every deployment.## Swapping to Redis or Valkeydiff --git a/docs/developer/deployment/database.mdx b/docs/developer/deployment/database.mdxindex 2a666f2ee3..566bc50cf1 100644--- a/docs/developer/deployment/database.mdx+++ b/docs/developer/deployment/database.mdx@@ -30,7 +30,7 @@ DATABASE_URL=sqlite3:db/production.sqlite3### Using database.yml-You can also configure the database in `config/database.yml`:+You can also configure the database in `config/database.yml`. The connection pool is sized to cover web request threads plus [background job](/developer/deployment/background_jobs) threads, since jobs run inside the web container by default:<Tabs><Tab title="PostgreSQL">@@ -38,7 +38,7 @@ You can also configure the database in `config/database.yml`:default: &defaultadapter: postgresqlencoding: unicode- pool: <%= ENV.fetch("RAILS_MAX_THREADS") { 5 } %>+ pool: <%= Integer(ENV.fetch("RAILS_MAX_THREADS", 3)) + Integer(ENV.fetch("JOB_THREADS", 3)) + 3 %>development:<<: *default@@ -55,7 +55,7 @@ You can also configure the database in `config/database.yml`:default: &defaultadapter: mysql2encoding: utf8mb4- pool: <%= ENV.fetch("RAILS_MAX_THREADS") { 5 } %>+ pool: <%= Integer(ENV.fetch("RAILS_MAX_THREADS", 3)) + Integer(ENV.fetch("JOB_THREADS", 3)) + 3 %>development:<<: *default@@ -71,7 +71,7 @@ You can also configure the database in `config/database.yml`:```yamldefault: &defaultadapter: sqlite3- pool: <%= ENV.fetch("RAILS_MAX_THREADS") { 5 } %>+ pool: <%= Integer(ENV.fetch("RAILS_MAX_THREADS", 3)) + Integer(ENV.fetch("JOB_THREADS", 3)) + 3 %>timeout: 5000development:diff --git a/docs/developer/deployment/docker.mdx b/docs/developer/deployment/docker.mdxindex 1957a6b6e9..fb04955c2c 100644--- a/docs/developer/deployment/docker.mdx+++ b/docs/developer/deployment/docker.mdx@@ -5,7 +5,7 @@ description: Build a production Docker image of your Spree project, or run the o## Building Your Project's Image-Every [create-spree-app](/developer/create-spree-app/quickstart) project builds into a single production image: the web server and background jobs run in one container, and the only dependency is a PostgreSQL database.+Every [create-spree-app](/developer/create-spree-app/quickstart) project builds into a single production image: the web server and background jobs run in one container, and the only dependency is a PostgreSQL database (the [single-node topology](/developer/deployment/quickstart#single-node-vs-distributed)).If you haven't ejected yet, do that first:diff --git a/docs/developer/deployment/emails.mdx b/docs/developer/deployment/emails.mdxindex d305c7b95e..d6212d08b4 100644--- a/docs/developer/deployment/emails.mdx+++ b/docs/developer/deployment/emails.mdx@@ -8,19 +8,25 @@ Spree handles two categories of emails:| Category | Sent by | Examples ||----------|---------|----------|-| **Customer-facing** | Storefront (via webhooks) | Order confirmation, shipping notification, password reset |-| **System/admin** | Spree backend (Rails) | Staff invitation, report ready, export complete |+| **Customer-facing** | Spree by default; optionally your storefront (via webhooks) | Order confirmation, shipping notification, password reset |+| **System/admin** | Spree | Staff invitation, report ready, export complete |-## Customer-Facing Emails (Headless)+## Customer-Facing Emails-In headless builds, customer-facing emails are rendered and sent by the **storefront**, not the backend. The Spree backend publishes webhook events, and the storefront receives them, renders React email templates, and sends via [Resend](https://resend.com) (or any provider).+By default, **Spree sends all customer transactional emails itself** — the `spree_emails` gem ships installed in every deployment. This works for every client of the API: mobile apps, custom frontends, POS integrations — no storefront required. Delivery uses the same [SMTP configuration](#configuration) as system emails.++Customer emails can be turned off in the admin under **Settings → Emails** — do this when your storefront takes over sending them (below), otherwise customers receive both.++### Sending from the Storefront Instead++With the Next.js storefront, you can let the storefront own the customer email experience: the Spree backend publishes webhook events, and the storefront receives them, renders React email templates, and sends via [Resend](https://resend.com) (or any provider).```Spree Backend → Webhook POST → Storefront → render email → send via Resend(HMAC signed) (verified) (react-email)```-### Setup+#### Setup1. **Create a webhook endpoint** in Spree Admin → Settings → Developers → Webhooks:- **URL:** `https://your-storefront.com/api/webhooks/spree`@@ -28,16 +34,18 @@ Spree Backend → Webhook POST → Storefront → render email → send via Rese2. **Configure the storefront** with the webhook secret and email provider:-```env-# .env.local (storefront)-SPREE_WEBHOOK_SECRET=your_webhook_endpoint_secret_key-RESEND_API_KEY=re_your_resend_api_key-EMAIL_FROM=Your Store <[email protected]>-```+ ```env+ # .env.local (storefront)+ SPREE_WEBHOOK_SECRET=your_webhook_endpoint_secret_key+ RESEND_API_KEY=re_your_resend_api_key+ EMAIL_FROM=Your Store <[email protected]>+ ```3. **The storefront handles everything else** — signature verification, event routing, email rendering, and delivery are built in. See the [Next.js storefront email docs](/developer/storefront/nextjs/customization#transactional-emails) for template customization.-### Supported Events+4. **Turn off Spree's own customer emails** under **Settings → Emails** in the admin, so customers don't receive duplicates.++#### Supported Events| Event | Email ||-------|-------|@@ -47,7 +55,7 @@ EMAIL_FROM=Your Store <[email protected]>| `customer.password_reset_requested` | Password reset link || `newsletter_subscriber.subscription_requested` | Newsletter double opt-in confirmation link |-### Custom Frameworks+#### Custom FrameworksIf you're not using the Next.js storefront, you can build your own webhook handler with any framework. Use `@spree/sdk/webhooks` for signature verification:@@ -57,9 +65,9 @@ import { verifyWebhookSignature } from '@spree/sdk/webhooks'See [Webhooks documentation](/developer/core-concepts/webhooks) for the full payload format and verification details.-## System Emails (Rails)+## System Emails-System emails are internal notifications sent to **store staff**, not customers. They are sent by the Spree backend via Rails ActionMailer.+System emails are internal notifications sent to **store staff**, not customers. They are always sent by Spree itself and can't be taken over by a storefront.| Email | When ||-------|------|@@ -71,7 +79,7 @@ System emails are internal notifications sent to **store staff**, not customers.### Configuration-Set the following environment variables on the **Spree backend** to enable system email delivery:+Set the following environment variables on the **Spree backend** to enable email delivery — this configuration powers both customer transactional emails and system emails:| Variable | Default | Description || --- | --- | --- |@@ -128,7 +136,7 @@ When `SMTP_HOST` is not set, emails are printed to the Rails log instead of bein## Local Development-### Customer-facing emails (storefront)+### Storefront-sent emailsIn development, no email provider is needed. Emails are rendered to HTML files in `.next/emails/` with a clickable `file://` link in the console. To preview and design templates:@@ -145,6 +153,6 @@ cloudflared tunnel --url http://localhost:3001Use the tunnel URL as the webhook endpoint URL in Spree Admin.-### System emails (Rails)+### Spree-sent emails-System emails use [letter_opener](https://github.com/ryanb/letter_opener) in development — emails open automatically in your browser instead of being sent.+In development, all emails Spree sends (customer and system alike) are captured by [Mailpit](https://mailpit.axllent.org/) — nothing is delivered externally. Open **http://localhost:8025** to read them. To deliver through a real provider instead, set `SMTP_HOST` (and friends) in `.env`.diff --git a/docs/developer/deployment/environment_variables.mdx b/docs/developer/deployment/environment_variables.mdxindex 2d9468fcc5..c7b78d4b74 100644--- a/docs/developer/deployment/environment_variables.mdx+++ b/docs/developer/deployment/environment_variables.mdx@@ -1,23 +1,20 @@---title: Environment Variables-description: Reference for Spree deployment environment variables — database, background jobs, SMTP, web server, file storage, and application configuration settings.+description: Reference for Spree deployment environment variables — database, web server, background jobs, SMTP, file storage, and application settings.---Spree uses environment variables for all deployment configuration. No secrets or credentials are stored in the codebase.## Required-These variables are required to run Spree in production.+These two variables are all a production deployment strictly needs:| Variable | Description | Example || --- | --- | --- |-| `DATABASE_URL` | PostgreSQL connection URL | `postgres://user:pass@localhost:5432/spree` |-| `SOLID_QUEUE_IN_PUMA` | Run the Solid Queue job supervisor inside Puma (default `true` — one process serves web + jobs). Set `false` when a dedicated `bin/jobs` worker runs | `true` |-| `JOB_THREADS` | Background job worker thread count (see `config/queue.yml`; the DB pool sizes itself from this) | `3` |-| `JOB_CONCURRENCY` | Background job worker process count — the standard Rails knob for scaling a dedicated worker | `1` |-| `SPREE_IMPORT_JOB_CONCURRENCY` | Max worker threads one CSV import may occupy at once (default: 75% of `JOB_THREADS`; `0` disables the cap) | `2` |-| `MISSION_CONTROL_USER` / `MISSION_CONTROL_PASSWORD` | HTTP Basic auth for the `/jobs` dashboard. Required in production (the dashboard stays locked without them); dev defaults to the seed admin credentials | `jobs` |-| `SECRET_KEY_BASE` | Secret key for session encryption. Generate with `bin/rails secret` | `2fad5c0b79d25e4765d3018d8c740f8c3a665f0e5c...` |+| `DATABASE_URL` | Database connection URL — see [Database Configuration](/developer/deployment/database) | `postgres://user:pass@localhost:5432/spree` |+| `SECRET_KEY_BASE` | Secret used to encrypt sessions and cookies. Generate with `openssl rand -hex 64` | `2fad5c0b79d25e4765d3018d8c740f8c3a665f0e5c...` |++You'll almost always want to set [`RAILS_HOST`](#urls-and-hosts) too — without it, generated URLs point at `localhost`.## URLs and Hosts@@ -30,17 +27,37 @@ When neither `RAILS_HOST` nor `CDN_HOST` is configured, image and attachment URL| Variable | Default | Description || --- | --- | --- || `RAILS_HOST` | — | Public host, optionally with a port — e.g. `store.example.com` or `203.0.113.7:8080`. Host only, no protocol. On [Render](/developer/deployment/render), falls back to the platform-provided `RENDER_EXTERNAL_HOSTNAME`. |-| `CDN_HOST` | — | Optional host for serving static assets and images, e.g. a CDN distribution in front of your app. Host only, no protocol. Falls back to `RAILS_HOST`. |+| `CDN_HOST` | — | Optional host for serving static assets and images, e.g. a CDN distribution in front of your app — see [CDN](/developer/deployment/cdn). Host only, no protocol. Falls back to `RAILS_HOST`. |Generated URLs use `https` unless both `RAILS_FORCE_SSL` and `RAILS_ASSUME_SSL` are set to `false` (see [SSL](#ssl)).+## Web Server++| Variable | Default | Description |+| --- | --- | --- |+| `PORT` | `3000` | Port the web server listens on |+| `RAILS_MAX_THREADS` | `3` | Concurrent requests each web server process handles |+| `WEB_CONCURRENCY` | `1` | Number of web server processes per container. Set to `auto` for one per CPU core — each process needs roughly 1 GB of RAM |++## Background Jobs++Background jobs (emails, image processing, webhooks, imports) run inside the web container by default — no extra service needed. See [Background Jobs](/developer/deployment/background_jobs) for how this works and when to split out a dedicated worker.++| Variable | Default | Description |+| --- | --- | --- |+| `SOLID_QUEUE_IN_PUMA` | `true` | Run background jobs inside the web container. Set to `false` when you run a dedicated worker service (`bin/jobs`) |+| `JOB_THREADS` | `3` | How many background jobs run concurrently. Raise it on a dedicated worker; the database connection pool sizes itself from this |+| `JOB_CONCURRENCY` | `1` | Number of worker processes — the scaling knob for a dedicated worker |+| `SPREE_IMPORT_JOB_CONCURRENCY` | 75% of `JOB_THREADS` | How much of the job capacity a single CSV import may occupy, so imports can't starve other work. `0` removes the cap |+| `MISSION_CONTROL_USER` / `MISSION_CONTROL_PASSWORD` | — | Login for the `/jobs` dashboard (HTTP Basic auth). Required in production — the dashboard stays locked without them |+## Email (SMTP)<Tip>-This configuration is used for system emails (e.g. staff invitations, report ready, export complete). Customer facing emails are handled by the [storefront via webhooks](/developer/storefront/nextjs/customization#transactional-emails).+This configuration powers all emails Spree sends — customer transactional emails (order confirmation, shipping notification; on by default) and staff notifications. A storefront can optionally take over customer emails via webhooks — see [Emails](/developer/deployment/emails).</Tip>-Spree works with any SMTP provider (Resend, Postmark, Mailgun, SendGrid, Amazon SES, etc.). Set `SMTP_HOST` to enable email delivery — when not set, no delivery method is configured and production email delivery fails (development opens emails in the browser via `letter_opener`).+Spree works with any SMTP provider (Resend, Postmark, Mailgun, SendGrid, Amazon SES, etc.). Set `SMTP_HOST` to enable email delivery — when not set, production email delivery is disabled (in development, emails are captured by Mailpit at `http://localhost:8025` instead of being sent). See [Emails](/developer/deployment/emails) for the full guide.| Variable | Default | Description || --- | --- | --- |@@ -52,24 +69,16 @@ Spree works with any SMTP provider (Resend, Postmark, Mailgun, SendGrid, AmazonLinks in emails use the host configured via [`RAILS_HOST`](#urls-and-hosts).-## Web Server--| Variable | Default | Description |-| --- | --- | --- |-| `PORT` | `3000` | Web server port |-| `RAILS_MAX_THREADS` | `3` | Puma threads per worker |-| `WEB_CONCURRENCY` | `1` | Number of Puma workers. Set to `auto` for one per CPU core |-## Application| Variable | Default | Description || --- | --- | --- |-| `RAILS_ENV` | `production` | Rails environment |+| `RAILS_ENV` | `production` | Runtime environment — leave as `production` when deploying || `RAILS_LOG_LEVEL` | `info` | Log level (`debug`, `info`, `warn`, `error`) |## File Storage (S3 / Cloudflare R2)-By default, uploaded files (product images, assets) are stored on the local filesystem. Set the appropriate credentials to use cloud storage instead. Spree auto-detects the provider based on which credentials are present.+By default, uploaded files (product images, assets) are stored on the local filesystem. Set the appropriate credentials to use cloud storage instead — Spree auto-detects the provider based on which credentials are present. See [Asset Storage](/developer/deployment/assets) for the full guide.### Amazon S3@@ -125,11 +134,11 @@ bundle exec rake spree:search:reindex## SSL-By default, Spree assumes it runs behind an SSL-terminating reverse proxy. Set these to `false` if running without SSL (e.g., local development or behind a proxy that doesn't do SSL termination).+By default, Spree assumes it runs behind an SSL-terminating reverse proxy or load balancer. Set these to `false` if running without SSL (e.g., local development or behind a proxy that doesn't do SSL termination).| Variable | Default | Description || --- | --- | --- |-| `RAILS_ASSUME_SSL` | `true` | Assume requests arrive via SSL (sets `X-Forwarded-Proto`) |+| `RAILS_ASSUME_SSL` | `true` | Treat incoming requests as arriving over HTTPS (trust the proxy's forwarded headers) || `RAILS_FORCE_SSL` | `true` | Redirect HTTP to HTTPS and use secure cookies |## Local Developmentdiff --git a/docs/developer/deployment/heroku.mdx b/docs/developer/deployment/heroku.mdxdeleted file mode 100644index 4bc91d0c19..0000000000--- a/docs/developer/deployment/heroku.mdx+++ /dev/null@@ -1,52 +0,0 @@-----title: Heroku-section: deployment------# Heroku--## Overview--Heroku is a Platform as a Service that makes deploying and hosting Spree applications super easy.--You should just follow [Heroku Rails 6 guide](https://devcenter.heroku.com/articles/getting-started-with-rails6).--We recommend you start and stick to Heroku if you do not have DevOps-skilled team members. [Spree Starter](https://github.com/spree/spree_starter) is pre-configured to work with Heroku out of the box.--## Dynos--[Heroku Dynos](https://www.heroku.com/dynos) are lightweight, isolated environments that provide compute and run your application.--There are 2 types of dynos:--* **Web** - for running the web interface of yuour Store Storefront, API, Admin Panel-* **Worker** - for running background jobs via [Active Job](https://guides.rubyonrails.org/active_job_basics.html) such as email send out, report generation, etc--### Recommended sizing--| Dynos | Staging environment | Production environment |-| :--- | :--- | :--- |-| **web** | 1 x Standard-2x | 1 x Performance-M or Performance-L |-| **worker** | 1 x Standard-1x | 1 x Standard-1x |--## Add-Ons--[Heroku Add-Ons](https://elements.heroku.com/addons) are tools and services for developing, extending, and operating your app.--### Recommended Add-Ons and plans--| Plan | Staging environment | Production environment |-| :--- | :--- | :--- |-| Bucketeer | Hobbyist | Micro |-| Edge | Hobby | Micro |-| Heroku Postgres | Hobby Basic | Standard-0 |-| Sendgrid | Free | Bronze |-| Sentry | Free | Small |--## Other resources--* [https://devcenter.heroku.com/categories/reference](https://devcenter.heroku.com/categories/reference)-* [https://devcenter.heroku.com/articles/getting-started-with-rails6](https://devcenter.heroku.com/articles/getting-started-with-rails6)-* [https://devcenter.heroku.com/categories/monitoring-metrics](https://devcenter.heroku.com/categories/monitoring-metrics)-* [https://devcenter.heroku.com/articles/deploying-rails-applications-with-the-puma-web-server](https://devcenter.heroku.com/articles/deploying-rails-applications-with-the-puma-web-server)-diff --git a/docs/developer/deployment/quickstart.mdx b/docs/developer/deployment/quickstart.mdxnew file mode 100644index 0000000000..5f0b242e30--- /dev/null+++ b/docs/developer/deployment/quickstart.mdx@@ -0,0 +1,85 @@+---+title: Deployment Overview+sidebarTitle: Quickstart+description: Run Spree anywhere — any cloud, any database, from a single container to a globally distributed stack.+---++Spree is open source and self-hosted: you own the entire stack, end to end. There is no proprietary software in the runtime, no required third-party service, and no per-order fees. The same application runs on a $10 VPS, a managed cloud platform, a Kubernetes cluster, or a server in your own data center — and moving between them is a redeploy, not a migration.++## Run It Anywhere++Spree ships as a standard [Docker image](/developer/deployment/docker), which means it runs wherever containers run:++- **Public cloud** — AWS, Google Cloud, Azure, or any provider with container hosting+- **Platform-as-a-Service** — Render, Railway, Fly.io, and similar platforms; deploy from your repository with a Blueprint or a few clicks+- **VPS or bare metal** — a single machine with Docker installed is a complete production environment+- **Kubernetes** — the image is stateless and horizontally scalable, so it drops into any cluster+- **On-premise and intranet** — Spree has no phone-home dependencies, so it runs in private networks and air-gapped environments where SaaS commerce platforms simply can't++The minimum footprint is deliberately small: **one application container and one database**. Background jobs, caching, and real-time updates all run inside that container and store their data in the database — no Redis, no message broker, no extra services to provision or monitor. A store starts comfortably on 1 GB of RAM.++When you need more, every piece scales independently: add web instances behind a load balancer, split job processing into dedicated workers, add a read replica, swap the cache to Redis or Valkey, add Meilisearch for search. Each step is configuration, not rearchitecting.++## Any Database++Spree runs on all major relational databases, including the managed and serverless flavors cloud providers offer:++| Database | Managed options |+|----------|-----------------|+| **PostgreSQL** (recommended) | Amazon RDS, Aurora PostgreSQL, Google Cloud SQL, Azure Database, Neon, Supabase |+| **MySQL / MariaDB** | Amazon RDS, Aurora MySQL, Google Cloud SQL, Azure Database |+| **SQLite** | ideal for development, evaluation, and small stores |++See [Database Configuration](/developer/deployment/database) for details.++## Web and Worker++A Spree deployment has two kinds of work: serving requests (the **web** process) and everything that happens in the background — sending emails, processing images, delivering webhooks, importing catalogs (the **worker**).++You can run them in two modes:++- **Combined (the default)** — the web container also processes background jobs. One container is the whole application. This is how every fresh deployment starts, and it comfortably serves most stores.+- **Split** — when job volume grows, move background processing into a dedicated worker service. It's the same docker image with a different start command and one environment variable (`SOLID_QUEUE_IN_PUMA=false` on web) — no rebuild, no code changes. Recommended for high volume retailers, multi-tenant apps and marketplaces with a lot of vendors using our Shopify sync.++Jobs live in the database, so scaling to multiple web instances or multiple workers is safe by default — they coordinate through it. For demanding workloads, you can also [swap the job backend to Sidekiq](/developer/deployment/background_jobs#swapping-to-sidekiq) on Redis or Valkey. See [Background Jobs](/developer/deployment/background_jobs) for the full picture.++## Single-Node vs Distributed++Spree is API-first, which gives you a real choice of shape:++**Single-node** — one container serves the API, the admin dashboard, and background jobs, with one database behind it. Simplest to operate, cheapest to run, and what [create-spree-app](/developer/create-spree-app/quickstart) projects deploy by default. For headless setups with a mobile app or a custom frontend, this is often all the infrastructure you ever need.++**Distributed** — because the storefront and admin talk to Spree exclusively through its APIs, each surface can be deployed and scaled on its own:++- The **API** scales horizontally behind a load balancer+- The **admin dashboard** is a static React app that can be served from the API container or any static host+- **Workers** scale independently of web traffic+- The **storefront** (Next.js) deploys to Vercel or any Node.js host, rendering at the edge close to your customers++You don't choose upfront. Start single-node, and split surfaces out when traffic or team structure calls for it — the API boundary is already there. Storefront is fully optional, you can use our Next.js reference implementation, or build your own with any framework, build a mobile app, or even a native desktop app. Spree is the backend for all of them.++## Storefront Deployment++The Next.js storefront is a separate application with its own deployment lifecycle — typically on Vercel, but any Node.js host or Docker environment works. It connects to your Spree API with a publishable key and can be redeployed independently of the backend.++See [Storefront Deployment](/developer/storefront/nextjs/deployment) for the full guide.++## Provider Guides++Step-by-step guides for specific platforms:++<CardGroup cols={2}>+ <Card title="AWS" icon="aws" href="/developer/deployment/aws">+ A single EC2 instance + RDS to start, or ECS Fargate with CI/CD and auto-scaling — same image, either way.+ </Card>++ <Card title="Render" icon="server" href="/developer/deployment/render">+ One-click Blueprint: a Docker web service and managed PostgreSQL, built straight from your repository.+ </Card>++ <Card title="Railway (coming soon)">+ A one-click Railway template is on the way.+ </Card>+</CardGroup>++For any other platform, the [Docker guide](/developer/deployment/docker) covers building and running your project's image — which is all any container host needs.diff --git a/docs/developer/deployment/render.mdx b/docs/developer/deployment/render.mdxindex d22c55308b..31143a7f79 100644--- a/docs/developer/deployment/render.mdx+++ b/docs/developer/deployment/render.mdx@@ -5,7 +5,7 @@ description: Deploy your Spree project to Render — one Docker service, one Pos## Overview-Every [create-spree-app](/developer/create-spree-app/quickstart) project ships a ready Render Blueprint (`render.yaml` at the project root). It deploys the whole app as **one Docker service built straight from your repository** plus a managed PostgreSQL — nothing else:+Every [create-spree-app](/developer/create-spree-app/quickstart) project ships a ready Render Blueprint (`render.yaml` at the project root). It deploys the whole app in the [single-node topology](/developer/deployment/quickstart#single-node-vs-distributed): **one Docker service built straight from your repository** plus a managed PostgreSQL — nothing else:- **Web** — one container running the Spree API and background jobs- **PostgreSQL** — the only backing service@@ -45,7 +45,7 @@ Generated URLs (images and attachments in API responses, email links) automatica## Scaling Out-The Blueprint's commented **worker** block splits background jobs into a dedicated service — same image, no rebuild. Uncomment it and set `SOLID_QUEUE_IN_PUMA=false` on the web service so it stops running jobs.+The Blueprint's commented **worker** block switches to [split mode](/developer/deployment/quickstart#web-and-worker): background jobs move into a dedicated service — same image, no rebuild. Uncomment it and set `SOLID_QUEUE_IN_PUMA=false` on the web service so it stops running jobs.For production workloads, we recommend:@@ -81,3 +81,5 @@ Before going to production:- [Set environment variables](/developer/deployment/environment_variables) (SMTP, SSL, etc.)- [Configure CDN](/developer/deployment/cdn)- [Configure caching](/developer/deployment/caching)++Deploying a storefront? The Next.js storefront ships separately — typically to Vercel. See [Storefront Deployment](/developer/storefront/nextjs/deployment).diff --git a/docs/docs.json b/docs/docs.jsonindex 28517bffd9..00d8d4e028 100644--- a/docs/docs.json+++ b/docs/docs.json@@ -456,15 +456,23 @@"group": "Deployment","icon": "server","pages": [+ "developer/deployment/quickstart","developer/deployment/docker",- "developer/deployment/render","developer/deployment/environment_variables",- "developer/deployment/caching",+ {+ "group": "AWS",+ "pages": [+ "developer/deployment/aws",+ "developer/deployment/aws_ecs"+ ]+ },+ "developer/deployment/render","developer/deployment/assets",- "developer/deployment/cdn","developer/deployment/emails",- "developer/deployment/database",- "developer/deployment/aws"+ "developer/deployment/cdn",+ "developer/deployment/background_jobs",+ "developer/deployment/caching",+ "developer/deployment/database"]},{