Skip to content

armgit / spree

Public Imported from GitHub
0

Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.

`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.json
index 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.md
index 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.md
index 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.mdx
index 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.json
index 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.md
new file mode 100644
index 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.ts
index 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.ts
index 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?: string
tty?: boolean
diff --git a/scripts/docker-compose.edge.yml b/scripts/docker-compose.edge.yml
index 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.sh
new file mode 100755
index 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 worker
diff --git a/scripts/server-setup.sh b/scripts/server-setup.sh
index 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=600
elapsed=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 ]; do
if [ "$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." >&2
echo " Inspect with: docker compose -f $DEV_COMPOSE logs web" >&2
exit 1
fi
- 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:prepare
printf '\nServer ready: http://localhost:3000\nAdmin: http://localhost:3000/admin\n\n'