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
`spree dev` now runs the app in the foreground like every other dev s… (#14146)
Damian Legawiec3f3f92fa6bd2
diff --git a/.claude/settings.local.json b/.claude/settings.local.jsonindex b6d79e6d03..ea002e041e 100644--- a/.claude/settings.local.json+++ b/.claude/settings.local.json@@ -10,10 +10,10 @@"WebFetch","WebSearch","Task",- "mcp__*","Bash(rm -rf server)","Bash(git clone *)",- "Bash(rm -rf server/.git server/.gitignore)"+ "Bash(rm -rf server/.git server/.gitignore)",+ "Skill(update-config)"],"deny": ["Bash(sudo *)",diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.mdindex 30bd4ae079..c4cb0bd558 100644--- a/.github/CONTRIBUTING.md+++ b/.github/CONTRIBUTING.md@@ -112,10 +112,11 @@ Which command after which change:| What changed | What to run ||---|---|| Ruby code in `spree/*` gems | Nothing — gems are bind-mounted; code reloads on the next request |-| A new migration in a gem | `cd server && pnpm exec spree migrate` |-| Gem dependencies (gemspec / Gemfile) | `cd server && pnpm exec spree bundle install` (persists in the `bundle_cache` volume) |+| A new migration in a gem | Nothing — the next `pnpm server:dev` boot applies it (or `cd server && pnpm exec spree migrate` while the stack runs) |+| Gem dependencies (gemspec / Gemfile / lock drift after `git pull`) | Nothing — the next `pnpm server:dev` boot self-heals via `bundle check || bundle install` (or `cd server && pnpm exec spree bundle install` while the stack runs) || Compose files / `server/.env` | `pnpm server:dev` (force-recreates the containers) |-| `server/Dockerfile` / `.ruby-version` | `pnpm server:build`, then `pnpm server:dev` |+| `server/Dockerfile` / `.ruby-version` / starter update that breaks the image build ("lockfile can't be updated because frozen") | `pnpm server:build`, then `pnpm server:dev` — the build script handles the edge-rewritten `Gemfile.lock` automatically |+| Meilisearch image bump ("database version … is incompatible") | Remove the `server_meilisearch_data` volume, boot, then reindex (`pnpm exec spree rake spree:search:reindex`) — the index is derived data || Broken beyond repair | `pnpm server:setup` (full reset — wipes the database and volumes) |Re-run `pnpm server:setup` **only** to fully reset — it does `docker compose down -v` + `rm -rf ./server`, wiping all DB data.diff --git a/CLAUDE.md b/CLAUDE.mdindex 75b2a00d4a..0843f83257 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -81,10 +81,11 @@ Day-to-day from the repo root: `pnpm server:dev` (foreground — streams web + w| What changed | What to run ||---|---|| Ruby code in `spree/*` gems | Nothing — bind-mounted, reloads on next request |-| New migration in a gem | `cd server && pnpm exec spree migrate` |-| Gem dependencies (gemspec / Gemfile) | `cd server && pnpm exec spree bundle install` (persists in the `bundle_cache` volume) |+| New migration in a gem | Nothing — the next `pnpm server:dev` boot runs `spree:install:migrations db:prepare` (or `cd server && pnpm exec spree migrate` while running) |+| Gem dependencies (gemspec / Gemfile / starter `Gemfile.lock` drift after a pull) | Nothing — the next `pnpm server:dev` boot self-heals (`bundle check || bundle install` into the `bundle_cache` volume); while running: `cd server && pnpm exec spree bundle install` || Compose files / `server/.env` | `pnpm server:dev` (force-recreates web + worker) |-| `server/Dockerfile` / `.ruby-version` | `pnpm server:build`, then `pnpm server:dev` |+| `server/Dockerfile` / `.ruby-version` / starter update that breaks the image build (frozen-lockfile error) | `pnpm server:build`, then `pnpm server:dev` — the build script swaps the edge PATH lock for a RubyGems-resolved one and the next boot swaps it back |+| Meilisearch image bump ("database version … is incompatible") | `docker compose -p server rm -sf meilisearch && docker volume rm server_meilisearch_data`, boot, then `cd server && pnpm exec spree rake spree:search:reindex` || Broken beyond repair | `pnpm server:setup` (full reset — wipes DB + volumes) |Backend: http://localhost:3000, admin at `/admin` (`[email protected]` / `spree123`). Native no-Docker path: `pnpm server:create`, then `cd server && bin/setup && bin/dev`.diff --git a/docs/developer/contributing/developing-spree.mdx b/docs/developer/contributing/developing-spree.mdxindex 6c06a141f5..abe3484eb5 100644--- a/docs/developer/contributing/developing-spree.mdx+++ b/docs/developer/contributing/developing-spree.mdx@@ -78,10 +78,11 @@ Which command after which change:| What changed | What to run ||---|---|| Ruby code in `spree/*` gems | Nothing — gems are bind-mounted; code reloads on the next request |-| A new migration in a gem | `cd server && pnpm exec spree migrate` |-| Gem dependencies (gemspec / Gemfile) | `cd server && pnpm exec spree bundle install` (persists in the `bundle_cache` volume) |+| A new migration in a gem | Nothing — the next `pnpm server:dev` boot applies it (or `cd server && pnpm exec spree migrate` while the stack runs) |+| Gem dependencies (gemspec / Gemfile / lock drift after `git pull`) | Nothing — the next `pnpm server:dev` boot self-heals via `bundle check || bundle install` (or `cd server && pnpm exec spree bundle install` while the stack runs) || Compose files / `server/.env` | `pnpm server:dev` (force-recreates the containers) |-| `server/Dockerfile` / `.ruby-version` | `pnpm server:build`, then `pnpm server:dev` |+| `server/Dockerfile` / `.ruby-version` / starter update that breaks the image build ("lockfile can't be updated because frozen") | `pnpm server:build`, then `pnpm server:dev` — the build script handles the edge-rewritten `Gemfile.lock` automatically |+| Meilisearch image bump ("database version … is incompatible") | Remove the `server_meilisearch_data` volume, boot, then reindex (`pnpm exec spree rake spree:search:reindex`) — the index is derived data || Broken beyond repair | `pnpm server:setup` (full reset — wipes the database and volumes) |Re-run `pnpm server:setup` **only** to fully reset — it does `docker compose down -v` + `rm -rf ./server`, wiping all DB data.diff --git a/package.json b/package.jsonindex de224570f0..a4c320c25c 100644--- a/package.json+++ b/package.json@@ -14,7 +14,7 @@"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:dev": "SPREE_PATH=$PWD docker compose -f server/docker-compose.dev.yml -f scripts/docker-compose.edge.yml up --force-recreate web worker",- "server:build": "SPREE_PATH=$PWD docker compose -f server/docker-compose.dev.yml -f scripts/docker-compose.edge.yml build web worker",+ "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: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",diff --git a/packages/cli/.changeset/cli-dev-foreground-and-resilience.md b/packages/cli/.changeset/cli-dev-foreground-and-resilience.mdnew file mode 100644index 0000000000..9f47b36e2e--- /dev/null+++ b/packages/cli/.changeset/cli-dev-foreground-and-resilience.md@@ -0,0 +1,15 @@+---+"@spree/cli": minor+---++`spree dev` now runs the app in the foreground like every other dev server (`vite dev`, `bin/dev`): it streams web + worker logs and `Ctrl+C` stops them, while the database containers keep running for a fast next boot — `spree stop` remains the full shutdown. Previously `Ctrl+C` only detached from the logs and left everything running. Real compose failures (daemon down, port conflict, bad config) now exit with the underlying code instead of printing a clean shutdown message; a `Ctrl+C` stop still ends cleanly.++Add `spree restart` — restarts `web` + `worker` in place (same image, same volumes, fresh Rails process). For `config/initializers` changes and anything Zeitwerk doesn't reload; it does not pick up Gemfile or compose changes.++`spree bundle` now works when the stack is down: if the `web` container isn't running — for example after a `Gemfile.lock` change crash-loops the boot, which is exactly when bundler is needed — it runs bundler in a one-off container against the same `bundle_cache` volume instead of failing on `exec`.++`spree dev` and `spree build` detect monorepo edge projects (`SPREE_PATH` in `.env`) and refuse with a pointer to the matching `pnpm server:*` script, instead of materializing the wrong compose config against the running edge stack.++`spree migrate` prints a header for each step and a completion note — previously a fully up-to-date run produced no output at all, leaving no signal that anything ran.++`spree upgrade`'s closing "Next steps" panel now includes the SDK side of the upgrade: when the project has the conventional `apps/storefront` consuming `@spree/sdk`, it names the currently-declared version and reminds you to bump it to the release matching the new Spree version.diff --git a/packages/cli/src/commands/bundle.ts b/packages/cli/src/commands/bundle.tsindex 2cce6e190a..6bc3568391 100644--- a/packages/cli/src/commands/bundle.ts+++ b/packages/cli/src/commands/bundle.ts@@ -1,6 +1,8 @@+import * as p from '@clack/prompts'import type { Command } from 'commander'-import { detectProject } from '../context.js'-import { dockerComposeExec } from '../docker.js'+import pc from 'picocolors'+import { detectProject, hasMonorepoSpreePath } from '../context.js'+import { dockerCompose, dockerComposeExec, isServiceRunning } from '../docker.js'// Run bundler inside the web container. Gems install into the bundle_cache// volume and persist across container restarts without an image rebuild.@@ -16,6 +18,31 @@ export function registerBundleCommand(program: Command): void {.passThroughOptions(true).action(async (args: string[]) => {const ctx = detectProject()- await dockerComposeExec(['bundle', ...args], ctx.projectDir)++ if (await isServiceRunning('web', ctx.projectDir)) {+ await dockerComposeExec(['bundle', ...args], ctx.projectDir)+ return+ }++ // Gemfile.lock drift crashes the containers before `exec` can reach+ // them — exactly the state where bundler is needed most. A one-off+ // `compose run` container mounts the same bundle_cache volume, so+ // gems land where the next boot expects them.+ if (hasMonorepoSpreePath(ctx.projectDir)) {+ p.cancel(+ [+ 'The web container is not running, and this is a monorepo edge project.',+ `Run ${pc.bold('pnpm server:dev')} from the monorepo root — the edge stack heals gem drift on boot.`,+ ].join('\n'),+ )+ process.exit(1)+ }++ p.log.info(+ 'web container is not running — using a one-off container (`docker compose run`) instead.',+ )+ await dockerCompose(['run', '--rm', 'web', 'bundle', ...args], ctx.projectDir, {+ stdio: 'inherit',+ })})}diff --git a/packages/cli/src/docker.ts b/packages/cli/src/docker.tsindex f4a2f21e53..4de670e612 100644--- a/packages/cli/src/docker.ts+++ b/packages/cli/src/docker.ts@@ -32,6 +32,19 @@ export async function rakeTask(.trim()}+// Whether a compose service has a running container — used by commands that+// can fall back to `compose run` when the stack is down. A defined service+// with no containers exits 0 with empty output (the legitimate false case);+// anything that makes `compose ps` itself fail — daemon down, broken compose+// file, unknown service — throws, so the caller surfaces the real error+// instead of acting on a wrong "stopped" answer.+export async function isServiceRunning(service: string, projectDir: string): Promise<boolean> {+ const { stdout } = await execa('docker', ['compose', 'ps', service, '--format', '{{.State}}'], {+ cwd: projectDir,+ })+ return stdout.split('\n').some((line) => line.trim() === 'running')+}+export interface DockerComposeExecOptions {service?: stringtty?: booleandiff --git a/scripts/docker-compose.edge.yml b/scripts/docker-compose.edge.ymlindex f4f83e6102..48d43f4035 100644--- a/scripts/docker-compose.edge.yml+++ b/scripts/docker-compose.edge.yml@@ -30,8 +30,19 @@ services:# Hard-bypass the starter's bin/docker-entrypoint, which auto-runs# `db:prepare` when the command is `bin/rails server`. The dev compose# claims to bypass it but doesn't actually set entrypoint: [], so we- # do it here. server:setup runs DB prep explicitly via the CLI.+ # do it here.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+ # 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.+ command:+ [+ "sh", "-c",+ "(bundle check || bundle install) && bin/rails spree:install:migrations db:prepare && exec bin/rails server -b 0.0.0.0 -p 3000"+ ]worker:environment:@@ -39,3 +50,17 @@ services: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-build.sh b/scripts/server-build.shnew file mode 100755index 0000000000..7877d0f080--- /dev/null+++ b/scripts/server-build.sh@@ -0,0 +1,35 @@+#!/usr/bin/env bash+# server-build.sh — rebuild the edge dev image (`pnpm server:build`).+#+# The edge flow rewrites server/Gemfile.lock with a PATH block pointing at+# the host monorepo (an absolute path like /Users/you/spree/spree). The+# Docker image build copies that lock into a context where SPREE_PATH is+# unset and bundler runs in frozen mode — so the build fails with+# "The list of sources changed, but the lockfile can't be updated".+#+# Fix: when the PATH block is present, regenerate a RubyGems-resolved lock+# (bundle lock in a throwaway ruby container, no .env so the Gemfile's+# SPREE_PATH branch stays inactive) and build with that. The next+# `pnpm server:dev` boot self-heals the bundle and rewrites the PATH lock.++set -euo pipefail++ROOT="$(cd "$(dirname "$0")/.." && pwd)"+cd "$ROOT"++LOCK="server/Gemfile.lock"++if grep -q "remote: $ROOT/spree" "$LOCK" 2>/dev/null; then+ RUBY_VERSION="$(cat server/.ruby-version)"+ echo "→ Edge PATH block detected in $LOCK"+ echo "→ Regenerating a RubyGems-resolved lock for the image build (ruby:${RUBY_VERSION}-slim)"+ TMP="$(mktemp -d)"+ trap 'rm -rf "$TMP"' EXIT+ cp server/Gemfile server/.ruby-version "$TMP/"+ docker run --rm -v "$TMP":/rails -w /rails "ruby:${RUBY_VERSION}-slim" bundle lock+ cp "$TMP/Gemfile.lock" "$LOCK"+ echo "→ Lock regenerated. (The next \`pnpm server:dev\` boot restores the monorepo PATH lock automatically.)"+fi++echo "→ Building web + worker"+SPREE_PATH="$ROOT" docker compose -f server/docker-compose.dev.yml -f scripts/docker-compose.edge.yml build web workerdiff --git a/scripts/server-setup.sh b/scripts/server-setup.shindex e50eaf7f4e..ca1b4fbe99 100755--- a/scripts/server-setup.sh+++ b/scripts/server-setup.sh@@ -11,14 +11,15 @@# 3. Clone spree-starter into server/# 4. Write server/.env with SPREE_PATH=.. (for the native bin/dev path —# Docker edge flow overrides via compose env) + a fresh SECRET_KEY_BASE-# 5. Build @spree/cli so node ../packages/cli/dist/index.js works-# 6. Start the edge stack-# 7. Wait until web container is `running` (not `healthy` — healthcheck-# polls /up which 500s without a DB)-# 8. CLI: bundle install (rewrites Gemfile.lock to use path-based gems)-# 9. CLI: rake spree:install:migrations (copies migrations from edge gems-# into server/db/migrate/)-# 10. CLI: rails db:prepare (create + migrate + seed)+# 5. Build @spree/cli so `pnpm exec spree …` works in server/+# 6. Start the edge stack and wait for it to finish booting. The edge web+# boot command (scripts/docker-compose.edge.yml) does the heavy lifting+# itself — bundle install against the monorepo gems (rewrites+# Gemfile.lock with the PATH block), spree:install:migrations, and+# db:prepare (create + migrate + seed) — so this script must NOT run+# those steps too: a second bundle install / db:prepare racing the+# boot's own can corrupt the bundle_cache volume or trip over a+# half-prepared database. We just wait until the web server answers.## Idempotent: re-running this from any state should converge. The volume# nuke in step 1 is what makes it idempotent in the face of partially-failed@@ -62,31 +63,27 @@ step "Starting the edge stack"# (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-step "Waiting for web container to come up"-WAIT_TIMEOUT=120+step "Waiting for the stack to finish booting"+# The edge web boot runs bundle install + spree:install:migrations ++# db:prepare before starting Puma (see scripts/docker-compose.edge.yml), so+# "web answers HTTP" means the whole bootstrap is done. First boot installs+# the monorepo spree gems into the bundle_cache volume — give it minutes,+# not seconds. Do NOT add exec-based setup steps here; they would race the+# boot's own sequence.+WAIT_TIMEOUT=600elapsed=0-until docker compose -f "$DEV_COMPOSE" ps web --format '{{.State}}' | grep -q running; do+until code="$(curl -s -o /dev/null -w '%{http_code}' --max-time 2 http://localhost:3000/ 2>/dev/null)" && [ "$code" -ge 200 ] && [ "$code" -lt 400 ]; doif [ "$elapsed" -ge "$WAIT_TIMEOUT" ]; then- echo "✗ web container did not reach 'running' within ${WAIT_TIMEOUT}s." >&2+ echo "✗ web did not respond within ${WAIT_TIMEOUT}s." >&2echo " Inspect with: docker compose -f $DEV_COMPOSE logs web" >&2exit 1fi- sleep 1- elapsed=$((elapsed + 1))+ if [ "$elapsed" -gt 0 ] && [ $((elapsed % 30)) -eq 0 ]; then+ echo " …still booting (${elapsed}s) — gems + migrations + seeds run on first boot."+ echo " Follow along: docker compose -f $DEV_COMPOSE logs -f web"+ fi+ sleep 3+ elapsed=$((elapsed + 3))done-# Even when running, Rails takes a few seconds to be ready to accept exec.-# A quick warmup avoids the first `docker compose exec` racing the boot.-sleep 5--step "bundle install (rewrites Gemfile.lock against monorepo gems)"-cd "$SERVER_DIR"-SPREE_CLI="$ROOT/packages/cli/dist/index.js"-node "$SPREE_CLI" bundle install--step "spree:install:migrations (copies edge migrations into server/db/migrate/)"-node "$SPREE_CLI" rake spree:install:migrations--step "db:prepare (create + migrate + seed)"-node "$SPREE_CLI" rails db:prepareprintf '\nServer ready: http://localhost:3000\nAdmin: http://localhost:3000/admin\n\n'