@spree/docs 0.1.129 → 0.1.131

package/dist/developer/deployment/aws_ecs.md

@@ -0,0 +1,460 @@
+---
+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](aws.md) gets you to production with a fraction of the moving parts — on the same [Docker image](docker.md), 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](database.md) |
+| [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](assets.md#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](cdn.md) in front of assets and images |
+| [ElastiCache](https://aws.amazon.com/elasticache/) | Valkey/Redis for [high-traffic caching](caching.md) — 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](docker.md) 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](environment_variables.md).
+
+### 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.
+
+## ECS Task Definitions
+
+One task definition runs the whole app — the web server also runs background jobs in-process ([combined mode](quickstart.md#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](quickstart.md#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](caching.md).
+
+### 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](assets.md) — configure S3 for product images and uploads
+- [Configure CDN](cdn.md) — set up CloudFront for asset delivery
+- [Configure caching](caching.md) — works out of the box; add ElastiCache for high-traffic installs
+- [Set environment variables](environment_variables.md) — SMTP, Sentry, SSL, etc.
+- [Deploy the storefront](../storefront/nextjs/deployment.md) — the Next.js storefront ships separately, typically to Vercel

package/dist/developer/deployment/background_jobs.md

@@ -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](quickstart.md#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`](environment_variables.md).
+
+## 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](caching.md); 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.

package/dist/developer/deployment/caching.md

@@ -1,19 +1,27 @@
 ---
 title: Caching
-description: Configure Redis-backed caching for your Spree application to speed up database queries and template renders, with tips for cache keys and invalidation.
+description: Spree's cache lives in Postgres by default (Solid Cache) — nothing extra to run, with a one-line Redis/Valkey swap for high-traffic installs.
 ---
 
-Caching improves performance by storing the results of expensive database queries and template renders in memory.
+Caching improves performance by storing the results of expensive computations. Spree's headless API caches sparingly — small memoized values (geo data, settings, taxonomy lookups) and the API's rate-limit counters — so the default store needs no dedicated service.
 
-## Setting up Redis as Cache Store
+## Solid Cache — the default
 
-Spree comes pre-configured to use Redis for caching in production. Just set the `REDIS_URL` environment variable — no gem installation or code changes needed.
+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.
 
-```bash
-REDIS_URL=redis://localhost:6379/0
+## Swapping to Redis or Valkey
+
+For high-traffic installs that want an in-memory cache, the swap is one line in `config/environments/production.rb` plus the gem:
+
+```ruby
+# Gemfile
+gem "redis"
+
+# config/environments/production.rb
+config.cache_store = :redis_cache_store, { url: ENV["REDIS_URL"] }
 ```
 
-When `REDIS_URL` is set, Spree automatically uses it for caching. When not set, it falls back to an in-memory cache store.
+Works identically with Redis or Valkey (the Linux Foundation fork most hosting platforms now provision).
 
 ## Testing Locally
 

package/dist/developer/deployment/database.md

@@ -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](background_jobs.md) threads, since jobs run inside the web container by default:
 
 **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
@@ -56,7 +56,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
@@ -73,7 +73,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: