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
import * as p from '@clack/prompts'
import { type Options as ExecaOptions, execa } from 'execa'
import pc from 'picocolors'
import { backendTaskCommand, PREPARE_DATABASE } from './backend.js'
import { hasMonorepoSpreePath } from './context.js'
export async function dockerCompose(args: string[], projectDir: string, options?: ExecaOptions) {
try {
return await execa('docker', ['compose', ...args], {
cwd: projectDir,
...options,
})
} catch (error) {
throw withDockerHint(error)
}
}
// Docker's default address pools hold about 30 bridge networks, and every
// compose project keeps its `<name>_default` network after its containers
// stop — so a machine with many old projects fails to create a new one with
// a daemon message that names neither the cause nor the fix.
const ADDRESS_POOLS_EXHAUSTED = /all predefined address pools have been fully subnetted/i
function isAddressPoolExhausted(error: unknown): boolean {
return ADDRESS_POOLS_EXHAUSTED.test(error instanceof Error ? error.message : String(error))
}
function withDockerHint(error: unknown): unknown {
if (!isAddressPoolExhausted(error)) return error
const message = error instanceof Error ? error.message : String(error)
return new Error(
`${message}\n\nDocker has no free network addresses left, usually because old projects left their networks behind. ` +
`List them with ${pc.cyan('docker network ls')} and remove the ones you no longer need with ${pc.cyan('docker network rm <name>')}. ` +
`${pc.cyan('docker network prune')} removes every network on this machine that no container is using, ` +
'including networks other tools created and still expect to find.',
{ cause: error },
)
}
// web and worker share one bundle_cache named volume and, in the dev compose,
// start concurrently. On a COLD volume Docker copies the image's populated
// /usr/local/bundle into it ("copy-up") the first time a container mounts it —
// per container, with no cross-container lock. Two concurrent copy-ups race on
// mkdir of the same nested gem-extension dirs and one loses with "file exists"
// (nondeterministic, first-boot only).
//
// Fix: bring `web` up alone first and wait for it. That single container wins
// the copy-up uncontended; by the time the rest of the stack starts the volume
// is non-empty, Docker's emptiness gate is false, and no further copy-up (hence
// no race) happens. `up -d` blocks until the container is started, which is
// when the copy-up runs (during mount setup, before the entrypoint), so the
// volume is populated once this resolves. On a warm volume it's a ~1s no-op.
//
// Best-effort: a failed prime (image not built yet, daemon hiccup) is swallowed
// so the caller's real `up` builds/pulls and surfaces the genuine error — we
// remove a race, we never mask a failure. The exception is a project network
// Docker cannot create: this is the first `up`, and `spree dev`'s foreground
// `up` streams stderr uncaptured, so this is the one place its hint can show.
export async function primeBundleVolume(
projectDir: string,
options?: { stdio?: 'inherit' | 'pipe' | 'ignore' },
): Promise<void> {
const stdio = options?.stdio ?? 'inherit'
try {
await dockerCompose(['up', '-d', '--no-deps', 'web'], projectDir, {
stdin: stdio,
stdout: stdio,
stderr: stdio === 'inherit' ? ['pipe', 'inherit'] : 'pipe',
})
} catch (error) {
if (isAddressPoolExhausted(error)) throw error
}
}
export async function captureTask(
task: string,
projectDir: string,
env?: Record<string, string>,
): Promise<string> {
const stdout = await dockerComposeCapture(backendTaskCommand(task), projectDir, { env })
// Backend boot prints noise to stdout (e.g. "[Spree Events] ...") — strip it
return stdout
.split('\n')
.filter((line) => !line.startsWith('['))
.join('\n')
.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']
}
}
/**
* Restart the app services in place when web is running, so a new Puma
* process loads gems installed or updated since it booted. A stopped stack is
* left stopped.
*/
export async function restartAppServices(projectDir: string, message: string): Promise<void> {
if (!(await isServiceRunning('web', projectDir))) return
p.log.step(pc.bold(message))
await dockerCompose(['restart', ...(await appServices(projectDir))], projectDir, {
stdio: 'inherit',
})
}
/**
* Whether compose has ever created a container (any state, including exited)
* for this project.
*/
export async function hasProjectContainers(projectDir: string): Promise<boolean> {
const { stdout } = await execa('docker', ['compose', 'ps', '-a', '-q'], { cwd: projectDir })
return stdout.trim().length > 0
}
// 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')
}
// Docker Desktop, the Linux engine and the Windows named pipe each word a
// stopped daemon differently.
const DAEMON_DOWN =
/Cannot connect to the Docker daemon|failed to connect to the docker API|error during connect/i
/**
* The refusal shown when `docker compose` itself failed while probing the
* stack (see isServiceRunning). A missing or stopped Docker gets a plain
* "install/start Docker"; anything else shows Docker's own reason rather than
* execa's command line.
*
* @param error the error `compose ps` threw
* @param command the spree command to re-run, e.g. `spree upgrade`
* @return the message lines
*/
export function dockerStackProblem(error: unknown, command: string): string[] {
const { code, stderr, originalMessage, message } = error as {
code?: string
stderr?: string
originalMessage?: string
message?: string
}
if (code === 'ENOENT') {
return [
'Docker is not installed (the `docker` command was not found).',
`Install Docker Desktop (or Docker Engine), then re-run ${pc.bold(command)}.`,
]
}
const output = String(stderr || originalMessage || message || '')
if (DAEMON_DOWN.test(output)) {
return [
'Docker is not running.',
`Start Docker Desktop (or the Docker service), then re-run ${pc.bold(command)}.`,
]
}
const reason = output.split('\n').find((line) => line.trim()) ?? ''
return [
'Could not inspect the Docker stack from this directory.',
` ${pc.dim(reason.trim())}`,
'',
`Run ${pc.bold(command)} from your project root (the directory holding the`,
'.env file), and make sure Docker is running.',
]
}
export interface DockerComposeExecOptions {
service?: string
tty?: boolean
// Run the command detached (`-d`): compose starts it inside the container and
// returns immediately. The process shares the container's lifecycle — stop the
// container and it dies with it. Used for the admin Tailwind watcher.
detach?: boolean
env?: Record<string, string>
}
// Run a command inside a service container. The foundation for `spree exec`,
// `spree task`, `spree test`, and `spree console`.
//
// Defaults to the `web` service and an interactive TTY. Pass `tty: false`
// (which adds `-T`) for non-interactive callers that capture stdout — those
// should use `captureTask` above, which already does this.
//
// stdio is inherited so the command behaves transparently: a Rails console
// stays interactive, a `bundle add` prints progress, an error exits with the
// inner command's exit code.
export async function dockerComposeExec(
argv: string[],
projectDir: string,
options: DockerComposeExecOptions = {},
): Promise<void> {
const { service = 'web', tty = true, detach = false, env } = options
const args = ['compose', 'exec']
if (detach) args.push('-d')
if (!tty) args.push('-T')
if (env) {
for (const [key, value] of Object.entries(env)) {
args.push('-e', `${key}=${value}`)
}
}
args.push(service, ...argv)
await execa('docker', args, { cwd: projectDir, stdio: 'inherit' })
}
export interface DockerComposeRunOptions {
service?: string
env?: Record<string, string>
// Also buffer the child's stderr into the thrown ExecaError so the caller can
// inspect failure output. Off by default: plain `stdio: 'inherit'` is right
// for interactive sessions (a Rails console's TTY) and leaves stderr
// unbuffered. db:reset opts in because it pattern-matches the Postgres error.
captureStderr?: boolean
}
// Run a command in a one-off `compose run --rm` container — the twin of
// dockerComposeExec for when the service's long-running container is NOT up.
// Unlike `exec`, `run` builds a fresh container and (in Compose v2) starts the
// service's depends_on (postgres/mailpit), honoring their
// `condition: service_healthy` healthchecks before the command runs — so it
// works from a fully cold stack. We deliberately omit `--no-deps` (we WANT
// those deps started + health-waited) and `--service-ports` (these callers
// publish nothing, and skipping it avoids colliding with a running web's
// ports). `--rm` removes only this one-off container on exit; the deps it
// started are left warm for the next boot.
//
// stdio is inherited so the command stays transparent: an interactive console
// keeps its TTY, db:seed streams progress, and the inner exit code propagates.
// With `captureStderr`, stderr is teed to `['pipe', 'inherit']` — still printed
// live, but also buffered onto ExecaError.stderr (plain `'inherit'` would leave
// it undefined, so the caller's error inspection would see nothing).
export async function dockerComposeRun(
argv: string[],
projectDir: string,
options: DockerComposeRunOptions = {},
): Promise<void> {
const { service = 'web', env, captureStderr = false } = options
const args = ['compose', 'run', '--rm']
if (env) {
for (const [key, value] of Object.entries(env)) {
args.push('-e', `${key}=${value}`)
}
}
args.push(service, ...argv)
const stdio: ExecaOptions = captureStderr
? { stdin: 'inherit', stdout: 'inherit', stderr: ['pipe', 'inherit'] }
: { stdio: 'inherit' }
await execa('docker', args, { cwd: projectDir, ...stdio })
}
// The dev compose (an ejected project) starts `bin/rails server` directly,
// bypassing bin/docker-entrypoint and its db:prepare. Puma runs the Solid Queue
// supervisor in-process, and when the database does not exist yet the
// supervisor fails and takes Puma down with it — so on a fresh stack the web
// container exits before anything can `exec` into it. Prepare the database in
// a one-off container instead (no Puma) before the app server is brought up.
// Postgres is started and health-waited explicitly first: older dev compose
// files give web no depends_on, so `run` alone would not wait for it. Being the only container that mounts a
// cold bundle_cache volume, it also wins the copy-up uncontended, so no
// separate primeBundleVolume is needed after it. `--build` makes it use the
// current Dockerfile rather than a dev image left over from an earlier eject,
// and the `up -d` that follows reuses that image.
//
// stdio defaults to piped so a spinner caller stays clean and a failure still
// carries compose's output on the thrown error.
export async function prepareDatabase(
projectDir: string,
options?: { stdio?: 'inherit' | 'pipe' | 'ignore' },
): Promise<void> {
const stdio = options?.stdio ?? 'pipe'
await dockerCompose(['up', '-d', '--wait', 'postgres'], projectDir, { stdio })
await dockerCompose(['run', '--rm', '--build', 'web', ...PREPARE_DATABASE], projectDir, {
stdio,
})
}
export interface DockerComposeExecOrRunOptions {
service?: string
env?: Record<string, string>
// Extra line appended to the monorepo-edge refusal, after the generic
// "run pnpm server:dev from the monorepo root" sentence — lets a caller add
// command-specific context (e.g. bundle's "the edge stack heals gem drift").
edgeHint?: string
}
// The single gate every app-facing command goes through: `exec` into the
// service's running container, or fall back to a one-off `compose run` when
// it's down. A monorepo edge project (SPREE_PATH in .env) is refused, because
// `run` materializes the project-local compose, which is not the running edge
// config — there the operator must use `pnpm server:*` from the monorepo root.
async function resolveComposeMode(
projectDir: string,
options: DockerComposeExecOrRunOptions = {},
): Promise<'exec' | 'run'> {
const { service = 'web', edgeHint } = options
if (await isServiceRunning(service, projectDir)) return 'exec'
if (hasMonorepoSpreePath(projectDir)) {
p.cancel(
[
`The ${service} container is not running, and this is a monorepo edge project.`,
`Run ${pc.bold('pnpm server:dev')} from the monorepo root${edgeHint ? ` — ${edgeHint}` : ''}.`,
].join('\n'),
)
process.exit(1)
}
p.log.info(
`${service} container is not running — using a one-off container (\`docker compose run\`) instead.`,
)
return 'run'
}
// Run a command in the service's container, transparently falling back to a
// one-off `compose run` when the long-running container is down. This is the
// shared shape behind every app-facing command (`spree migrate`, `spree
// test`, `spree console`, `spree task`, …): exec into the live container if
// it's up, otherwise boot a fresh one-off against the same warm DB/volumes.
export async function dockerComposeExecOrRun(
argv: string[],
projectDir: string,
options: DockerComposeExecOrRunOptions = {},
): Promise<void> {
const { service = 'web', env } = options
if ((await resolveComposeMode(projectDir, options)) === 'exec') {
await dockerComposeExec(argv, projectDir, { service, env })
} else {
await dockerComposeRun(argv, projectDir, { service, env })
}
}
// Captured-output twin of dockerComposeExecOrRun, for callers that parse
// stdout (captureTask, `bundle list`). Non-interactive (`-T`) so a TTY never
// mangles the captured stream; compose's own progress noise goes to stderr,
// which stays off stdout and is buffered onto ExecaError for failure paths.
export async function dockerComposeCapture(
argv: string[],
projectDir: string,
options: DockerComposeExecOrRunOptions = {},
): Promise<string> {
const { service = 'web', env } = options
const mode = await resolveComposeMode(projectDir, options)
const args = ['compose', mode]
if (mode === 'run') args.push('--rm')
args.push('-T')
if (env) {
for (const [key, value] of Object.entries(env)) {
args.push('-e', `${key}=${value}`)
}
}
args.push(service, ...argv)
// `compose up -d` can recreate a container moments before this runs — a
// recovering project does exactly that — and `exec` into a container that
// is still starting fails with "not running". That is transient, but the
// error it surfaces ("Is it running? Start it with `spree dev`") sends the
// operator after a stack that IS running, so retry briefly before failing.
let lastError: unknown
for (let attempt = 0; attempt < 5; attempt++) {
try {
const { stdout } = await execa('docker', args, { cwd: projectDir })
return stdout
} catch (error) {
lastError = error
if (!isContainerNotReady(error)) throw error
await new Promise((resolve) => setTimeout(resolve, 2000))
}
}
throw lastError
}
/**
* A compose `exec` that lost the race with a starting container, as opposed
* to a command that ran and failed — only the former is worth retrying.
*/
function isContainerNotReady(error: unknown): boolean {
const message = error instanceof Error ? error.message : String(error)
return (
/is not running/i.test(message) ||
/no such container/i.test(message) ||
/container .* is restarting/i.test(message)
)
}
export async function streamLogs(service: string, projectDir: string): Promise<void> {
await execa('docker', ['compose', 'logs', '-f', service], {
cwd: projectDir,
stdio: 'inherit',
})
}