@spree/docs 0.1.129 → 0.1.130

package/dist/developer/deployment/docker.md

@@ -1,34 +1,41 @@
 ---
 title: Docker
-description: Run the official Spree Docker image or build your own.
+description: Build a production Docker image of your Spree project, or run the official prebuilt image.
 ---
 
-## Official Docker Image
+## Building Your Project's Image
+
+Every [create-spree-app](../create-spree-app/quickstart.md) 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](quickstart.md#single-node-vs-distributed)).
 
-Spree publishes multi-arch Docker images (`linux/amd64` and `linux/arm64`) to the GitHub Container Registry on every release.
+If you haven't ejected yet, do that first:
 
 ```bash
-docker pull ghcr.io/spree/spree:latest
+spree eject
 ```
 
-### Available Tags
+This generates the app source — including its production `Dockerfile` — in `backend/`. Make your customizations, then build:
 
-| Tag | Description |
-|-----|-------------|
-| `latest` | Latest stable release |
-| `5.4.0` | Specific version |
-| `5.4` | Latest patch for a minor version |
+```bash
+spree build --production                                  # → <project>-spree:latest
+spree build --production --tag registry.example.com/my-store:v42
+```
 
-Browse all tags on the [GitHub Packages page](https://github.com/spree/spree/pkgs/container/spree).
+Or with plain Docker, from the project root:
+
+```bash
+docker build . -f backend/Dockerfile -t my-store
+```
 
-### Running the Image
+Both produce the same image — and it's exactly what Render and Railway build from your repository. Migrations run automatically on boot.
 
-The image runs a Puma web server on port 3000. You also need a worker container for background jobs (Sidekiq):
+## Running the Image
+
+One app container plus Postgres is a complete deployment:
 
 ```yaml docker-compose.yml
 services:
   postgres:
-    image: postgres:17-alpine
+    image: postgres:18-alpine
     environment:
       POSTGRES_HOST_AUTH_METHOD: trust
     volumes:
@@ -39,26 +46,13 @@ services:
       timeout: 5s
       retries: 5
 
-  redis:
-    image: redis:7-alpine
-    volumes:
-      - redis_data:/data
-    healthcheck:
-      test: redis-cli ping
-      interval: 5s
-      timeout: 5s
-      retries: 5
-
   web:
-    image: ghcr.io/spree/spree:latest
+    image: my-store   # or ghcr.io/spree/spree:latest for the stock image
     depends_on:
       postgres:
         condition: service_healthy
-      redis:
-        condition: service_healthy
     environment:
       DATABASE_URL: postgres://postgres@postgres:5432/spree_production
-      REDIS_URL: redis://redis:6379/0
       SECRET_KEY_BASE: change-me-to-a-real-secret
       RAILS_FORCE_SSL: "false"
       RAILS_ASSUME_SSL: "false"
@@ -74,21 +68,8 @@ services:
       retries: 10
       start_period: 30s
 
-  worker:
-    image: ghcr.io/spree/spree:latest
-    depends_on:
-      web:
-        condition: service_healthy
-    environment:
-      DATABASE_URL: postgres://postgres@postgres:5432/spree_production
-      REDIS_URL: redis://redis:6379/0
-      SECRET_KEY_BASE: change-me-to-a-real-secret
-      RAILS_HOST: localhost:3000
-    command: bundle exec sidekiq
-
 volumes:
   postgres_data:
-  redis_data:
 ```
 
 Start everything:
@@ -97,37 +78,48 @@ Start everything:
 docker compose up -d
 ```
 
-The database is automatically created and migrated on first boot. The app is available at [http://localhost:3000](http://localhost:3000).
+The database is created and migrated on first boot. The app is available at [http://localhost:3000](http://localhost:3000).
 
-> **TIP:** Use [create-spree-app](../create-spree-app/quickstart.md) for a fully scaffolded Docker setup with `.env` files, health checks, and optional Next.js storefront — all configured automatically.
+### Scaling out the worker
+
+Background jobs run inside the web container by default. When job load deserves its own process, split it out — same image, no rebuild: set `SOLID_QUEUE_IN_PUMA: "false"` on `web` and add a worker service:
+
+```yaml
+  worker:
+    image: my-store
+    depends_on:
+      postgres:
+        condition: service_healthy
+    environment:
+      DATABASE_URL: postgres://postgres@postgres:5432/spree_production
+      SECRET_KEY_BASE: change-me-to-a-real-secret
+      RAILS_HOST: localhost:3000
+    command: bin/jobs
+```
 
 ### Required Environment Variables
 
 | Variable | Description | Example |
 | --- | --- | --- |
 | `DATABASE_URL` | PostgreSQL connection URL | `postgres://user:pass@host:5432/spree` |
-| `REDIS_URL` | Redis URL for jobs, caching, and Action Cable | `redis://redis:6379/0` |
 | `SECRET_KEY_BASE` | Secret key for session encryption | Generate with `bin/rails secret` |
-| `RAILS_HOST` | Public host used in generated URLs — image/attachment URLs in API responses, email links. Without it they fall back to the store's URL setting (`localhost` on a fresh install) | `store.example.com` |
+| `RAILS_HOST` | Public host used in generated URLs — image/attachment URLs in API responses, email links | `store.example.com` |
+| `SOLID_QUEUE_IN_PUMA` | Run background jobs inside the web container (default `true`); set `false` when running a dedicated worker | `true` |
 
 See [Environment Variables](environment_variables.md) for the full list.
 
-## Building Your Own Image
+## Official Docker Image
 
-If you have your own Rails application with Spree installed, build a Docker image from your app's Dockerfile:
+To run Spree without any customizations, pull the prebuilt multi-arch image (`linux/amd64` and `linux/arm64`) published to the GitHub Container Registry on every release:
 
 ```bash
-docker build -t my-spree .
+docker pull ghcr.io/spree/spree:latest
 ```
 
-Then use your custom image in place of `ghcr.io/spree/spree`:
-
-```bash
-docker run -p 3000:3000 \
-  -e DATABASE_URL=postgres://user:pass@host:5432/spree \
-  -e REDIS_URL=redis://localhost:6379/0 \
-  -e SECRET_KEY_BASE=your-secret \
-  my-spree
-```
+| Tag | Description |
+|-----|-------------|
+| `latest` | Latest stable release |
+| `5.4.0` | Specific version |
+| `5.4` | Latest patch for a minor version |
 
-> **TIP:** When creating a new Rails app with Spree via `rails new -m`, a production-ready Dockerfile is generated automatically by Rails.
+Browse all tags on the [GitHub Packages page](https://github.com/spree/spree/pkgs/container/spree). The image drops into the compose file above in place of your custom tag.

package/dist/developer/deployment/emails.md

@@ -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 <orders@your-domain.com>
-```
+    ```env
+    # .env.local (storefront)
+    SPREE_WEBHOOK_SECRET=your_webhook_endpoint_secret_key
+    RESEND_API_KEY=re_your_resend_api_key
+    EMAIL_FROM=Your Store <orders@your-domain.com>
+    ```
 
 3. **The storefront handles everything else** — signature verification, event routing, email rendering, and delivery are built in. See the [Next.js storefront email docs](../storefront/nextjs/customization.md#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 <orders@your-domain.com>
 | `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](../core-concepts/webhooks.md) 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`.

package/dist/developer/deployment/environment_variables.md

@@ -1,20 +1,20 @@
 ---
 title: Environment Variables
-description: Reference for Spree deployment environment variables — database, Redis, 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` |
-| `REDIS_URL` | Redis URL for background jobs (Sidekiq) and Action Cable | `redis://localhost:6379/0` |
-| `REDIS_CACHE_URL` | Redis URL for caching (optional — falls back to `REDIS_URL`) | `redis://localhost:6380/0` |
-| `SECRET_KEY_BASE` | Secret key for session encryption. Generate with `bin/rails secret` | `2fad5c0b79d25e4765d3018d8c740f8c3a665f0e5c...` |
+| `DATABASE_URL` | Database connection URL — see [Database Configuration](database.md) | `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
 
@@ -25,15 +25,35 @@ These variables are required to run Spree in production.
 | 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](render.md), 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](cdn.md). 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](background_jobs.md) 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](../storefront/nextjs/customization.md#transactional-emails).
+> **TIP:** 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](emails.md).
 
-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](emails.md) for the full guide.
 
 | Variable | Default | Description |
 | --- | --- | --- |
@@ -45,24 +65,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](assets.md) for the full guide.
 
 ### Amazon S3
 
@@ -116,11 +128,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

package/dist/developer/deployment/quickstart.md

@@ -0,0 +1,79 @@
+---
+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](docker.md), 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](database.md) 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](background_jobs.md#swapping-to-sidekiq) on Redis or Valkey. See [Background Jobs](background_jobs.md) 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](../create-spree-app/quickstart.md) 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](../storefront/nextjs/deployment.md) for the full guide.
+
+## Provider Guides
+
+Step-by-step guides for specific platforms:
+
+
+  - [AWS](aws.md) — A single EC2 instance + RDS to start, or ECS Fargate with CI/CD and auto-scaling — same image, either way.
+
+  - [Render](render.md) — One-click Blueprint: a Docker web service and managed PostgreSQL, built straight from your repository.
+
+  - **Railway (coming soon)** — A one-click Railway template is on the way.
+
+
+For any other platform, the [Docker guide](docker.md) covers building and running your project's image — which is all any container host needs.

package/dist/developer/deployment/render.md

@@ -1,75 +1,57 @@
 ---
 title: Render
-description: Deploy Spree to Render with one click.
+description: Deploy your Spree project to Render — one Docker service, one Postgres.
 ---
 
-## One-Click Deploy
+## Overview
 
-The fastest way to get Spree running on Render:
+Every [create-spree-app](../create-spree-app/quickstart.md) project ships a ready Render Blueprint (`render.yaml` at the project root). It deploys the whole app in the [single-node topology](quickstart.md#single-node-vs-distributed): **one Docker service built straight from your repository** plus a managed PostgreSQL — nothing else:
 
-[![Deploy to Render](https://render.com/images/deploy-to-render-button.svg)](https://render.com/deploy?repo=https://github.com/spree/spree-starter)
+- **Web** — one container running the Spree API and background jobs
+- **PostgreSQL** — the only backing service
 
-This creates all required services automatically:
+Migrations run automatically on boot. Render builds the same image `spree build --production` builds locally.
 
-- **Web** — Rails app serving the API and admin panel
-- **Worker** — Sidekiq for background jobs
-- **PostgreSQL** — database
-- **Redis** — caching, jobs, Action Cable
+> **TIP:** Just evaluating Spree? Skip self-hosting entirely and use a hosted sandbox at [spreecommerce.org](https://spreecommerce.org).
 
-The database is seeded on first deploy. Your store is ready in a few minutes.
+## Deploying
 
-## Prerequisites
+1. Push your create-spree-app project to GitHub
+2. In the Render dashboard, click **New** → **Blueprint** and select your repository
+3. Render reads `render.yaml` and creates the services. Review and click **Deploy Blueprint**.
 
-- [Render account](https://render.com) with a credit card on file
-- [GitHub account](https://github.com)
-
-## Custom Deployment
-
-If you need to customize the backend (add gems, models, etc.), start from the [Spree Starter](https://github.com/spree/spree-starter) template:
-
-1. Go to [spree/spree-starter](https://github.com/spree/spree-starter) and click **Use this template** > **Create a new repository**
-
-2. Clone your new repository and make your changes
-
-3. In the Render dashboard, click **New** > **Blueprint** and select your repository
-
-4. Render reads the `render.yaml` from your repo and creates all services. Review and click **Deploy Blueprint**.
-
-The included [`render.yaml`](https://github.com/spree/spree-starter/blob/main/render.yaml) handles:
-- Build: `bundle install`, asset precompilation, `db:prepare`, `db:seed`
-- Web: Puma with health check on `/up`
-- Worker: Sidekiq with shared `SECRET_KEY_BASE`
-- PostgreSQL 18 and Redis
+The database is seeded on first boot. Your store is ready in a few minutes — including any customizations, since the image builds from your repository.
 
 ## After Deployment
 
-### Admin Dashboard
-
-Access your admin panel at:
+### Admin
 
 ```
-https://<your-app-name>.onrender.com/admin
+https://<your-app-name>.onrender.com/admin        # admin panel
+https://<your-app-name>.onrender.com/jobs         # background jobs dashboard
 ```
 
-Default credentials are created during `db:seed`. Change them immediately after first login.
+Default credentials are created during seeding. Change them immediately after first login.
+
+The `/jobs` dashboard uses HTTP Basic auth: user `jobs`, with a password the Blueprint generates — read it in the Render dashboard under the web service's **Environment** tab (`MISSION_CONTROL_PASSWORD`).
 
 ### Environment Variables
 
-Render sets `DATABASE_URL`, `REDIS_URL`, and `SECRET_KEY_BASE` automatically from the blueprint. For additional configuration (SMTP, file storage, Sentry, etc.), see [Environment Variables](environment_variables.md).
+Render sets `DATABASE_URL` and `SECRET_KEY_BASE` automatically from the Blueprint. For additional configuration (SMTP, file storage, Sentry, etc.), see [Environment Variables](environment_variables.md).
 
 Generated URLs (images and attachments in API responses, email links) automatically use Render's `RENDER_EXTERNAL_HOSTNAME` (`<your-app-name>.onrender.com`). When you attach a custom domain, set [`RAILS_HOST`](environment_variables.md#urls-and-hosts) to it — it takes precedence.
 
-## Production Sizing
+## Scaling Out
 
-The free/starter plans work for trying Spree. For production workloads, we recommend:
+The Blueprint's commented **worker** block switches to [split mode](quickstart.md#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:
 
 | Service | Plan | Resources | Auto-scaling |
 |---|---|---|---|
 | **Web** | Pro | 4 GB RAM, 2 CPU | 1–2 instances |
-| **Worker** | Standard | 2 GB RAM, 1 CPU | — |
+| **Worker** (optional split) | Standard | 2 GB RAM, 1 CPU | — |
 | **PostgreSQL** | Pro 4 GB | 4 GB RAM, 1 CPU | — |
-| **Redis** (jobs) | Standard | 1 GB RAM | — |
-| **Redis** (cache) | Standard | 1 GB RAM | — |
 
 To enable auto-scaling, add this to the web service in your `render.yaml`:
 
@@ -84,6 +66,8 @@ To enable auto-scaling, add this to the web service in your `render.yaml`:
     targetCPUPercent: 80
 ```
 
+High-traffic installs can additionally swap [caching](caching.md) to a managed Redis/Valkey — the default needs no extra service.
+
 ## Next Steps
 
 Render provides ephemeral storage — uploaded files (product images, etc.) won't persist across deploys. Set up cloud storage:
@@ -95,3 +79,5 @@ Before going to production:
 - [Set environment variables](environment_variables.md) (SMTP, SSL, etc.)
 - [Configure CDN](cdn.md)
 - [Configure caching](caching.md)
+
+Deploying a storefront? The Next.js storefront ships separately — typically to Vercel. See [Storefront Deployment](../storefront/nextjs/deployment.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spree/docs",
-  "version": "0.1.129",
+  "version": "0.1.130",
   "description": "Spree Commerce developer documentation for AI agents and local reference",
   "type": "module",
   "license": "CC-BY-4.0",

package/dist/developer/deployment/heroku.md

@@ -1,51 +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)