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.

Added Claude Code cloud environment setup (#14943)

Damian Legawiec92e27a3adf0a
diff --git a/.claude/settings.json b/.claude/settings.json
index 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.md
index 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.mdx
index 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.sh
new file mode 100755
index 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 || true
diff --git a/scripts/cloud/provision.sh b/scripts/cloud/provision.sh
new file mode 100755
index 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.
+EOF
diff --git a/scripts/cloud/screenshot.mjs b/scripts/cloud/screenshot.mjs
new file mode 100755
index 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.sh
new file mode 100755
index 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