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 deplpyment guides

Damian Legawiecdea3bf7dbe37
diff --git a/docs/developer/deployment/aws.mdx b/docs/developer/deployment/aws.mdx
index 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 box
diff --git a/docs/developer/deployment/aws_ecs.mdx b/docs/developer/deployment/aws_ecs.mdx
new file mode 100644
index 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 Vercel
diff --git a/docs/developer/deployment/background_jobs.mdx b/docs/developer/deployment/background_jobs.mdx
new file mode 100644
index 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.mdx
index 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 Valkey
diff --git a/docs/developer/deployment/database.mdx b/docs/developer/deployment/database.mdx
index 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: &default
adapter: postgresql
encoding: 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: &default
adapter: mysql2
encoding: 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`:
```yaml
default: &default
adapter: sqlite3
- pool: <%= ENV.fetch("RAILS_MAX_THREADS") { 5 } %>
+ pool: <%= Integer(ENV.fetch("RAILS_MAX_THREADS", 3)) + Integer(ENV.fetch("JOB_THREADS", 3)) + 3 %>
timeout: 5000
development:
diff --git a/docs/developer/deployment/docker.mdx b/docs/developer/deployment/docker.mdx
index 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.mdx
index 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
+#### Setup
1. **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 Rese
2. **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 Frameworks
If 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 emails
In 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:3001
Use 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.mdx
index 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, Amazon
Links 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 Development
diff --git a/docs/developer/deployment/heroku.mdx b/docs/developer/deployment/heroku.mdx
deleted file mode 100644
index 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.mdx
new file mode 100644
index 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.mdx
index 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.json
index 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"
]
},
{