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
Added Claude Code cloud environment setup (#14943)
Damian Legawiec92e27a3adf0a
diff --git a/.claude/settings.json b/.claude/settings.jsonindex 13167a9963..d29f3c0177 100644--- a/.claude/settings.json+++ b/.claude/settings.json@@ -1,6 +1,18 @@{"$schema": "https://json.schemastore.org/claude-code-settings.json","hooks": {+ "SessionStart": [+ {+ "matcher": "startup|resume",+ "hooks": [+ {+ "type": "command",+ "command": "[ \"$CLAUDE_CODE_REMOTE\" = true ] || exit 0; exec \"$CLAUDE_PROJECT_DIR/scripts/cloud/provision.sh\"",+ "timeout": 1200+ }+ ]+ }+ ],"PostToolUse": [{"matcher": "Write|Edit|MultiEdit",diff --git a/CLAUDE.md b/CLAUDE.mdindex 84ff557a13..5abd4c28b1 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -81,6 +81,8 @@ One-time machine setup: Homebrew `postgresql@18` running on :5432 (with a `postg| Broken beyond repair | `wt remove` and recreate — or `dropdb spree_dev_<branch>`, delete `server/`, re-run `pnpm wt:setup` |When working with worktrees, don't use the `pnpm server:dev` and other docker-based commands.++**Cloud sessions** (`CLAUDE_CODE_REMOTE=true`) have no worktrees, portless or Homebrew. The SessionStart hook (`scripts/cloud/provision.sh`) has already started Postgres and Mailpit, cloned `server/`, and created and seeded `spree_development` — its summary at the top of the session lists the URLs. Start servers with `scripts/cloud/start.sh [rails|dashboard|seller|all]` (plain http: Rails :3000, dashboard :5173, seller :5175, logs in `/tmp/spree-*.log`); `pnpm wt:dev`/`wt:dashboard`/`wt:seller` do not work there. Check UI changes yourself with `node scripts/cloud/screenshot.mjs <url> <out.png> --login` and Read the PNG — the human cannot open these servers. `pnpm test:rspec`, `pnpm test:changed` and `pnpm wt:e2e` work unchanged.NEVER kill/shut off dev serves already running unless they are broken (eg. migrations didn't run, missing migrations).---diff --git a/docs/developer/contributing/developing-spree.mdx b/docs/developer/contributing/developing-spree.mdxindex b12b594c04..822d2c2ebb 100644--- a/docs/developer/contributing/developing-spree.mdx+++ b/docs/developer/contributing/developing-spree.mdx@@ -438,6 +438,31 @@ The MCP server URL for quick setup:https://spreecommerce.org/docs/mcp```+### Claude Code cloud sessions++Cloud sessions (claude.ai/code, or **Cloud** in the Claude desktop app) run the agent on a remote Linux machine. The repository is set up so the agent there can run the backend, the admin dashboard and the seller panel, and check its work in a headless browser.++Create the cloud environment once, then share it with your organization if others need it:++1. Open the environment settings from the environment selector under the message box.+2. **Setup script**: paste the contents of [`scripts/cloud/environment-setup.sh`](https://github.com/spree/spree/blob/main/scripts/cloud/environment-setup.sh). It installs Ruby, pnpm, Mailpit and Chromium, and the result is saved for later sessions.+3. **Network access**: choose **Custom**, keep the default allowed domains, and add `cdn.playwright.dev` and `playwright.download.prss.microsoft.com` so the browser can be downloaded.+4. **Environment variables**:++ ```bash+ PLAYWRIGHT_BROWSERS_PATH=/opt/ms-playwright+ BASH_DEFAULT_TIMEOUT_MS=300000+ BASH_MAX_TIMEOUT_MS=1200000+ ```++When a session starts, a hook clones the starter app, installs dependencies, and creates and seeds the database. The first session takes a few minutes. The agent then starts the servers with `scripts/cloud/start.sh` and looks at pages with `scripts/cloud/screenshot.mjs`.++<Note>+The servers run on the remote machine, so you cannot open them in your own browser. The agent checks the pages itself, and the Playwright suite (`pnpm wt:e2e`) runs there as it does on a laptop.+</Note>++When the starter moves to a new Ruby version, update `RUBY_VERSION` in `scripts/cloud/environment-setup.sh` and paste the script into the environment again.+## That's a wrap!Thank you for participating in Open Source and improving Spree - you're awesome!diff --git a/scripts/cloud/environment-setup.sh b/scripts/cloud/environment-setup.shnew file mode 100755index 0000000000..bc133cdc08--- /dev/null+++ b/scripts/cloud/environment-setup.sh@@ -0,0 +1,51 @@+#!/usr/bin/env bash+# Setup script for the Claude Code cloud environment (claude.ai/code and the+# desktop app's Cloud sessions). Paste it into the environment's "Setup script"+# field — see "Claude Code cloud sessions" in+# docs/developer/contributing/developing-spree.mdx.+#+# Runs as root on Ubuntu before the session starts. Anthropic snapshots the+# filesystem when it finishes within about five minutes, so this installs only+# machine-level tools (no gems, node modules or database — the session start+# hook in scripts/cloud/provision.sh owns those, because they follow the branch).+set -euo pipefail++RUBY_VERSION=4.0.5+RV_RUBY_RELEASE=20260929+PNPM_VERSION=11.1.1+PLAYWRIGHT_VERSION=1.64.1++export DEBIAN_FRONTEND=noninteractive+apt-get update -qq+apt-get install -y -qq --no-install-recommends libvips42t64 libpq-dev libyaml-dev lsof >/dev/null++# Precompiled, relocatable Ruby: building 4.0.x from source alone would use+# most of the five-minute snapshot budget, and the image ships only 3.1-3.3.+if [ ! -x "/opt/rubies/$RUBY_VERSION/bin/ruby" ]; then+ mkdir -p /opt/rubies+ curl -fsSL "https://github.com/spinel-coop/rv-ruby/releases/download/$RV_RUBY_RELEASE/ruby-$RUBY_VERSION.x86_64_linux.tar.gz" \+ | tar xz -C /opt/rubies --strip-components=1+fi+chmod -R a+rwX /opt/rubies++npm install -g --silent "pnpm@$PNPM_VERSION"++# Catches every email the app sends, as it does on the laptop.+if ! command -v mailpit >/dev/null; then+ curl -fsSL https://github.com/axllent/mailpit/releases/latest/download/mailpit-linux-amd64.tar.gz \+ | tar xz -C /usr/local/bin mailpit+fi++# Local throwaway database: trust loopback connections so the starter's+# database.yml (no password) connects as postgres.+for hba in /etc/postgresql/*/main/pg_hba.conf; do+ sed -i -E 's/^(host[[:space:]]+all[[:space:]]+all[[:space:]]+(127\.0\.0\.1\/32|::1\/128)[[:space:]]+)[^[:space:]]+/\1trust/' "$hba"+done++# Version pinned to the dashboard's lockfile. Needs cdn.playwright.dev and+# playwright.download.prss.microsoft.com on the allowed hosts; without them the+# environment still starts, but the browser is missing.+export PLAYWRIGHT_BROWSERS_PATH=/opt/ms-playwright+npx -y "playwright@$PLAYWRIGHT_VERSION" install --with-deps chromium \+ || echo "! Chromium download failed — add the Playwright hosts to the environment's allowed domains"+chmod -R a+rX /opt/ms-playwright 2>/dev/null || truediff --git a/scripts/cloud/provision.sh b/scripts/cloud/provision.shnew file mode 100755index 0000000000..12f80d9028--- /dev/null+++ b/scripts/cloud/provision.sh@@ -0,0 +1,104 @@+#!/usr/bin/env bash+# Prepare a Claude Code cloud session: start Postgres and Mailpit, clone the+# starter into server/, install gems and node modules, and create + seed the+# database on first boot. Runs from the SessionStart hook on every start and+# resume (a paused VM loses its processes, not its files), so every step is+# idempotent and cheap the second time. Only stdout reaches the agent, so the+# steps log to $LOG and the summary at the end is what it reads.+#+# Cloud only — on a laptop use the worktree scripts (scripts/worktree/).+set -euo pipefail+cd "${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel)}"++LOG=/tmp/spree-cloud-provision.log+DATABASE_NAME=spree_development+ADMIN_PASSWORD=spree123++step() { echo "▸ $*" >>"$LOG"; }+fail() { echo "✗ Cloud provisioning failed: $* — see $LOG"; exit 1; }+as_root() { if [ "$(id -u)" = 0 ]; then "$@"; else sudo "$@"; fi; }++: >"$LOG"++step "Starting Postgres"+as_root service postgresql start >>"$LOG" 2>&1 || fail "Postgres did not start"+for _ in $(seq 1 30); do pg_isready -q -h localhost && break; sleep 1; done++if command -v mailpit >/dev/null && ! lsof -iTCP:1025 -sTCP:LISTEN >/dev/null 2>&1; then+ step "Starting Mailpit"+ nohup mailpit >/tmp/spree-mailpit.log 2>&1 &+fi++if [ ! -d server ]; then+ step "Cloning spree-starter into server/"+ git clone --quiet --depth 1 https://github.com/spree/spree-starter.git server >>"$LOG" 2>&1 || fail "could not clone spree-starter"+ rm -rf server/.git server/.gitignore+fi++ruby_version=$(cat server/.ruby-version)+ruby_bin="/opt/rubies/$ruby_version/bin"+[ -x "$ruby_bin/ruby" ] || fail "Ruby $ruby_version is not installed — bump RUBY_VERSION in scripts/cloud/environment-setup.sh and paste it into the environment's setup script"+export PATH="$ruby_bin:$PATH"++# Later Bash commands in the session read this file, so ruby/bundle resolve to+# the starter's version rather than the image's rbenv ones.+if [ -n "${CLAUDE_ENV_FILE:-}" ]; then+ {+ echo "export PATH=\"$ruby_bin:\$PATH\""+ echo "export PLAYWRIGHT_BROWSERS_PATH=\"\${PLAYWRIGHT_BROWSERS_PATH:-/opt/ms-playwright}\""+ } >>"$CLAUDE_ENV_FILE"+fi++if [ ! -f server/.env ]; then+ step "Writing server/.env"+ cat >server/.env <<EOF+SPREE_PATH=$(pwd)+SECRET_KEY_BASE=$(openssl rand -hex 64)+DATABASE_NAME=$DATABASE_NAME+DATABASE_NAME_TEST=spree_test+SPREE_DASHBOARD_URL=http://localhost:5173+SPREE_SELLER_PANEL_URL=http://localhost:5175+RAILS_HOST=localhost:3000+RAILS_PROTOCOL=http+SMTP_HOST=localhost+SMTP_PORT=1025+ACTIVE_RECORD_ENCRYPTION_PRIMARY_KEY=$(openssl rand -hex 16)+ACTIVE_RECORD_ENCRYPTION_DETERMINISTIC_KEY=$(openssl rand -hex 16)+ACTIVE_RECORD_ENCRYPTION_KEY_DERIVATION_SALT=$(openssl rand -hex 16)+EOF+fi++step "Installing gems"+(cd server && { bundle check >/dev/null 2>&1 || bundle install --quiet; }) >>"$LOG" 2>&1 || fail "bundle install"++if psql -h localhost -U postgres -lqt | cut -d'|' -f1 | tr -d ' ' | grep -qx "$DATABASE_NAME"; then+ step "Migrating $DATABASE_NAME"+ (cd server && bin/rails spree:install:migrations db:migrate) >>"$LOG" 2>&1 || fail "db:migrate"+else+ step "Creating and seeding $DATABASE_NAME (first boot, a few minutes)"+ (cd server && ADMIN_EMAIL="$ADMIN_EMAIL" ADMIN_PASSWORD="$ADMIN_PASSWORD" \+ bin/rails db:create spree:install:migrations db:migrate db:seed) >>"$LOG" 2>&1 || fail "database setup"+fi++lock_hash=$(sha1sum pnpm-lock.yaml | cut -c1-40)+if [ "$(cat node_modules/.cloud-lock-hash 2>/dev/null)" != "$lock_hash" ]; then+ step "Installing node modules"+ pnpm install --silent >>"$LOG" 2>&1 || fail "pnpm install"+ echo "$lock_hash" >node_modules/.cloud-lock-hash+fi++for app in dashboard-starter seller-dashboard-starter; do+ printf 'VITE_API_PROXY_TARGET=http://localhost:3000\n' >"packages/$app/.env.local"+done++cat <<EOF+✓ Spree cloud environment ready (Ruby $ruby_version, database $DATABASE_NAME, log $LOG)+ Start servers: scripts/cloud/start.sh [rails|dashboard|seller|all] (default: rails + dashboard)+ Rails API: http://localhost:3000 (log /tmp/spree-rails.log)+ Admin dashboard: http://localhost:5173 ($ADMIN_EMAIL / $ADMIN_PASSWORD)+ Seller panel: http://localhost:5175 (seed a seller: cd server && bin/rails spree:sellers:sample_data)+ Look at a page: node scripts/cloud/screenshot.mjs http://localhost:5173/ /tmp/page.png --login then Read the PNG+ Email: http://localhost:8025/api/v1/messages (Mailpit)+ Only you can see these servers: the person using the app has no browser preview of them.+EOFdiff --git a/scripts/cloud/screenshot.mjs b/scripts/cloud/screenshot.mjsnew file mode 100755index 0000000000..379fb94a1f--- /dev/null+++ b/scripts/cloud/screenshot.mjs@@ -0,0 +1,41 @@+#!/usr/bin/env node+// Screenshot a page from the cloud session's headless Chromium, so the agent+// can look at the dashboard it is changing (Read the PNG afterwards).+//+// node scripts/cloud/screenshot.mjs <url> [out.png] [--login] [--full]+//+// --login signs in with the seeded admin first (or SPREE_LOGIN_EMAIL /+// SPREE_LOGIN_PASSWORD, e.g. a seller on :5175). Browser console errors are+// printed, since a blank page usually explains itself there.+import { createRequire } from 'node:module'++const require = createRequire(new URL('../../packages/dashboard/package.json', import.meta.url))+const { chromium } = require('@playwright/test')++const args = process.argv.slice(2)+const [url, out = '/tmp/screenshot.png'] = args.filter((arg) => !arg.startsWith('--'))+if (!url) {+ console.error('Usage: node scripts/cloud/screenshot.mjs <url> [out.png] [--login] [--full]')+ process.exit(64)+}++const browser = await chromium.launch()+const page = await browser.newPage({ viewport: { width: 1440, height: 900 } })+page.on('console', (message) => {+ if (message.type() === 'error') console.log(`console error: ${message.text()}`)+})++try {+ if (args.includes('--login')) {+ await page.goto(new URL('/login', url).href)+ await page.getByLabel(/email/i).fill(process.env.SPREE_LOGIN_EMAIL ?? '[email protected]')+ await page.getByLabel(/password/i).fill(process.env.SPREE_LOGIN_PASSWORD ?? 'spree123')+ await page.getByRole('button', { name: /^sign in$/i }).click()+ await page.waitForURL((current) => !current.pathname.startsWith('/login'), { timeout: 15_000 })+ }+ await page.goto(url, { waitUntil: 'networkidle' })+ await page.screenshot({ path: out, fullPage: args.includes('--full') })+ console.log(`Saved ${out} (${page.url()})`)+} finally {+ await browser.close()+}diff --git a/scripts/cloud/start.sh b/scripts/cloud/start.shnew file mode 100755index 0000000000..dc24447467--- /dev/null+++ b/scripts/cloud/start.sh@@ -0,0 +1,48 @@+#!/usr/bin/env bash+# Start the cloud session's servers in the background and wait until they+# answer. Already-running servers are left alone, so it is safe to re-run.+# Usage: scripts/cloud/start.sh [rails|dashboard|seller|all ...] (default: rails dashboard)+set -euo pipefail+cd "${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel)}"+root=$(pwd)++listening() { lsof -iTCP:"$1" -sTCP:LISTEN -n -P >/dev/null 2>&1; }++wait_for() {+ local name="$1" url="$2" log="$3"+ for _ in $(seq 1 180); do+ curl -fsS -o /dev/null "$url" 2>/dev/null && { echo "✓ $name $url"; return 0; }+ sleep 1+ done+ echo "✗ $name did not answer at $url — last lines of $log:"+ tail -n 30 "$log"+ return 1+}++start_rails() {+ listening 3000 || (cd server && nohup bin/dev >/tmp/spree-rails.log 2>&1 &)+ wait_for "Rails" http://localhost:3000/up /tmp/spree-rails.log+}++# Vite ignores PORT, so build the shell's workspace deps first, then pin the port.+start_vite() {+ local name="$1" package="$2" port="$3" log="/tmp/spree-$1.log"+ if ! listening "$port"; then+ pnpm turbo build --filter="@spree/$package^..." >"$log" 2>&1+ (cd "$root/packages/$package" && nohup pnpm vite --port "$port" --strictPort >>"$log" 2>&1 &)+ fi+ wait_for "$name" "http://localhost:$port/" "$log"+}++targets=("$@")+[ ${#targets[@]} -gt 0 ] || targets=(rails dashboard)+[ "${targets[*]}" = all ] && targets=(rails dashboard seller)++for target in "${targets[@]}"; do+ case "$target" in+ rails) start_rails ;;+ dashboard) start_vite dashboard dashboard-starter 5173 ;;+ seller) start_vite seller seller-dashboard-starter 5175 ;;+ *) echo "Unknown target '$target' (rails, dashboard, seller, all)" >&2; exit 64 ;;+ esac+done