Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
Single-node Docker deployment as the default: root-context builds
Damian Legawiec1bb80695ce46
diff --git a/CLAUDE.md b/CLAUDE.mdindex f27cbef8c1..8e4d7d9e04 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -86,7 +86,7 @@ Shipped plans:One-time bootstrap (Docker required, no host Ruby): `pnpm install && pnpm server:setup`. It clones spree-starter into `server/`, boots the edge stack (monorepo gems bind-mounted via a compose overlay), and prepares + seeds the DB. Idempotent — but re-running it is a **full reset** that wipes the DB and volumes.-Day-to-day from the repo root: `pnpm server:dev` (foreground — streams web + worker logs, Ctrl+C stops them; postgres/redis stay warm) / `server:stop` (full teardown) / `server:restart` / `server:logs` / `server:console` / `server:seed` / `server:load_sample_data`. CLI commands run from `server/`: `pnpm exec spree <cmd>` (`spree migrate`, `spree console`, `spree generate model …`). `spree dev` and `spree build` refuse to run in `server/` (SPREE_PATH guard) — use the `pnpm server:*` scripts instead.+Day-to-day from the repo root: `pnpm server:dev` (foreground — streams web logs; jobs run in-process via Solid Queue; Ctrl+C stops it, postgres stays warm) / `server:stop` (full teardown) / `server:restart` / `server:logs` / `server:console` / `server:seed` / `server:load_sample_data`. CLI commands run from `server/`: `pnpm exec spree <cmd>` (`spree migrate`, `spree console`, `spree generate model …`). `spree dev` and `spree build` refuse to run in `server/` (SPREE_PATH guard) — use the `pnpm server:*` scripts instead.| What changed | What to run ||---|---|diff --git a/README.md b/README.mdindex 4c9d9ba4bb..41dac7f9af 100755--- a/README.md+++ b/README.md@@ -88,12 +88,9 @@ Everything below ships in this repository under the BSD 3-Clause license.## Deployment-You can quickly deploy a Spree store with the button below, or follow our [deployment guide](https://spreecommerce.org/docs/developer/deployment/overview) for detailed instructions on deploying to various platforms.+Spree backend can be deployed everywhere, on cloud, on prem or VPS. We provide official Docker images and Dockerfiles so you can use AWS, Azure, GCP, Render, Railway, Fly.io, Heroku, or any other Docker-compatible host. The Next.js storefront can be deployed to Vercel, Netlify, or any Node.js host. [See the Deployment Documentation](https://spreecommerce.org/docs/developer/deployment) for more details.-[](https://render.com/deploy?repo=https://github.com/spree/spree-starter)--> **Note**-> This uses Render's free plan for quick evaluation. Free instances spin down after inactivity and may take 30-60s to wake up. For a zero-setup evaluation, [create a free sandbox](https://console.spree.sh) instead. For production, see [recommended sizing](https://spreecommerce.org/docs/developer/deployment/render#production-sizing).+If you want to quickly evaluate Spree, you can use the [free sandbox](https://console.spree.sh) — a hosted Spree store with the Admin Dashboard and storefront, nothing to install.## Screenshotsdiff --git a/docs/developer/contributing/developing-spree.mdx b/docs/developer/contributing/developing-spree.mdxindex b481f48234..e425f16b99 100644--- a/docs/developer/contributing/developing-spree.mdx+++ b/docs/developer/contributing/developing-spree.mdx@@ -36,7 +36,7 @@ pnpm install # workspace dependenciespnpm server:setup # ~5–10 min on first run; idempotent```-`pnpm server:setup` clones [spree-starter](https://github.com/spree/spree-starter) into `./server/`, wires it to load Spree gems from the monorepo via a Docker compose overlay, builds the dev image, starts the stack (Postgres + Redis + Meilisearch + Rails `web` + Sidekiq `worker`), and prepares the database. The full sequence lives in `scripts/server-setup.sh`.+`pnpm server:setup` clones [spree-starter](https://github.com/spree/spree-starter) into `./server/`, wires it to load Spree gems from the monorepo via a Docker compose overlay, builds the dev image, starts the stack (Postgres + Meilisearch + a single Rails `web` container — background jobs run in-process via Solid Queue), and prepares the database. The full sequence lives in `scripts/server-setup.sh`.When it's done, the backend is up at [http://localhost:3000](http://localhost:3000) and the admin is at [http://localhost:3000/admin](http://localhost:3000/admin). Sign in with the seed admin: **`[email protected]`** / **`spree123`** (override at seed time with `ADMIN_EMAIL` / `ADMIN_PASSWORD` env vars — see `spree/core/app/services/spree/seeds/admin_user.rb`).@@ -95,7 +95,7 @@ If you prefer the fastest possible inner loop and don't mind installing Ruby, Popnpm server:create # clones spree-starter, writes server/.env with SPREE_PATH=..cd serverbin/setup # installs Ruby (via mise), Postgres/Redis/Meilisearch (via brew bundle on macOS), gems, prepares the database-bin/dev # starts Rails + Sidekiq + CSS watchers via Foreman+bin/dev # starts Rails (jobs run in-process) + CSS watchers via Foreman```This path is faster per request but means more on your host. It also runs against your installed system services, not a sandboxed Docker stack.diff --git a/docs/developer/core-concepts/reports.mdx b/docs/developer/core-concepts/reports.mdxindex 80321f54b5..dfe3c0e34e 100644--- a/docs/developer/core-concepts/reports.mdx+++ b/docs/developer/core-concepts/reports.mdx@@ -187,7 +187,7 @@ Spree::Admin::RuntimeConfig.reports_line_items_limit = 100By default, report jobs run on the `:default` queue. To route them to a dedicated queue, configure your job processor:```ruby-# Sidekiq example+# ActiveJob exampleSpree.queues.reports = :reports```diff --git a/docs/developer/create-spree-app/quickstart.mdx b/docs/developer/create-spree-app/quickstart.mdxindex 1204a06d59..ce33351491 100644--- a/docs/developer/create-spree-app/quickstart.mdx+++ b/docs/developer/create-spree-app/quickstart.mdx@@ -16,12 +16,14 @@ The CLI walks you through an interactive setup:2. Optionally load **sample data** (products, categories, images)3. Optionally **start Docker services** immediately-Once complete, your store is running at [http://localhost:3000](http://localhost:3000).+Once complete, your store is running at [http://localhost:3000](http://localhost:3000) — setup pulls the latest Spree image, seeds the database, and configures API keys, then prints a summary with your admin credentials and keys. If you skipped starting services, the first `pnpm dev` completes setup automatically.++The **React Dashboard** (Developer Preview of the next-generation admin) is available with the `--react-dashboard` flag, or later via `spree add dashboard`.## Prerequisites- [Node.js](https://nodejs.org/) 20 or later-- [Docker](https://docs.docker.com/get-docker/) (for running the Spree backend, PostgreSQL, Redis, and Meilisearch)+- [Docker](https://docs.docker.com/get-docker/) (for running the Spree backend, PostgreSQL, and Meilisearch)## CLI Flags@@ -33,6 +35,7 @@ npx create-spree-app@latest my-store --no-storefront --no-sample-data --no-start| Flag | Description ||------|-------------|+| `--react-dashboard` | Include the React Dashboard (Developer Preview — also available later via `spree add dashboard`) || `--no-storefront` | Skip Next.js storefront setup || `--no-sample-data` | Skip loading sample products and categories || `--no-start` | Don't start Docker services after scaffolding |@@ -53,35 +56,39 @@ npx create-spree-app@latest my-store --no-storefront --no-sample-data --no-start```textmy-store/-├── docker-compose.yml # Spree backend (prebuilt image) + Postgres + Redis + Meilisearch+├── docker-compose.yml # Spree backend (prebuilt image) + Postgres + Meilisearch├── docker-compose.dev.yml # Alternative: build from local backend/-├── .env # SECRET_KEY_BASE, SPREE_PORT, SPREE_VERSION_TAG+├── render.yaml # Render Blueprint — one Docker service built from this repo+├── .env # SECRET_KEY_BASE, SPREE_PORT, SPREE_VERSION_TAG, SPREE_SAMPLE_DATA+├── .dockerignore # Keeps the production build context to sources├── .gitignore├── package.json # Convenience scripts├── README.md-├── backend/ # Full Rails app (from spree/spree-starter)+├── backend/ # Full Rails app — the Spree API (from spree/spree-starter)│ ├── Gemfile-│ ├── Dockerfile+│ ├── Dockerfile # Also builds the production image (API + dashboard)│ ├── config/│ ├── app/│ └── ...└── apps/- └── storefront/ # Next.js storefront (unless --no-storefront)- ├── .env.local # API URL + API key+ ├── storefront/ # Next.js storefront (unless --no-storefront)+ │ ├── .env.local # API URL + API key+ │ └── ...+ └── dashboard/ # React Dashboard (with --react-dashboard)+ ├── .env.local # Dev proxy target — no credentials└── ...```### What's in docker-compose.yml-- **Spree** — `web` (Rails) + `worker` (Sidekiq) running the `ghcr.io/spree/spree:latest` image on the configured port (default `3000`)+- **Spree** — one `web` container running the `ghcr.io/spree/spree:latest` image on the configured port (default `3000`); background jobs run in-process via Solid Queue (stored in Postgres — job dashboard at `/jobs`)- **PostgreSQL 18** — database with persistent volume-- **Redis 7** — caching, background jobs, and Action Cable- **Meilisearch** — search engine-- Health checks on postgres, redis, meilisearch, and web+- Health checks on postgres, meilisearch, and web-## Customizing the Backend+## Customizing the Spree API-The `backend/` directory contains a full Rails application with Spree installed (cloned from [spree-starter](https://github.com/spree/spree-starter)). By default, the project uses a prebuilt Docker image. To switch to building from your local backend:+The `backend/` directory is the Spree API — a full Rails application with Spree installed (cloned from [spree-starter](https://github.com/spree/spree-starter)) serving the Store and Admin APIs your storefront and dashboard talk to, plus background jobs and transactional emails. By default, the project runs it from a prebuilt Docker image. To switch to building from your local copy:```bashnpx spree eject@@ -103,10 +110,12 @@ The project includes [@spree/cli](/developer/cli/quickstart) for managing your S| Command | Description ||---------|-------------|-| `spree dev` | Run the backend in the foreground — streams logs, Ctrl+C stops it |+| `spree dev` | Run the app in the foreground — streams logs, Ctrl+C stops it. First run completes setup automatically; co-runs the React Dashboard dev server when `apps/dashboard` exists || `spree stop` | Stop backend services || `spree update` | Pull latest Spree image and restart (runs migrations automatically) || `spree eject` | Switch from prebuilt image to building from `backend/` |+| `spree add dashboard` | Add the React Dashboard to an existing project |+| `spree build --production` | Build the production image — the Spree API plus your dashboard, in one || `spree logs` | View backend logs || `spree logs worker` | View background jobs logs || `spree console` | Rails console |@@ -122,6 +131,8 @@ Open [http://localhost:3000/admin](http://localhost:3000/admin) and log in with:| **Email** | `[email protected]` || **Password** | `spree123` |+With `--react-dashboard`, the React Dashboard's dev server is the admin instead: `spree dev` starts it alongside the API at [http://localhost:5173](http://localhost:5173) — same credentials, live-reloading from `apps/dashboard/` (the classic admin remains at `/admin`). See the [React Dashboard docs](/developer/dashboard/overview).+### Store APIThe REST API is available at [http://localhost:3000/api/v3/store](http://localhost:3000/api/v3/store). See the [API Reference](/api-reference) for details.@@ -153,6 +164,15 @@ To pin a specific version, edit `SPREE_VERSION_TAG` in `.env`:SPREE_VERSION_TAG=5.4```+## Deployment++The project deploys as **one image**: `backend/Dockerfile` builds the Spree API together with your React Dashboard (when `apps/dashboard` exists), served same-origin at `/dashboard` — no CORS, no cookie configuration, no second service.++- **Render** — the `render.yaml` at the project root is a ready Blueprint: one Docker service built straight from your repo, migrations run on boot.+- **Anywhere else** — `spree build --production` builds the same image locally; push it to a registry and run it on any Docker host.++See the [Deployment Guide](/developer/deployment) and the [dashboard deployment docs](/developer/dashboard/deployment).+## Next Steps<CardGroup cols={2}>diff --git a/docs/developer/dashboard/deployment.mdx b/docs/developer/dashboard/deployment.mdxindex 719285eb09..f1e116685a 100644--- a/docs/developer/dashboard/deployment.mdx+++ b/docs/developer/dashboard/deployment.mdx@@ -24,16 +24,13 @@ The official image contains the *stock* dashboard. Once you've customized yoursspree build --production # optionally --tag registry/repo:tag```-The command detects `apps/dashboard/`, selects the Dockerfile's `custom` dashboard stage (`--build-arg DASHBOARD_SOURCE=custom`), and passes your app as a named build context — the Node toolchain lives only in that throw-away stage, and the final image is Rails plus your built `dist/` served at `/dashboard`. Without the CLI, the equivalent is:+The Dockerfile normalizes its own build context: built from the project root it detects the layout (`backend/` = the Rails app, `apps/dashboard/` = your dashboard) and builds *your* dashboard into the image — no flags, no named contexts. Without the CLI, the equivalent is:```bash-docker build backend/ -f backend/Dockerfile \- --build-arg DASHBOARD_SOURCE=custom \- --build-context dashboard-src=./apps/dashboard \- -t my-shop-spree:latest+docker build . -f backend/Dockerfile -t my-shop-spree:latest```-Inside the stage the build runs with `VITE_BASE_PATH=/dashboard/` (asset URLs resolve under the mount) and `VITE_SPREE_API_URL` unset (API calls stay origin-relative). Projects **without** `apps/dashboard/` build exactly what plain `docker build backend/` produces — and if your `backend/Dockerfile` predates dashboard support, the command warns instead of silently shipping the stock dashboard over your customized one.+Inside the dashboard stage the build runs with `VITE_BASE_PATH=/dashboard/` (asset URLs resolve under the mount) and `VITE_SPREE_API_URL` unset (API calls stay origin-relative); the Node toolchain lives only in that throw-away stage. Projects **without** `apps/dashboard/` get the stock dashboard baked instead — and if your `backend/Dockerfile` predates this layout support, the command warns instead of silently shipping the stock dashboard over your customized one (update it from the spree-starter template).## Static host / CDN — the alternative@@ -54,16 +51,15 @@ A middle ground also works: serve `dist/` and proxy `/api/*` + `/rails/*` to Rai## Render-If your project deploys to Render via the Blueprint that `create-spree-app` places at the project root, `spree add dashboard` wires the single-node topology automatically: it extends the backend service's `buildCommand` to also build `apps/dashboard` (Render's Ruby runtime includes Node, and the full repo is available during the build) and adds one env var so the server serves the result:+The Blueprint that `create-spree-app` places at the project root deploys the backend as a **Docker service** built from your repo — the same Dockerfile as everywhere else, with the repo root as context:```yaml-buildCommand: bundle install && … && (cd ../apps/dashboard && corepack enable pnpm && pnpm install && VITE_BASE_PATH=/dashboard/ pnpm build)-envVars:- - key: SPREE_DASHBOARD_DIST_PATH- value: ../apps/dashboard/dist+runtime: docker+dockerfilePath: ./backend/Dockerfile+dockerContext: .```-That's the whole setup — one service, one origin, **your customized dashboard** (it builds from your `apps/dashboard`, not the stock bundle) at `https://your-service.onrender.com/dashboard`. No `VITE_SPREE_API_URL`, no Allowed Origins entry, no extra service. Redeploys rebuild on every push.+That's the whole setup — one service, one origin, **your customized dashboard** (it builds from your `apps/dashboard`, not the stock bundle) at `https://your-service.onrender.com/dashboard`. No `VITE_SPREE_API_URL`, no Allowed Origins entry, no extra service, no build commands to maintain — migrations run from the image entrypoint on boot. Redeploys rebuild on every push, and what Render builds is byte-for-byte what `spree build --production` builds locally.If you prefer the dashboard on Render's CDN instead, add a static-site service by hand using the cross-origin recipe above.diff --git a/docs/developer/deployment/aws.mdx b/docs/developer/deployment/aws.mdxindex c9b82b658c..8eaf5d212d 100644--- a/docs/developer/deployment/aws.mdx+++ b/docs/developer/deployment/aws.mdx@@ -15,7 +15,7 @@ To fully run your Spree application on AWS, you will need the following services|---------|-------------|| [AWS ECS Fargate](https://aws.amazon.com/fargate/) | Fully managed container orchestration — run and scale containers without managing infrastructure. || [AWS RDS](https://aws.amazon.com/rds/) | Managed relational database. Spree works with [Aurora PostgreSQL](https://aws.amazon.com/rds/aurora/), [Aurora MySQL](https://aws.amazon.com/rds/aurora/), [RDS PostgreSQL](https://aws.amazon.com/rds/postgresql/), [RDS MySQL](https://aws.amazon.com/rds/mysql/), and [RDS MariaDB](https://aws.amazon.com/rds/mariadb/). |-| [AWS ElastiCache](https://aws.amazon.com/elasticache/) | Valkey or Redis for background jobs (Sidekiq), [caching](/developer/deployment/caching), and Action Cable. We recommend separate instances for jobs and cache. |+| [AWS 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. |@@ -24,7 +24,7 @@ To fully run your Spree application on AWS, you will need the following services## Docker Image-You can use the [official Docker image](/developer/deployment/docker) (`ghcr.io/spree/spree`) directly, or build your own from your Rails application's Dockerfile.+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:@@ -216,8 +216,6 @@ Create the following secrets in AWS Secrets Manager:| Secret Name | Variable | Description ||---|---|---|| `spree/database-url` | `DATABASE_URL` | PostgreSQL connection URL |-| `spree/redis-url` | `REDIS_URL` | Redis URL for background jobs and Action Cable |-| `spree/redis-cache-url` | `REDIS_CACHE_URL` | Redis URL for caching (separate instance recommended) || `spree/secret-key-base` | `SECRET_KEY_BASE` | Generate with `bin/rails secret` |Optional secrets for email delivery, file storage, and error tracking:@@ -233,7 +231,7 @@ Optional secrets for email delivery, file storage, and error tracking:## ECS Task Definitions-You will need two ECS task definitions: one for the web service and one for the worker service. Save these as `.aws/web-task-definition.json` and `.aws/worker-task-definition.json` in your repository.+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.### Web Service@@ -288,14 +286,6 @@ You will need two ECS task definitions: one for the web service and one for the"name": "DATABASE_URL","valueFrom": "arn:aws:secretsmanager:${AWS_REGION}:${AWS_ACCOUNT_ID}:secret:spree/database-url"},- {- "name": "REDIS_URL",- "valueFrom": "arn:aws:secretsmanager:${AWS_REGION}:${AWS_ACCOUNT_ID}:secret:spree/redis-url"- },- {- "name": "REDIS_CACHE_URL",- "valueFrom": "arn:aws:secretsmanager:${AWS_REGION}:${AWS_ACCOUNT_ID}:secret:spree/redis-cache-url"- },{"name": "SECRET_KEY_BASE","valueFrom": "arn:aws:secretsmanager:${AWS_REGION}:${AWS_ACCOUNT_ID}:secret:spree/secret-key-base"@@ -321,7 +311,9 @@ You will need two ECS task definitions: one for the web service and one for the}```-### Worker Service+### Worker Service (optional scale-out)++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`:```json{@@ -336,7 +328,7 @@ You will need two ECS task definitions: one for the web service and one for the{"name": "worker","image": "${ECR_REGISTRY}/${ECR_REPOSITORY}:${IMAGE_TAG}",- "command": ["bundle", "exec", "sidekiq"],+ "command": ["bin/jobs"],"essential": true,"environment": [{@@ -353,10 +345,6 @@ You will need two ECS task definitions: one for the web service and one for the"name": "DATABASE_URL","valueFrom": "arn:aws:secretsmanager:${AWS_REGION}:${AWS_ACCOUNT_ID}:secret:spree/database-url"},- {- "name": "REDIS_URL",- "valueFrom": "arn:aws:secretsmanager:${AWS_REGION}:${AWS_ACCOUNT_ID}:secret:spree/redis-url"- },{"name": "SECRET_KEY_BASE","valueFrom": "arn:aws:secretsmanager:${AWS_REGION}:${AWS_ACCOUNT_ID}:secret:spree/secret-key-base"@@ -371,7 +359,7 @@ You will need two ECS task definitions: one for the web service and one for the}},"healthCheck": {- "command": ["CMD-SHELL", "pgrep -f sidekiq || exit 1"],+ "command": ["CMD-SHELL", "pgrep -f solid_queue || exit 1"],"interval": 30,"timeout": 5,"retries": 3,@@ -389,10 +377,10 @@ The task definitions above are sized for production. Here is a summary and scali| Service | Fargate CPU | Fargate Memory | Instances ||---|---|---|---|| **Web** | 1 vCPU | 4 GB | 2+ (use ECS Service Auto Scaling) |-| **Worker** | 0.5 vCPU | 2 GB | 1+ |-| **RDS (PostgreSQL)** | — | `db.r6g.large` (2 vCPU, 16 GB) | 1 primary + read replica |-| **ElastiCache (jobs)** | — | `cache.r6g.large` (13 GB) | 1 |-| **ElastiCache (cache)** | — | `cache.r6g.large` (13 GB) | 1 |+| **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@@ -426,7 +414,7 @@ aws application-autoscaling put-scaling-policy \## After Deployment-### Admin Dashboard+### AdminAccess your admin panel at:@@ -464,5 +452,5 @@ aws ecs run-task \- [Asset Storage](/developer/deployment/assets) — configure S3 for product images and uploads- [Configure CDN](/developer/deployment/cdn) — set up CloudFront for asset delivery-- [Configure caching](/developer/deployment/caching) — use ElastiCache for application caching+- [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.diff --git a/docs/developer/deployment/caching.mdx b/docs/developer/deployment/caching.mdxindex e0df883e2f..aca3427ad6 100644--- a/docs/developer/deployment/caching.mdx+++ b/docs/developer/deployment/caching.mdx@@ -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 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 Locallydiff --git a/docs/developer/deployment/docker.mdx b/docs/developer/deployment/docker.mdxindex 8e510f4f09..1957a6b6e9 100644--- a/docs/developer/deployment/docker.mdx+++ b/docs/developer/deployment/docker.mdx@@ -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](/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.-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.ymlservices:postgres:- image: postgres:17-alpine+ image: postgres:18-alpineenvironment:POSTGRES_HOST_AUTH_METHOD: trustvolumes:@@ -39,26 +46,13 @@ services:timeout: 5sretries: 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 imagedepends_on:postgres:condition: service_healthy- redis:- condition: service_healthyenvironment:DATABASE_URL: postgres://postgres@postgres:5432/spree_production- REDIS_URL: redis://redis:6379/0SECRET_KEY_BASE: change-me-to-a-real-secretRAILS_FORCE_SSL: "false"RAILS_ASSUME_SSL: "false"@@ -74,21 +68,8 @@ services:retries: 10start_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,41 +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](/developer/create-spree-app/quickstart) for a fully scaffolded Docker setup with `.env` files, health checks, and optional Next.js storefront — all configured automatically.-</Tip>+### 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](/developer/deployment/environment_variables) 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.-</Tip>+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.diff --git a/docs/developer/deployment/environment_variables.mdx b/docs/developer/deployment/environment_variables.mdxindex d2e34b83d9..2d9468fcc5 100644--- a/docs/developer/deployment/environment_variables.mdx+++ b/docs/developer/deployment/environment_variables.mdx@@ -1,6 +1,6 @@---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, background jobs, SMTP, web server, file storage, and application configuration settings.---Spree uses environment variables for all deployment configuration. No secrets or credentials are stored in the codebase.@@ -12,8 +12,11 @@ These variables are required to run Spree in production.| 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` |+| `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...` |## URLs and Hostsdiff --git a/docs/developer/deployment/render.mdx b/docs/developer/deployment/render.mdxindex 0adc74ed3b..d22c55308b 100644--- a/docs/developer/deployment/render.mdx+++ b/docs/developer/deployment/render.mdx@@ -1,75 +1,59 @@---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](/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:-[](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).+</Tip>-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](/developer/deployment/environment_variables).+Render sets `DATABASE_URL` and `SECRET_KEY_BASE` automatically from the Blueprint. For additional configuration (SMTP, file storage, Sentry, etc.), see [Environment Variables](/developer/deployment/environment_variables).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`](/developer/deployment/environment_variables#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 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.++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 +68,8 @@ To enable auto-scaling, add this to the web service in your `render.yaml`:targetCPUPercent: 80```+High-traffic installs can additionally swap [caching](/developer/deployment/caching) to a managed Redis/Valkey — the default needs no extra service.+## Next StepsRender provides ephemeral storage — uploaded files (product images, etc.) won't persist across deploys. Set up cloud storage:diff --git a/package.json b/package.jsonindex 8dc6587c2f..e66cf2695d 100644--- a/package.json+++ b/package.json@@ -14,9 +14,9 @@"server:create": "git clone --depth 1 https://github.com/spree/spree-starter.git server && rm -rf server/.git server/.gitignore && printf 'SPREE_PATH=..\\nSECRET_KEY_BASE=%s\\n' \"$(openssl rand -hex 64)\" > server/.env","server:setup": "bash scripts/server-setup.sh","server:dashboard": "turbo build --filter=@spree/dashboard && VITE_BASE_PATH=/dashboard/ pnpm --dir packages/dashboard-starter build",- "server:dev": "SPREE_PATH=$PWD docker compose -f server/docker-compose.dev.yml -f scripts/docker-compose.edge.yml up --force-recreate web worker",+ "server:dev": "SPREE_PATH=$PWD docker compose -f server/docker-compose.dev.yml -f scripts/docker-compose.edge.yml up --force-recreate web","server:build": "bash scripts/server-build.sh",- "server:restart": "SPREE_PATH=$PWD docker compose -f server/docker-compose.dev.yml -f scripts/docker-compose.edge.yml restart web worker",+ "server:restart": "SPREE_PATH=$PWD docker compose -f server/docker-compose.dev.yml -f scripts/docker-compose.edge.yml restart web","server:stop": "SPREE_PATH=$PWD docker compose -f server/docker-compose.dev.yml -f scripts/docker-compose.edge.yml down","server:console": "cd server && spree console","server:logs": "cd server && spree logs",diff --git a/packages/cli/CHANGELOG.md b/packages/cli/CHANGELOG.mdindex 5810b16f3a..a32ea8bfe4 100644--- a/packages/cli/CHANGELOG.md+++ b/packages/cli/CHANGELOG.md@@ -1,5 +1,35 @@# @spree/cli+## 2.4.5++### Patch Changes++- `spree build --production` is now a plain `docker build` from the project+root: the updated spree-starter Dockerfile normalizes its own build context+(detecting the `backend/` layout and a customized `apps/dashboard`), so the+staged-copy and named-build-context machinery is gone, and what the CLI+builds is byte-for-byte what Render/Railway build straight from the repo. A+root `.dockerignore` is written when missing so the context stays lean.+Pre-normalization Dockerfiles keep the old `backend/` context, with a+warning when a dashboard would be left out.++- Handle the Solid Queue single-container compose layout: new spree-starter+projects have no `worker` or `redis` services (jobs run inside Puma, stored+in Postgres), so `spree dev`, `restart`, `build`, and `db:reset` now target+the services the compose file actually defines instead of hard-coding+`web worker` — Sidekiq-era projects keep working unchanged. `spree logs+worker` on a worker-less project explains the in-process model and streams+web logs, pointing at the `/jobs` dashboard.++- Removed the `render.yaml` amendment from `spree add dashboard` — the+starter's Blueprint now deploys the backend as a Docker service built from+the repo root, which bakes `apps/dashboard` into the image by itself. The+scaffolded dashboard also pins its package manager (`packageManager` ++`pnpm-workspace.yaml` with `trustLockfile`) so image rebuilds don't break+when pnpm changes install-policy defaults — pnpm 11's `minimumReleaseAge`+re-validation fails any rebuild whose lockfile references day-old packages,+including every Spree release day (`@spree/*` is exempted from the gate).+## 2.4.4### Patch Changesdiff --git a/packages/cli/package.json b/packages/cli/package.jsonindex ecff58f771..0285976dfb 100644--- a/packages/cli/package.json+++ b/packages/cli/package.json@@ -1,6 +1,6 @@{"name": "@spree/cli",- "version": "2.4.4",+ "version": "2.4.5","description": "CLI for managing Spree Commerce projects","type": "module","bin": {diff --git a/packages/cli/src/commands/add.ts b/packages/cli/src/commands/add.tsindex 3b948d94bc..918696db5b 100644--- a/packages/cli/src/commands/add.ts+++ b/packages/cli/src/commands/add.ts@@ -75,7 +75,6 @@ export async function addDashboard(ctx: ProjectContext, opts: AddDashboardOptionp.log.warn(`${pc.bold('apps/dashboard/')} already exists. Nothing to do.`)return}- ensureRenderBlueprintService(ctx.projectDir, detectPackageManager(ctx.projectDir, dashboardDir))p.log.info(`${env === 'written' ? 'Wrote missing' : 'Repaired'} ${pc.bold('apps/dashboard/.env.local')}. Nothing else to do.`,)@@ -97,18 +96,6 @@ export async function addDashboard(ctx: ProjectContext, opts: AddDashboardOptionwriteDashboardEnv(envPath, ctx.port)const pm = detectPackageManager(ctx.projectDir, dashboardDir)- const blueprint = ensureRenderBlueprintService(ctx.projectDir, pm)- if (blueprint === 'amended') {- p.log.info(- `Amended ${pc.bold('render.yaml')}: the backend service now builds the dashboard ` +- `and serves it at ${pc.cyan('/dashboard')} — same origin, nothing else to configure.`,- )- } else if (blueprint === 'unrecognized') {- p.log.warn(- `${pc.bold('render.yaml')} exists but doesn't match the starter Blueprint — ` +- `left untouched. See the dashboard deployment docs to wire it up manually.`,- )- }if (opts.install) {s.start(`Installing dependencies with ${pm}...`)@@ -166,68 +153,6 @@ function resolveBundledTemplate(): string {process.exit(1)}-/**- * Fold the dashboard into the project's Render Blueprint as **single node**:- * the backend web service builds `apps/dashboard` in its own build step- * (Render's Ruby runtime includes Node; the repo is fully cloned even with- * `rootDir: backend`, so `../apps/dashboard` is reachable) and serves it at- * /dashboard via `SPREE_DASHBOARD_DIST_PATH`. Same origin as the API — no- * CORS entries, no `VITE_SPREE_API_URL`, nothing manual after deploy.- *- * The amendment anchors on the starter Blueprint's shape (a `buildCommand:`- * running `bundle install`, followed by that service's `envVars:`). A- * hand-customized Blueprint where those anchors are missing is left- * untouched — returns 'unrecognized' so the caller can point at the- * deployment docs instead of guessing.- *- * Idempotent: a Blueprint already carrying SPREE_DASHBOARD_DIST_PATH is- * left as-is.- */-export function ensureRenderBlueprintService(- projectDir: string,- pm: string,-): 'amended' | 'present' | 'no-blueprint' | 'unrecognized' {- const renderYamlPath = path.join(projectDir, 'render.yaml')- if (!fs.existsSync(renderYamlPath)) return 'no-blueprint'-- const content = fs.readFileSync(renderYamlPath, 'utf-8')- if (content.includes('SPREE_DASHBOARD_DIST_PATH')) return 'present'-- const dashboardBuild =- pm === 'pnpm'- ? 'corepack enable pnpm && pnpm install && VITE_BASE_PATH=/dashboard/ pnpm build'- : pm === 'yarn'- ? 'yarn install && VITE_BASE_PATH=/dashboard/ yarn build'- : 'npm install && VITE_BASE_PATH=/dashboard/ npm run build'-- // 1. Extend the Rails build to also build the dashboard (subshell keeps the- // working directory intact for any commands appended later).- const buildCommandRe = /^([ \t]*)buildCommand:.*bundle install.*$/m- const buildMatch = buildCommandRe.exec(content)- if (!buildMatch) return 'unrecognized'-- let next = content.replace(- buildCommandRe,- (line) => `${line} && (cd ../apps/dashboard && ${dashboardBuild})`,- )-- // 2. Point the server at the built dist. Anchor on the first `envVars:`- // after the build command — the same service's env block. The path is- // resolved relative to the service's working directory (rootDir).- const envVarsRe = /^([ \t]*)envVars:[ \t]*$/m- const afterBuild = next.slice(next.indexOf('buildCommand:'))- const envMatch = envVarsRe.exec(afterBuild)- if (!envMatch) return 'unrecognized'-- const envIndent = `${envMatch[1]} `- const envEntry = `${envIndent}# Serve the dashboard built above at /dashboard (single node — same\n${envIndent}# origin as the API, so no CORS or cookie configuration).\n${envIndent}- key: SPREE_DASHBOARD_DIST_PATH\n${envIndent} value: ../apps/dashboard/dist\n`- const envVarsIndex = next.indexOf('buildCommand:') + envMatch.index + envMatch[0].length- next = `${next.slice(0, envVarsIndex)}\n${envEntry.replace(/\n$/, '')}${next.slice(envVarsIndex)}`-- fs.writeFileSync(renderYamlPath, next)- return 'amended'-}-/*** The bundled template ships its `.gitignore` as `gitignore.template`* (npm never packs `.gitignore` files) — restore the real name on scaffold.diff --git a/packages/cli/src/commands/build.ts b/packages/cli/src/commands/build.tsindex 2f42f20552..f28cf7b099 100644--- a/packages/cli/src/commands/build.ts+++ b/packages/cli/src/commands/build.ts@@ -1,12 +1,11 @@import fs from 'node:fs'-import os from 'node:os'import path from 'node:path'import * as p from '@clack/prompts'import type { Command } from 'commander'import { execa } from 'execa'import pc from 'picocolors'import { detectProject, hasMonorepoSpreePath, isEjectedProject } from '../context.js'-import { dockerCompose } from '../docker.js'+import { appServices, dockerCompose } from '../docker.js'export function registerBuildCommand(program: Command): void {program@@ -100,7 +99,7 @@ async function buildDevImage(flags: { resetBundle?: boolean; yes?: boolean }): P}console.log(`\n${pc.bold('Rebuilding dev image...')}\n`)- await dockerCompose(['build', 'web', 'worker'], ctx.projectDir, {+ await dockerCompose(['build', ...(await appServices(ctx.projectDir))], ctx.projectDir, {stdio: 'inherit',})@@ -119,13 +118,13 @@ async function buildDevImage(flags: { resetBundle?: boolean; yes?: boolean }): P/*** What `spree build --production` will run, computed without touching Docker- * — exported for tests. When the project carries a customized dashboard- * (`apps/dashboard`) AND the backend Dockerfile supports source selection- * (the `DASHBOARD_SOURCE` build arg from spree-starter), the plan stages a- * filtered copy of the app (no node_modules/build output — Docker named- * contexts don't apply .dockerignore) and selects the `custom` dashboard- * stage. Older projects hit neither branch and build exactly what- * `docker build backend/` would — nothing changes for them.+ * — exported for tests. The starter Dockerfile normalizes its own build+ * context (backend/Gemfile marks the project layout; apps/dashboard marks a+ * customized dashboard), so the plan is a plain `docker build` from the+ * project root — the ejected backend and your dashboard ship in one image+ * with zero flags, exactly what Render/Railway run from the repo. A+ * Dockerfile predating the normalization builds from backend/ as before,+ * with a warning when a dashboard would be silently left out.*/export function planProductionBuild(projectDir: string,@@ -134,7 +133,6 @@ export function planProductionBuild(args: string[]imageTag: stringdashboard: 'custom' | 'stock-or-none' | 'unsupported-dockerfile'- stagedDashboardDir?: string} {const backendDir = path.join(projectDir, 'backend')const dockerfile = path.join(backendDir, 'Dockerfile')@@ -149,29 +147,51 @@ export function planProductionBuild(.toLowerCase().replace(/[^a-z0-9_-]/g, '')}-spree:latest`- const args = ['build', backendDir, '-f', dockerfile, '-t', imageTag]+ const hasDashboard = fs.existsSync(path.join(projectDir, 'apps', 'dashboard', 'package.json'))- const dashboardDir = path.join(projectDir, 'apps', 'dashboard')- if (!fs.existsSync(path.join(dashboardDir, 'package.json'))) {- return { args, imageTag, dashboard: 'stock-or-none' }+ // The layout-normalizing Dockerfile leaves a distinctive marker; without+ // it, root context would break the build (the old file expects the Rails+ // app at the context root), so fall back to the old backend/ context.+ if (!fs.readFileSync(dockerfile, 'utf-8').includes('.spree-custom-dashboard')) {+ return {+ args: ['build', backendDir, '-f', dockerfile, '-t', imageTag],+ imageTag,+ dashboard: hasDashboard ? 'unsupported-dockerfile' : 'stock-or-none',+ }}- if (!fs.readFileSync(dockerfile, 'utf-8').includes('DASHBOARD_SOURCE')) {- return { args, imageTag, dashboard: 'unsupported-dockerfile' }+ ensureRootDockerignore(projectDir)+ return {+ args: ['build', projectDir, '-f', dockerfile, '-t', imageTag],+ imageTag,+ dashboard: hasDashboard ? 'custom' : 'stock-or-none',}+}- const staged = fs.mkdtempSync(path.join(os.tmpdir(), 'spree-dashboard-src-'))- fs.cpSync(dashboardDir, staged, {- recursive: true,- filter: (src) => {- const base = path.basename(src)- return base !== 'node_modules' && base !== 'dist' && base !== '.tanstack'- },- })- args.push('--build-arg', 'DASHBOARD_SOURCE=custom', '--build-context', `dashboard-src=${staged}`)- return { args, imageTag, dashboard: 'custom', stagedDashboardDir: staged }+/**+ * A root-context build without a .dockerignore would upload node_modules and+ * friends as build context — write the standard one when missing (projects+ * scaffolded before it existed). Never overwrites.+ */+export function ensureRootDockerignore(projectDir: string): void {+ const target = path.join(projectDir, '.dockerignore')+ if (fs.existsSync(target)) return+ fs.writeFileSync(target, ROOT_DOCKERIGNORE)}+export const ROOT_DOCKERIGNORE = `# Build context for backend/Dockerfile (repo root): keep it to sources.+**/node_modules+**/.git+.spree+apps/storefront+apps/dashboard/dist+apps/dashboard/.tanstack+backend/log+backend/tmp+backend/storage+backend/.env*+`+/*** Build the production image (the Dockerfile's final stage) — the one you* push to a registry and run on Render/Railway/AWS/anywhere. Unlike the dev@@ -191,26 +211,20 @@ async function buildProductionImage(projectDir: string, tag?: string): Promise<v} else if (plan.dashboard === 'unsupported-dockerfile') {p.log.warn(`${pc.bold('apps/dashboard/')} exists, but ${pc.bold('backend/Dockerfile')} predates ` +- `dashboard support (no DASHBOARD_SOURCE build arg) — the image will NOT include your ` +- `dashboard. Update the Dockerfile from the spree-starter template to bake it in.`,+ `dashboard support — the image will NOT include your dashboard. Update the ` ++ `Dockerfile from the spree-starter template to bake it in.`,)}console.log(`\n${pc.bold(`Building production image ${plan.imageTag}...`)}\n`)- try {- await execa('docker', plan.args, { cwd: projectDir, stdio: 'inherit' })- } finally {- if (plan.stagedDashboardDir) {- fs.rmSync(plan.stagedDashboardDir, { recursive: true, force: true })- }- }+ await execa('docker', plan.args, { cwd: projectDir, stdio: 'inherit' })p.note([`Run it: ${pc.cyan(`docker run --rm -p 3000:3000 ${plan.imageTag}`)}`,`Push it: ${pc.cyan(`docker tag ${plan.imageTag} <registry>/<repo> && docker push <registry>/<repo>`)}`,plan.dashboard !== 'unsupported-dockerfile'- ? `Dashboard: served at ${pc.bold('/dashboard')} when the image includes one.`+ ? `Dashboard: served at ${pc.bold('/dashboard')} on the same origin as the API.`: '',].filter(Boolean)diff --git a/packages/cli/src/commands/db.ts b/packages/cli/src/commands/db.tsindex 2a17543a38..f25390dc54 100644--- a/packages/cli/src/commands/db.ts+++ b/packages/cli/src/commands/db.ts@@ -2,7 +2,13 @@ import * as p from '@clack/prompts'import type { Command } from 'commander'import pc from 'picocolors'import { detectProject, hasMonorepoSpreePath } from '../context.js'-import { dockerCompose, dockerComposeExec, dockerComposeRun, isServiceRunning } from '../docker.js'+import {+ appServices,+ dockerCompose,+ dockerComposeExec,+ dockerComposeRun,+ isServiceRunning,+} from '../docker.js'export const RESET_TASK = ['bin/rails',@@ -59,12 +65,13 @@ export function registerDbCommand(program: Command): void {// RAILS_MAX_THREADS pooled connections), so we only need to know if either// is running; probe them concurrently.let stackUp: boolean+ let services: string[]try {- const [webUp, workerUp] = await Promise.all([- isServiceRunning('web', ctx.projectDir),- isServiceRunning('worker', ctx.projectDir),- ])- stackUp = webUp || workerUp+ services = await appServices(ctx.projectDir)+ const running = await Promise.all(+ services.map((service) => isServiceRunning(service, ctx.projectDir)),+ )+ stackUp = running.some(Boolean)} catch (err) {// `compose ps` itself failed: broken/stale compose, daemon down, unknown// service. Point home rather than dumping the raw env-file error (mirrors@@ -81,9 +88,9 @@ export function registerDbCommand(program: Command): void {if (stackUp) {const s = p.spinner()- s.start('Stopping web + worker to release database connections...')- await dockerCompose(['stop', 'web', 'worker'], ctx.projectDir)- s.stop('Stopped web + worker.')+ s.start('Stopping the app to release database connections...')+ await dockerCompose(['stop', ...services], ctx.projectDir)+ s.stop('App stopped.')}try {diff --git a/packages/cli/src/commands/dev.ts b/packages/cli/src/commands/dev.tsindex a0c505032b..d453d53989 100644--- a/packages/cli/src/commands/dev.ts+++ b/packages/cli/src/commands/dev.ts@@ -18,6 +18,7 @@ import {warnDashboardNotRunnable,} from '../dashboard-server.js'import {+ appServices,buildAdminStylesheets,dockerCompose,hasProjectContainers,@@ -123,7 +124,7 @@ export function registerDevCommand(program: Command): void {)p.log.info(- `Starting services — ${withDashboard ? 'API + dashboard logs' : 'web + worker logs'} stream below. ` ++ `Starting services — ${withDashboard ? 'API + dashboard logs' : 'API logs'} stream below. ` +`${pc.bold('Ctrl+C')} stops them ` +`(databases keep running; ${pc.bold('spree stop')} shuts everything down).\n`,)@@ -194,10 +195,14 @@ export function registerDevCommand(program: Command): void {// the finally covers non-signal exits.dashboard = withDashboard ? startDashboardDevServer(ctx.projectDir) : null- result = await dockerCompose(['up', 'web', 'worker'], ctx.projectDir, {- stdio: 'inherit',- reject: false,- })+ result = await dockerCompose(+ ['up', ...(await appServices(ctx.projectDir))],+ ctx.projectDir,+ {+ stdio: 'inherit',+ reject: false,+ },+ )} finally {dashboard?.stop()process.off('SIGINT', ignoreSigint)@@ -213,7 +218,7 @@ export function registerDevCommand(program: Command): void {}p.outro(- `${withDashboard ? 'API + dashboard' : 'Web + worker'} stopped. Databases keep running — ${pc.bold('spree stop')} shuts everything down.`,+ `${withDashboard ? 'API + dashboard' : 'API'} stopped. Databases keep running — ${pc.bold('spree stop')} shuts everything down.`,)})}diff --git a/packages/cli/src/commands/logs.ts b/packages/cli/src/commands/logs.tsindex e9db48486f..5708b3a436 100644--- a/packages/cli/src/commands/logs.ts+++ b/packages/cli/src/commands/logs.ts@@ -1,14 +1,27 @@+import * as p from '@clack/prompts'import type { Command } from 'commander'+import pc from 'picocolors'import { detectProject } from '../context.js'-import { streamLogs } from '../docker.js'+import { appServices, streamLogs } from '../docker.js'export function registerLogsCommand(program: Command): void {program.command('logs').description('Stream service logs')- .argument('[service]', 'service name (web or worker)', 'web')+ .argument('[service]', 'service name (e.g. web)', 'web').action(async (service: string) => {const ctx = detectProject()+ // Solid Queue projects have no worker service — jobs run inside the web+ // process, so their logs are web's logs.+ if (service === 'worker' && !(await appServices(ctx.projectDir)).includes('worker')) {+ p.log.info(+ `This project has no ${pc.bold('worker')} service — jobs run inside the web process ` ++ `(Solid Queue in Puma). Streaming ${pc.bold('web')} logs; the job dashboard is at ` ++ `${pc.cyan(`http://localhost:${ctx.port}/jobs`)}.`,+ )+ await streamLogs('web', ctx.projectDir)+ return+ }await streamLogs(service, ctx.projectDir)})}diff --git a/packages/cli/src/commands/restart.ts b/packages/cli/src/commands/restart.tsindex 9e73bc27df..29f0789232 100644--- a/packages/cli/src/commands/restart.ts+++ b/packages/cli/src/commands/restart.ts@@ -1,7 +1,7 @@import * as p from '@clack/prompts'import type { Command } from 'commander'import { detectProject } from '../context.js'-import { dockerCompose } from '../docker.js'+import { appServices, dockerCompose } from '../docker.js'export function registerRestartCommand(program: Command): void {program@@ -13,7 +13,7 @@ export function registerRestartCommand(program: Command): void {const s = p.spinner()s.start('Restarting web + worker...')try {- await dockerCompose(['restart', 'web', 'worker'], ctx.projectDir)+ await dockerCompose(['restart', ...(await appServices(ctx.projectDir))], ctx.projectDir)s.stop('Services restarted.')} catch (error) {s.stop('Restart failed.')diff --git a/packages/cli/src/docker.ts b/packages/cli/src/docker.tsindex ed4c76aee6..9b0e3b4384 100644--- a/packages/cli/src/docker.ts+++ b/packages/cli/src/docker.ts@@ -65,6 +65,26 @@ export async function rakeTask(.trim()}+/**+ * The app services the project's compose file actually defines — ['web'] on+ * the Solid Queue single-container layout (jobs run inside Puma), ['web',+ * 'worker'] on Sidekiq-era projects. Commands target what exists instead of+ * hard-coding the old two-service shape.+ */+export async function appServices(projectDir: string): Promise<string[]> {+ try {+ const { stdout } = await execa('docker', ['compose', 'config', '--services'], {+ cwd: projectDir,+ })+ const services = stdout.split('\n').map((line) => line.trim())+ const app = ['web', 'worker'].filter((name) => services.includes(name))+ return app.length > 0 ? app : ['web']+ } catch {+ // A broken compose file surfaces on the real command that follows.+ return ['web']+ }+}+/*** Whether compose has ever created a container (any state, including exited)* for this project.diff --git a/packages/cli/tests/add-dashboard.test.ts b/packages/cli/tests/add-dashboard.test.tsindex aca9d30f1e..c71c0e9097 100644--- a/packages/cli/tests/add-dashboard.test.ts+++ b/packages/cli/tests/add-dashboard.test.ts@@ -2,11 +2,7 @@ import fs from 'node:fs'import os from 'node:os'import path from 'node:path'import { afterEach, beforeEach, describe, expect, it } from 'vitest'-import {- addDashboard,- ensureDashboardDevEnv,- ensureRenderBlueprintService,-} from '../src/commands/add.js'+import { addDashboard, ensureDashboardDevEnv } from '../src/commands/add.js'import type { ProjectContext } from '../src/types.js'/**@@ -80,77 +76,6 @@ describe('addDashboard', () => {await addDashboard(ctx(), { template: templateDir, install: false })expect(fs.readFileSync(envPath, 'utf-8')).toContain('http://localhost:3999')})-- describe('Render Blueprint single-node amendment', () => {- // The starter Blueprint shape after create-spree-app relocates it.- const BLUEPRINT = `services:- - type: web- name: spree- runtime: ruby- rootDir: backend- plan: free- buildCommand: bundle install && bundle exec rails assets:precompile && bundle exec rails db:prepare- startCommand: bundle exec puma -C config/puma.rb- envVars:- - key: DATABASE_URL- fromDatabase:- name: spree-db- property: connectionString-- - type: redis- name: spree-redis--databases:- - name: spree-db-`-- it('extends the backend service to build and serve the dashboard', async () => {- fs.writeFileSync(path.join(projectDir, 'render.yaml'), BLUEPRINT)-- await addDashboard(ctx(), { template: templateDir, install: false })-- const content = fs.readFileSync(path.join(projectDir, 'render.yaml'), 'utf-8')- // Build step appended to the Rails buildCommand, dashboard built with- // the sub-path base and no absolute API URL (origin-relative).- expect(content).toContain(- 'bundle exec rails db:prepare && (cd ../apps/dashboard && corepack enable pnpm && pnpm install && VITE_BASE_PATH=/dashboard/ pnpm build)',- )- // Served by the same service — env var inside the backend's envVars.- expect(content).toContain('- key: SPREE_DASHBOARD_DIST_PATH')- expect(content).toContain('value: ../apps/dashboard/dist')- expect(content.indexOf('SPREE_DASHBOARD_DIST_PATH')).toBeLessThan(- content.indexOf('DATABASE_URL'),- )- // No cross-origin machinery: no static site, no VITE_SPREE_API_URL.- expect(content).not.toContain('VITE_SPREE_API_URL')- expect(content).not.toContain('runtime: static')- })-- it('is idempotent and picks the build command from the project lockfile', async () => {- fs.writeFileSync(path.join(projectDir, 'render.yaml'), BLUEPRINT)- fs.writeFileSync(path.join(projectDir, 'package-lock.json'), '{}')-- expect(ensureRenderBlueprintService(projectDir, 'npm')).toBe('amended')- const once = fs.readFileSync(path.join(projectDir, 'render.yaml'), 'utf-8')- expect(once).toContain('npm install && VITE_BASE_PATH=/dashboard/ npm run build')-- expect(ensureRenderBlueprintService(projectDir, 'npm')).toBe('present')- expect(fs.readFileSync(path.join(projectDir, 'render.yaml'), 'utf-8')).toBe(once)- })-- it('does nothing when the project has no Blueprint', async () => {- expect(ensureRenderBlueprintService(projectDir, 'pnpm')).toBe('no-blueprint')- expect(fs.existsSync(path.join(projectDir, 'render.yaml'))).toBe(false)- })-- it('leaves an unrecognized Blueprint untouched', () => {- const custom = 'services:\n - type: web\n name: my-thing\n runtime: docker\n'- fs.writeFileSync(path.join(projectDir, 'render.yaml'), custom)-- expect(ensureRenderBlueprintService(projectDir, 'pnpm')).toBe('unrecognized')- expect(fs.readFileSync(path.join(projectDir, 'render.yaml'), 'utf-8')).toBe(custom)- })- })})describe('ensureDashboardDevEnv', () => {diff --git a/packages/cli/tests/build-production.test.ts b/packages/cli/tests/build-production.test.tsindex df0c839b06..b326714b35 100644--- a/packages/cli/tests/build-production.test.ts+++ b/packages/cli/tests/build-production.test.ts@@ -6,12 +6,13 @@ import { planProductionBuild } from '../src/commands/build.js'/*** Pure planning logic for `spree build --production` — the safety contract:- * projects without apps/dashboard (or with a pre-dashboard Dockerfile) build- * exactly what `docker build backend/` would.+ * a layout-normalizing Dockerfile builds from the project root (the ejected+ * backend and apps/dashboard travel in the context, zero flags); an older+ * Dockerfile keeps the backend/ context it expects, with the dashboard+ * flagged as left out.*/describe('planProductionBuild', () => {let projectDir: string- const staged: string[] = []beforeEach(() => {projectDir = fs.mkdtempSync(path.join(os.tmpdir(), 'spree-prod-build-'))@@ -20,9 +21,11 @@ describe('planProductionBuild', () => {afterEach(() => {fs.rmSync(projectDir, { recursive: true, force: true })- for (const dir of staged.splice(0)) fs.rmSync(dir, { recursive: true, force: true })})+ // The marker the layout-normalizing starter Dockerfile carries.+ const NORMALIZING_DOCKERFILE = 'FROM alpine AS ctx\n# .spree-custom-dashboard\nFROM ruby\n'+function writeDockerfile(content: string) {fs.writeFileSync(path.join(projectDir, 'backend', 'Dockerfile'), content)}@@ -31,66 +34,80 @@ describe('planProductionBuild', () => {const dir = path.join(projectDir, 'apps', 'dashboard')fs.mkdirSync(path.join(dir, 'src'), { recursive: true })fs.writeFileSync(path.join(dir, 'package.json'), '{"name":"dashboard"}\n')- fs.writeFileSync(path.join(dir, 'src', 'main.tsx'), '// entry\n')- fs.mkdirSync(path.join(dir, 'node_modules', 'left-over'), { recursive: true })- fs.mkdirSync(path.join(dir, 'dist'))- fs.writeFileSync(path.join(dir, 'dist', 'stale.js'), '')}it('throws without a backend Dockerfile', () => {expect(() => planProductionBuild(projectDir)).toThrow(/backend\/Dockerfile/)})- it('builds plain when the project has no dashboard app', () => {- writeDockerfile('FROM ruby\n')+ it('builds from the project root with a layout-normalizing Dockerfile', () => {+ writeDockerfile(NORMALIZING_DOCKERFILE)+ writeDashboardApp()const plan = planProductionBuild(projectDir, 'shop:1')- expect(plan.dashboard).toBe('stock-or-none')+ expect(plan.dashboard).toBe('custom')expect(plan.args).toEqual(['build',- path.join(projectDir, 'backend'),+ projectDir,'-f',path.join(projectDir, 'backend', 'Dockerfile'),'-t','shop:1',])- expect(plan.stagedDashboardDir).toBeUndefined()})- it('builds plain and flags a Dockerfile without dashboard support', () => {- writeDockerfile('FROM ruby\n')- writeDashboardApp()+ it('writes the root .dockerignore when missing, never overwriting', () => {+ writeDockerfile(NORMALIZING_DOCKERFILE)++ planProductionBuild(projectDir)+ const ignorePath = path.join(projectDir, '.dockerignore')+ expect(fs.readFileSync(ignorePath, 'utf-8')).toContain('**/node_modules')++ fs.writeFileSync(ignorePath, '# mine\n')+ planProductionBuild(projectDir)+ expect(fs.readFileSync(ignorePath, 'utf-8')).toBe('# mine\n')+ })++ it('reports stock for a normalizing Dockerfile without a dashboard app', () => {+ writeDockerfile(NORMALIZING_DOCKERFILE)const plan = planProductionBuild(projectDir)- expect(plan.dashboard).toBe('unsupported-dockerfile')- expect(plan.args).not.toContain('--build-context')- expect(plan.args).not.toContain('--build-arg')+ expect(plan.dashboard).toBe('stock-or-none')+ expect(plan.args[1]).toBe(projectDir)})- it('selects the custom stage and stages a filtered dashboard copy', () => {- writeDockerfile('ARG DASHBOARD_SOURCE=stock\nFROM ruby\n')+ it('keeps the backend/ context for a pre-normalization Dockerfile', () => {+ writeDockerfile('FROM ruby\n')++ const plan = planProductionBuild(projectDir, 'shop:1')++ expect(plan.dashboard).toBe('stock-or-none')+ expect(plan.args).toEqual([+ 'build',+ path.join(projectDir, 'backend'),+ '-f',+ path.join(projectDir, 'backend', 'Dockerfile'),+ '-t',+ 'shop:1',+ ])+ // No root-context machinery for a Dockerfile that can't use it.+ expect(fs.existsSync(path.join(projectDir, '.dockerignore'))).toBe(false)+ })++ it('flags a pre-normalization Dockerfile when a dashboard would be left out', () => {+ writeDockerfile('FROM ruby\n')writeDashboardApp()const plan = planProductionBuild(projectDir)- if (plan.stagedDashboardDir) staged.push(plan.stagedDashboardDir)- expect(plan.dashboard).toBe('custom')- expect(plan.args).toContain('DASHBOARD_SOURCE=custom')- const contextArg = plan.args[plan.args.indexOf('--build-context') + 1]- expect(contextArg).toBe(`dashboard-src=${plan.stagedDashboardDir}`)-- // Staged copy carries source but never host artifacts.- const stagedDir = plan.stagedDashboardDir as string- expect(fs.existsSync(path.join(stagedDir, 'package.json'))).toBe(true)- expect(fs.existsSync(path.join(stagedDir, 'src', 'main.tsx'))).toBe(true)- expect(fs.existsSync(path.join(stagedDir, 'node_modules'))).toBe(false)- expect(fs.existsSync(path.join(stagedDir, 'dist'))).toBe(false)+ expect(plan.dashboard).toBe('unsupported-dockerfile')+ expect(plan.args[1]).toBe(path.join(projectDir, 'backend'))})it('derives a sanitized default tag from the project directory', () => {- writeDockerfile('FROM ruby\n')+ writeDockerfile(NORMALIZING_DOCKERFILE)const plan = planProductionBuild(projectDir)diff --git a/packages/cli/tests/db.test.ts b/packages/cli/tests/db.test.tsindex 1f6762fc30..3733c98ca1 100644--- a/packages/cli/tests/db.test.ts+++ b/packages/cli/tests/db.test.ts@@ -12,6 +12,9 @@ vi.mock('../src/context', () => ({}))vi.mock('../src/docker', () => ({+ // Sidekiq-era compose shape by default — these tests exercise the two-service+ // path; the Solid Queue single-service shape drops 'worker' from this list.+ appServices: vi.fn().mockResolvedValue(['web', 'worker']),dockerCompose: vi.fn().mockResolvedValue(undefined),dockerComposeExec: vi.fn().mockResolvedValue(undefined),dockerComposeRun: vi.fn().mockResolvedValue(undefined),diff --git a/packages/create-spree-app/CHANGELOG.md b/packages/create-spree-app/CHANGELOG.mdindex 7f20344913..ee9f34ac67 100644--- a/packages/create-spree-app/CHANGELOG.md+++ b/packages/create-spree-app/CHANGELOG.md@@ -1,5 +1,16 @@# create-spree-app+## 1.1.3++### Patch Changes++- Single-node deployment out of the box: the relocated `render.yaml` now+deploys the backend as a Docker service built from the repo root (verbatim+from the starter — no more `rootDir` rewriting), so the ejected backend and+your customized `apps/dashboard` ship in one image with the dashboard+served same-origin at `/dashboard`. New projects also get a root+`.dockerignore` keeping that build context to sources.+## 1.1.2### Patch Changesdiff --git a/packages/create-spree-app/package.json b/packages/create-spree-app/package.jsonindex 34b670c39e..12d85921a9 100644--- a/packages/create-spree-app/package.json+++ b/packages/create-spree-app/package.json@@ -1,6 +1,6 @@{"name": "create-spree-app",- "version": "1.1.2",+ "version": "1.1.3","description": "Create a new Spree Commerce project with a single command","type": "module","bin": "./dist/index.js",diff --git a/packages/create-spree-app/src/backend.ts b/packages/create-spree-app/src/backend.tsindex aa1732bace..455a268289 100644--- a/packages/create-spree-app/src/backend.ts+++ b/packages/create-spree-app/src/backend.ts@@ -57,15 +57,13 @@ export function prepareBackendTemplate(projectDir: string): void {}// Render reads a single Blueprint from the repository root. The starter ships- // render.yaml authored for a repo where the Rails app *is* the root; left in- // backend/ it is invisible to Render, and even at the root its services would- // build from the wrong directory. Relocate it to the project root with- // `rootDir: backend` on every buildable service.+ // The starter authors render.yaml for exactly this project layout (Docker+ // runtime, backend/Dockerfile built with the repo root as context, so the+ // ejected backend and apps/dashboard ship in one image) — Render just needs+ // it at the repo root where Blueprints are read.const srcRenderYaml = path.join(backendDir, 'render.yaml')if (fs.existsSync(srcRenderYaml)) {- const content = fs.readFileSync(srcRenderYaml, 'utf-8')- fs.writeFileSync(path.join(projectDir, 'render.yaml'), adaptRenderYamlForNestedBackend(content))- fs.rmSync(srcRenderYaml, { force: true })+ fs.renameSync(srcRenderYaml, path.join(projectDir, 'render.yaml'))}}@@ -100,23 +98,3 @@ export function adaptWorkflowForNestedBackend(content: string): string {return result}--/**- * Rewrite the starter's Render Blueprint so each service that builds from source- * deploys the `backend/` subdirectory instead of the repo root. The starter- * authors render.yaml for a repo where the Rails app *is* the root; in the- * wrapper project the app lives under backend/, so without `rootDir: backend`- * Render runs `bundle install` at the root (no Gemfile) and the build fails.- *- * `rootDir` is added after every `runtime:` line — the marker of a- * build-from-source service (web, worker) — while managed services (redis,- * databases) have no runtime and are left untouched. The commented-out worker- * template is handled too: its `runtime:` line keeps its `#` prefix, so- * uncommenting the block yields a correctly-rooted worker.- */-export function adaptRenderYamlForNestedBackend(content: string): string {- return content.replace(- /^([ \t]*(?:#[ \t]*)?)runtime:.*$/gm,- (line, prefix) => `${line}\n${prefix}rootDir: backend`,- )-}diff --git a/packages/create-spree-app/src/scaffold.ts b/packages/create-spree-app/src/scaffold.tsindex 7724686c30..9353d6787c 100644--- a/packages/create-spree-app/src/scaffold.ts+++ b/packages/create-spree-app/src/scaffold.ts@@ -20,7 +20,7 @@ import {import { agentsMdContent, rootClaudeMdContent } from './templates/claude-md.js'import { dependabotContent } from './templates/dependabot.js'import { envContent } from './templates/env.js'-import { gitignoreContent } from './templates/gitignore.js'+import { dockerignoreContent, gitignoreContent } from './templates/gitignore.js'import { rootPackageJsonContent } from './templates/package-json.js'import { readmeContent } from './templates/readme.js'import type { PackageManager, ScaffoldOptions } from './types.js'@@ -95,6 +95,7 @@ export async function scaffold(options: ScaffoldOptions): Promise<void> {)fs.writeFileSync(path.join(projectDir, 'package.json'), rootPackageJsonContent(projectName))fs.writeFileSync(path.join(projectDir, '.gitignore'), gitignoreContent())+ fs.writeFileSync(path.join(projectDir, '.dockerignore'), dockerignoreContent())fs.writeFileSync(path.join(projectDir, 'AGENTS.md'), agentsMdContent())s.stop('Project structure created.')diff --git a/packages/create-spree-app/src/templates/gitignore.ts b/packages/create-spree-app/src/templates/gitignore.tsindex e7684ae10a..47bbf61e8c 100644--- a/packages/create-spree-app/src/templates/gitignore.ts+++ b/packages/create-spree-app/src/templates/gitignore.ts@@ -7,3 +7,23 @@ export function gitignoreContent(): string {.spree/`}++/**+ * Build context for backend/Dockerfile (repo root): the image build ships+ * the ejected backend plus apps/dashboard, so keep the context to sources.+ * Mirrors @spree/cli's ensureRootDockerignore for pre-existing projects.+ */+export function dockerignoreContent(): string {+ return `# Build context for backend/Dockerfile (repo root): keep it to sources.+**/node_modules+**/.git+.spree+apps/storefront+apps/dashboard/dist+apps/dashboard/.tanstack+backend/log+backend/tmp+backend/storage+backend/.env*+`+}diff --git a/packages/create-spree-app/tests/backend.test.ts b/packages/create-spree-app/tests/backend.test.tsindex 49cc909435..e8bff4c141 100644--- a/packages/create-spree-app/tests/backend.test.ts+++ b/packages/create-spree-app/tests/backend.test.ts@@ -2,11 +2,7 @@ import fs from 'node:fs'import os from 'node:os'import path from 'node:path'import { afterEach, describe, expect, it } from 'vitest'-import {- adaptRenderYamlForNestedBackend,- adaptWorkflowForNestedBackend,- prepareBackendTemplate,-} from '../src/backend'+import { adaptWorkflowForNestedBackend, prepareBackendTemplate } from '../src/backend'// Mirrors spree-starter's .github/workflows/backend-ci.yml (the workflow that// create-spree-app relocates to the generated project root).@@ -115,26 +111,6 @@ describe('adaptWorkflowForNestedBackend', () => {})})-describe('adaptRenderYamlForNestedBackend', () => {- it('adds rootDir: backend to the buildable web service', () => {- const result = adaptRenderYamlForNestedBackend(RENDER_YAML)- expect(result).toContain(' runtime: ruby\n rootDir: backend\n')- })-- it('adds a commented rootDir to the commented worker so uncommenting still deploys', () => {- const result = adaptRenderYamlForNestedBackend(RENDER_YAML)- expect(result).toContain(' # runtime: ruby\n # rootDir: backend\n')- })-- it('leaves managed services (no runtime) untouched', () => {- const result = adaptRenderYamlForNestedBackend(RENDER_YAML)- // Only web + the commented worker have a runtime, so exactly two rootDirs;- // redis has none and is left verbatim.- expect(result.match(/rootDir: backend/g)).toHaveLength(2)- expect(result).toContain(' - type: redis\n name: spree-redis\n plan: free')- })-})-describe('prepareBackendTemplate', () => {const tempDirs: string[] = []@@ -181,13 +157,14 @@ describe('prepareBackendTemplate', () => {expect(fs.existsSync(path.join(projectDir, 'backend', 'README.md'))).toBe(false)})- it('relocates render.yaml to the project root with rootDir: backend', () => {+ it('relocates render.yaml to the project root verbatim', () => {const projectDir = seedClonedBackend()prepareBackendTemplate(projectDir)const moved = path.join(projectDir, 'render.yaml')expect(fs.existsSync(moved)).toBe(true)- expect(fs.readFileSync(moved, 'utf-8')).toContain(' runtime: ruby\n rootDir: backend\n')+ // Authored by the starter for exactly this layout — no rewriting.+ expect(fs.readFileSync(moved, 'utf-8')).toBe(RENDER_YAML)// The original in backend/ is removed so Render never reads a stale copy.expect(fs.existsSync(path.join(projectDir, 'backend', 'render.yaml'))).toBe(false)})diff --git a/scripts/docker-compose.edge.yml b/scripts/docker-compose.edge.ymlindex 49527a9e10..19a90d10ef 100644--- a/scripts/docker-compose.edge.yml+++ b/scripts/docker-compose.edge.yml@@ -7,7 +7,7 @@## SPREE_PATH=/absolute/host/path/to/spree-monorepo \# docker compose -f docker-compose.dev.yml -f docker-compose.edge.yml \-# up -d --force-recreate web worker+# up -d --force-recreate web## Without -f docker-compose.edge.yml, regular dev usage is unaffected:# no extra mounts, no SPREE_PATH dependency, runs identically on@@ -42,7 +42,7 @@ services:entrypoint: []# Self-healing boot. Monorepo pulls and starter updates routinely drift# Gemfile.lock ahead of the bundle_cache volume and add new engine- # migrations — without this, web/worker crash-loop on Bundler::GemNotFound+ # migrations — without this, web crash-loops on Bundler::GemNotFound# or 500 on ActiveRecord::PendingMigrationError after every such pull.# `bundle check` is sub-second when clean; the rails invocation is one# boot (~5s) that no-ops when nothing changed.@@ -64,24 +64,3 @@ services:"sh", "-c","(bundle check || bundle install) && rm -f public/assets/.manifest.json && bin/rails spree:install:migrations db:prepare && bin/rails spree:admin:tailwindcss:build && (bin/rails spree:admin:tailwindcss:watch &) && exec bin/rails server -b 0.0.0.0 -p 3000"]-- worker:- environment:- SPREE_PATH: ${SPREE_PATH}- volumes:- - ${SPREE_PATH}:${SPREE_PATH}- entrypoint: []- # Gate Sidekiq on web actually serving: the web boot chain starts Puma- # only after bundle install + spree:install:migrations + db:prepare have- # all succeeded, so "/up answers" covers everything the worker needs —- # a satisfied bundle (shared bundle_cache volume) AND a fully migrated,- # seeded database. Gating on `bundle check` alone raced the migrations:- # a clean bundle let Sidekiq run jobs against a half-prepared schema.- # The Host header matters: dev-mode HostAuthorization rejects the- # compose-internal hostname (`web`) with a 403, so curl presents an- # allowed host instead.- command:- [- "sh", "-c",- "i=0; until curl -fsS -o /dev/null -H 'Host: localhost' http://web:3000/up 2>/dev/null; do i=$$((i+1)); if [ \"$$i\" -ge 200 ]; then echo 'worker: web did not become ready within 10 minutes — inspect with: docker compose logs web' >&2; exit 1; fi; echo 'worker: waiting for web to finish booting (bundle + migrations + db:prepare)…'; sleep 3; done; exec bundle exec sidekiq"- ]diff --git a/scripts/server-setup.sh b/scripts/server-setup.shindex d1e461b58d..a89a3d702b 100755--- a/scripts/server-setup.sh+++ b/scripts/server-setup.sh@@ -70,7 +70,7 @@ fistep "Starting the edge stack"# Detached on purpose — `pnpm server:dev` runs the stack in the foreground# (streaming logs, Ctrl+C to stop); setup needs to continue past the boot.-SPREE_PATH="$ROOT" docker compose -f "$DEV_COMPOSE" -f "$EDGE_OVERLAY" up -d --force-recreate web worker+SPREE_PATH="$ROOT" docker compose -f "$DEV_COMPOSE" -f "$EDGE_OVERLAY" up -d --force-recreate webstep "Waiting for the stack to finish booting"# The edge web boot runs bundle install + spree:install:migrations +diff --git a/scripts/sync-dashboard-starter.mjs b/scripts/sync-dashboard-starter.mjsindex b3cfb92561..6863e51746 100644--- a/scripts/sync-dashboard-starter.mjs+++ b/scripts/sync-dashboard-starter.mjs@@ -37,6 +37,10 @@ fs.mkdirSync(targetDir, { recursive: true })const EXCLUDE = new Set(['node_modules', 'dist', '.turbo', '.tanstack'])const MONOREPO_ONLY_DEV_DEPS = new Set(['@spree/dashboard-plugin-example'])+// Bump deliberately (with an image-build test) — pnpm majors have changed+// install-policy behavior under existing lockfiles.+const TEMPLATE_PNPM_VERSION = '11.13.1'+// Clear the target working tree (keep .git) so deletions in the monorepo// propagate instead of accumulating stale files.for (const entry of fs.readdirSync(targetDir)) {@@ -81,8 +85,38 @@ for (const section of ['dependencies', 'devDependencies']) {}}}+// Pin the package manager so scaffolded apps (and the Docker image builds+// that run `corepack enable pnpm` against them) use a known pnpm instead of+// whatever is latest — pnpm 11 changed install-policy defaults under+// existing lockfiles, which broke image rebuilds. Injected here rather than+// in the monorepo source, where the workspace root's pin governs.+pkg.packageManager = `pnpm@${TEMPLATE_PNPM_VERSION}`fs.writeFileSync(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`)+// --- pnpm-workspace.yaml: install policy for scaffolded apps -----------------+// Standalone-only (the monorepo workspace root governs inside the repo).+// trustLockfile: pnpm 11 re-applies minimumReleaseAge (default 24h) to every+// lockfile entry, so an image rebuild whose committed lockfile references+// day-old packages fails; the committed lockfile is the trust anchor.+// The @spree/* exemption keeps Spree's own releases installable on day one.+fs.writeFileSync(+ path.join(targetDir, 'pnpm-workspace.yaml'),+ [+ 'packages:',+ " - '.'",+ '# Image rebuilds re-install the committed lockfile verbatim — without this,',+ "# pnpm 11's supply-chain re-validation (minimumReleaseAge) fails any build",+ '# whose lockfile references <24h-old packages you intentionally installed.',+ '# Fresh resolution on your machine still honors the age gate.',+ 'trustLockfile: true',+ "# Spree's own releases shouldn't wait out the age gate — an upgrade right",+ '# after a Spree release would otherwise fail for a day.',+ 'minimumReleaseAgeExclude:',+ " - '@spree/*'",+ '',+ ].join('\n'),+)+// --- biome.json: inline the workspace root config ----------------------------const rootBiome = JSON.parse(fs.readFileSync(path.join(repoRoot, 'biome.json'), 'utf8'))diff --git a/spree/core/app/jobs/spree/imports/process_group_job.rb b/spree/core/app/jobs/spree/imports/process_group_job.rbindex 4bae14c7c3..da1bbaab82 100644--- a/spree/core/app/jobs/spree/imports/process_group_job.rb+++ b/spree/core/app/jobs/spree/imports/process_group_job.rb@@ -1,6 +1,22 @@module Spreemodule Importsclass ProcessGroupJob < Spree::Imports::BaseJob+ # A large import fans out into many group jobs; without a cap they+ # occupy every worker thread as one frees up, starving checkout-critical+ # queues that share the pool. Cap concurrent groups per import at 75%+ # of JOB_THREADS (at least 1), or SPREE_IMPORT_JOB_CONCURRENCY when set+ # (0 disables the cap) — excess jobs wait as blocked executions, not in+ # worker threads. Both values are read by the process enqueueing the+ # import, so on a split web/worker deployment set the explicit override+ # on the web service. The semaphore duration must outlive the slowest+ # group; expiry just lifts the cap, it doesn't lose jobs. Solid+ # Queue-specific (no-op on other adapters).+ import_concurrency = ENV['SPREE_IMPORT_JOB_CONCURRENCY'].presence&.to_i ||+ [Integer(ENV.fetch('JOB_THREADS', 3)) * 3 / 4, 1].max+ if import_concurrency.positive? && respond_to?(:limits_concurrency)+ limits_concurrency to: import_concurrency, key: ->(import_id, _row_ids) { import_id }, duration: 30.minutes+ end+# Rows are loaded in slices so a large group never holds every ImportRow# (and its raw CSV data) in memory for the whole job.ROWS_BATCH_SIZE = 100