Develops, tests, and deploys Laravel applications using Spin and serversideup/php Docker images. Covers Docker Compose configuration, development environment setup, container commands, running Laravel tests (PHPUnit and Pest), SPIN_ENV selection and CI parity, parallel Compose environments, Laravel service configuration (databases, queues, Horizon, Reverb), server provisioning, and deployment workflows. Use when working with Spin, Docker Compose files, serversideup/php images, spin commands, running artisan test, configuring Laravel services in Docker, or deploying Laravel apps to production servers.
docker system prune, docker volume rm, dropping databases, removing services, or any destructive operation.docker info. If Docker is not running, tell the user to start Docker Desktop and offer to retry before continuing.spin exec <service> <cmd> when the stack is running — it reuses the live container and is near-instant. Use spin run when the stack is not running or isolated state is needed.-T as a defensive default when invoking commands from an AI agent, CI, or subprocess context. Compose auto-detects TTY in regular terminals, but that detection can misfire when wrapped, causing hangs or garbled output.Spin runs PHP inside Docker, not on the host machine. Laravel Boost's MCP server needs a bridge script (spin-mcp-wait.sh) that retries until Docker is ready and filters Docker's stdout noise to preserve the JSON-RPC stdio protocol.
The required .env configuration:
BOOST_PHP_EXECUTABLE_PATH="./vendor/bin/spin-mcp-wait.sh ./vendor/bin/spin run -T php php"
BOOST_COMPOSER_EXECUTABLE_PATH="./vendor/bin/spin run php composer"
BOOST_NPM_EXECUTABLE_PATH="./vendor/bin/spin run node npm"
NEVER use spin-mcp-wait.sh to run commands. It is exclusively for MCP server startup. The script will refuse non-MCP invocations with this error:
Error: spin-mcp-wait.sh is only for starting the MCP server. Use 'spin' directly instead.
If that error appears, drop spin-mcp-wait.sh and invoke spin directly:
./vendor/bin/spin exec -T php php artisan test # Correct
./vendor/bin/spin run -T php php artisan migrate # Correct
./vendor/bin/spin-mcp-wait.sh ./vendor/bin/spin run php # WRONG — never do this
Spin wraps Docker Compose and follows its syntax exactly. Any Docker Compose option works with Spin.
The core pattern is Docker Compose overrides: a base docker-compose.yml is merged with an environment-specific override file. Spin sets COMPOSE_FILE=docker-compose.yml:docker-compose.$SPIN_ENV.yml automatically.
SPIN_ENV defaults to dev, so spin up is equivalent to:
COMPOSE_FILE=docker-compose.yml:docker-compose.dev.yml docker compose up
Override with SPIN_ENV=testing spin up to use docker-compose.testing.yml instead.
The base file defines shared service structure. Override files add environment-specific settings. Docker merges them intelligently — override values replace or extend base values:
# docker-compose.yml (base — shared across all environments)