php-ship / ship
Framework-agnostic, cross-platform Docker development environment for PHP — no WSL required.
Requires
- php: ^8.2
- symfony/console: ^7.4 || ^8.0
- symfony/filesystem: ^7.0 || ^8.0
- symfony/process: ^7.0 || ^8.0
- symfony/yaml: ^7.0 || ^8.0
Requires (Dev)
- friendsofphp/php-cs-fixer: ^3.75
- phpstan/phpstan: ^2.0
- phpstan/phpstan-strict-rules: ^2.0
- phpunit/phpunit: ^11.0
Suggests
- laravel/prompts: Enables arrow-key selection in `ship init`. Not required -- falls back to a numbered prompt without it. Already present via laravel/framework in any Laravel >=11 project, so this is 'free' for the common case; deliberately not a hard require since laravel/prompts conflicts with laravel/framework 10.17-10.24.
Provides
None
Conflicts
None
Replaces
None
README
A framework-agnostic, cross-platform Docker development environment for PHP — inspired by Laravel Sail, but usable outside Laravel and without requiring Windows users to put their project inside WSL.
Status: production-ready. init/up/down/exec/shell/logs/
db/composer/npm/yarn/pnpm/package-manager/artisan/console/tempest all work end-to-end, verified
against a real Docker daemon in both dev and production mode — including
a real production HTTP request, a real database, and a real crashed-
container recovery. CI passes on every push, across Ubuntu/macOS/Windows
x PHP 8.2 to 8.5, plus a separate job that runs the same dev/production
verification against a real Docker daemon on every commit.
Contents
- Why not just use Sail?
- Requirements
- Quick start
- Commands
- Services
- Databases · Cache · Search · Object storage · Mail · Message broker · WebSockets · Application runtime · Browser testing · Frontend
- Configuration (
ship.json) - Production releases
- HTTPS / TLS
- Backing up data volumes
- Frontend dev server (Vite HMR)
- File ownership in dev (why containers run as root)
- Xdebug (off by default)
- Faster file sync on Windows/macOS (Mutagen)
- Running more than one project at once
- Customizing the stack
- Extending ship
- Architecture
- Contributing
- License
Why not just use Sail?
Laravel Sail is a good starting point for a Laravel app. ship covers the same ground and goes further, on every axis below. Every claim about Sail here comes from its own documentation or repository.
It runs anywhere PHP runs, for any framework.
- Sail is a bash script, so on Windows it's supported only through WSL2.
ship's CLI is PHP (Symfony Console + Process):
ship upand every other command run natively on Windows, macOS and Linux, and your project stays wherever you keep it. Docker Desktop still uses WSL2 under the hood to run Linux containers; only that part is unavoidable. - Sail is Laravel's (
php artisan sail:install). ship knows nothing about any framework in its core: Laravel, Symfony and Tempest areFrameworkAdapters (ship artisan,ship console,ship tempest), and any other framework can plug in the same way.
Development runs almost the same stack production runs.
- Sail serves the app with
php artisan serve, PHP's built-in development server. ship runs nginx + php-fpm, or the Octane server you pick (Swoole, RoadRunner or FrankenPHP), in development and production alike, so you find problems before production does. processes(queue workers, Horizon, the scheduler),deployCommands(migrations) and the framework's boot-time optimize step are part of the sameship.json, not something you reassemble for production.- "Almost":
processesrun only in production. In development you start the ones you need yourself (seeprocesses), since a long-running worker would keep running old code after every edit. Everything else is the same stack.
It takes you to production. Sail is a development environment;
deploying is left to you. ship release --tag builds production images (no
bind mount, assets built) and writes one portable folder: the images, a
final compose file with every third-party image pinned by digest, a deploy
script and the exact deploy steps. A server needs nothing but Docker. The
folder is a documented contract (ship-release),
so deployment tools can read it: release.json names the services and
their roles, which receive HTTP and their health paths, the data volumes and
the settings, never their values. Releases are atomic, never overwrite a
tag silently, and refuse to build without the credentials production needs.
It's secure by default.
- Sail publishes MySQL, Postgres and Redis on every network interface, so
anyone on your network can reach them with whatever password
.envholds. ship publishes no database port at all (ship dbopens the client shell inside the container), and every development port it does publish binds127.0.0.1only. In production nothing is published unless you ask. - Sail's MySQL root password is the app's
DB_PASSWORD, and its MongoDB has authentication off by default. ship's MySQL, MariaDB, MongoDB and SQL Server keep a separate root secret the app never receives, the app's own user only owns its database (MongoDB, SQL Server), and MongoDB, SQL Server and Elasticsearch always require authentication. - Sail still offers PHP 8.0 and 8.1, which no longer get security fixes. ship refuses end-of-life branches and any patch release below its PHP security floor (currently the October 2026 RCE fixes), checked again inside the image at build time.
- Production credentials are required, not defaulted: a release can't start with a password everyone's development setup shares.
More services, and more than one of each. ship init picks one option
per group, and additionalServices adds named second instances (a second
database, a second Redis) with their own env var prefix:
- Databases: Postgres, MySQL, MariaDB, MongoDB, SQL Server.
- Runtimes: php-fpm with nginx, or Octane with Swoole, RoadRunner or FrankenPHP.
- Object storage: Garage, SeaweedFS, RustFS, Silo.
- Cache: Redis, Valkey, Memcached. Search: Meilisearch, Elasticsearch, Typesense. Mail: Mailpit.
- Real-time: Reverb, or Centrifugo for any framework (with an opt-in Redis engine to run several servers as one). Queues: RabbitMQ.
- Browser testing: Dusk, Playwright or Cypress, each in its own container, given the app's internal address.
Selecting a service also wires its PHP extensions into the image (MongoDB's
mongodb, Memcached's memcached, SQL Server's pdo_sqlsrv with
Microsoft's ODBC driver), and every
image tag is pinned and kept current by Renovate.
It tells you what's wrong. ship up waits for every healthcheck and
checks that every port really bound. ship doctor shows each container's
state and health with a recovery hint, and ship config:test checks
ship.json, both compose files and the production settings without
starting anything.
It works on real machines and real teams.
- Several projects at once: every project has its own Compose name and
volumes, every port has an override, and
serviceNamesplusexternalNetworklet projects share a Docker network (or a reverse proxy) without name clashes. - Files you own on Linux:
hostUserruns the development container as your own UID/GID, so nothing it writes ends up owned by root. - Fast file sync on Windows and macOS:
SHIP_MUTAGEN=1replaces the slow bind mount with a Mutagen sync. - Extend it without forking: a
docker-compose.override.ymllayers on top of what ship generates, and a Composer package can add its own services or framework adapter throughship.json'sextensions.
Sail still has a few things ship doesn't: sail share (a public URL
through Expose), a devcontainer setup, and a Mailtrap Local service.
Requirements
- PHP 8.2+ and Composer, to install and run
shipitself. - Docker Desktop (or another Docker Engine + Compose v2 setup) — this is
what actually runs your project;
shipjust drivesdocker compose. - A
composer.jsonin your project root. Nothing else — no framework required, no PHP extensions, no local database or Node install.
Quick start
composer require --dev php-ship/ship vendor/bin/ship init # pick your services interactively vendor/bin/ship up # build and start vendor/bin/ship artisan migrate # if artisan is detected at the project root vendor/bin/ship composer require some/package vendor/bin/ship shell # drop into the app container vendor/bin/ship down
ship init asks, in order:
- the project's name, which names its containers, images and data volumes (a release needs it; keep it once deployed);
- which kinds of service it needs (a checklist), then which service for each (each menu ends with None, for a kind you ticked and then decided against, such as an Octane runtime when PHP-FPM will do), and any second instances (a second database, say);
- which processes run beside the app in production: a checklist of what
the framework suggests from what the project uses (Horizon or a queue
worker and the scheduler for Laravel, plus Reverb when
laravel/reverbis installed and ship's own Reverb service isn't chosen — see Reverb: a service or a process?; Messenger workers for the transportsmessenger.yamlconfigures and Scheduler's schedules for Symfony; the scheduler and the async command worker for Tempest), then processes of your own: a name, a command, and an optional health check command (seeprocesses); - which PHP extensions the image needs beyond what's added anyway: it first says what that is and why (what every image has, what your Composer packages declare, what the chosen services need), then takes the rest, comma-separated, starting from what ship.json lists;
- the external networks a reverse proxy shares with the app, comma-separated (the hint lists the ones on this machine);
- the PHP and Node.js versions and the JavaScript package manager,
and ends with a summary. It then adds the settings your choices use to the project's env files, where they're missing:
.env.exampleand.env: every setting the chosen services pass to the app (DB_HOST,DB_PASSWORD,REDIS_HOST, …) with the development value ship uses — a value built from others, such as SQL Server'sDB_URL, as references ("…${DB_PASSWORD}…"), so it follows them..env.exampleis created if there's none, and.envas its copy;.env.production: the settings a release can't run without (the services' passwords, the framework's own such asAPP_KEY), empty, for you to fill in — a release still refuses until you do.
Only missing keys are added (a commented-out one counts as missing), at the
end of the file under a # Added by ship init … line; nothing is changed or
removed. Where a file gives a setting ship fixes another value (.env's
DB_CONNECTION=sqlite while you chose PostgreSQL), it says so: inside the
containers ship's value wins, and the file's only applies to commands run
outside them. ship config:test reports the same things as warnings. Re-run it any time: every question
starts at the project's current setting, so pressing Enter keeps it. The
instances and processes ship.json already has are listed, ticked: untick one
to remove it (an instance's data volume stays until you delete it), and to
change one, untick it and add it again. In a
terminal it uses Laravel Prompts
(arrow keys, space to tick, answers checked as you type, Ctrl+U to go back
to the previous question, which keeps the answer you gave), on a clean
screen that gives the terminal's earlier content back when it ends, with
the summary below it; nothing is written until the last answer. With -n it takes
every default, and without a terminal (piped, CI, native Windows) it asks plain
numbered questions instead.
It writes ship.json and publishes a ship/ directory (Dockerfile,
nginx/php config) into your project root — both are meant to be committed.
Production is a separate pair of commands, not a flag on ship up — see
Production releases below for ship build/ship release.
Commands
| Command | What it does |
|---|---|
ship init |
Interactive picker for services (database, cache, runtime, ...); writes ship.json and publishes the ship/ directory. Re-run it after upgrading ship to pick up stub changes — see Adding a service later. |
ship up |
Regenerates ship/docker-compose.generated.yml from ship.json and runs docker compose up --build -d. Development only — see ship build/ship release below for production. |
ship build |
Builds every project-owned production image, tagged locally. Needs a real .env.production the moment any selected service has a required credential — see that section below. See Production releases. |
ship release --tag <tag> [--force] [--no-env] |
Builds the same images (re-tagged) and assembles the portable release under dist/ship/<tag>/, described by release.json (the ship-release contract). --force replaces an existing release of that tag; --no-env leaves .env.production out. Needs name in ship.json. See Production releases. |
ship down [--volumes] |
docker compose down. --volumes also deletes named volumes (database/storage data — use with care). |
ship exec <service> <cmd...> |
Runs an arbitrary command inside a running service container. The generic escape hatch every shortcut below wraps. |
| ship shell [service] | Opens an interactive shell (sh) in a service; defaults to app. |
| ship logs [service] [-f] | Tails logs for one service, or all services if none given. -f/--follow streams live. |
| ship db [instance] | Opens a database's interactive client shell (psql/mysql/mariadb/mongosh/sqlcmd), reading credentials from that container's own environment. Omit instance for the default database; name one of additionalServices' database entries to open that instance instead. Fails clearly if no database is selected, or the named instance doesn't exist. |
| ship config:test | ship.json's equivalent of nginx -t: validates ship.json, builds both the development and production compose files, and checks for a required production credential missing from .env.production or a stale nginx upstream, and warns about service settings missing from .env or .env.example, values there that ship's containers override, and framework settings a release needs (APP_KEY) — all without starting or building anything. Reports every problem it finds in one pass, not just the first. |
| ship doctor | Shows the installed and published versions and the state and health of every container in the development stack, with a recovery hint for anything that crashed or is unhealthy. Reads the compose file ship up generated; changes nothing. |
| ship composer <args...> | Proxies to composer inside the app container. |
| ship npm <args...> | Proxies to npm inside the app container (e.g. ship npm run dev, ship npm install). |
| ship yarn <args...> / ship pnpm <args...> | Proxies to Yarn or pnpm inside the app container, at the version package.json's packageManager names. ship npm, ship yarn and ship pnpm each refuse to run in a project that uses another package manager (see JavaScript package managers). |
| ship package-manager <npm\|yarn\|pnpm>[@version] | Switches the project to that package manager, or updates the version it records: removes the other tools' lockfiles and node_modules (asking first), records the tool in packageManager, and reinstalls. Needs the app running (ship up). |
| ship artisan <args...> | Proxies to php artisan inside app — only registered when Laravel's artisan is detected at the project root. |
| ship console <args...> | Proxies to php bin/console inside app — only registered when Symfony's bin/console is detected at the project root. |
| ship tempest <args...> | Proxies to php tempest inside app — only registered for a Tempest project (a tempest console file and tempest/framework in composer.json). |
ship exec and every proxied command forward their arguments exactly as
typed, flags included (-m in ship artisan make:model Post -m), so ship
doesn't need to know about every artisan or console subcommand. That
includes flags ship has too: ship pnpm --version prints pnpm's version and
ship artisan migrate --help shows artisan's help. ship's own options go
before the command name (ship -q npm install).
Services
ship init asks for at most one service per group, and additionalServices adds
named second instances where that makes sense (see
Multiple instances of a service). The
tables below show, per group, what each built-in service wires up and what
is still on the app to add. "Wired" means the container runs and the right
env vars are set on app; it does not mean the Composer package that
reads those env vars is installed — that's the app's decision. The group's
key in ship.json is in each heading.
Everything in the right-hand columns is one-time setup per project:
ship's job stops at "the infrastructure is reachable with the right env
vars", not "every Composer package is pre-installed".
Databases (database)
| Service | Wired automatically | Still needed in the app |
|---|---|---|
Postgres (postgres) |
DB_* env vars, pdo_pgsql extension |
Nothing — works out of the box |
| MySQL | DB_* env vars, pdo_mysql extension |
Nothing — works out of the box |
| MariaDB | DB_* env vars (DB_CONNECTION=mariadb), pdo_mysql extension |
Nothing on Laravel 11+, whose mariadb connection this uses |
| MongoDB | MONGODB_URI/MONGODB_DATABASE, mongodb PHP extension (added to the image automatically) |
composer require mongodb/laravel-mongodb, add its mongodb connection to config/database.php (reading those two variables), and set DB_CONNECTION=mongodb yourself if it should be the default. MONGODB_PASSWORD is embedded in the URI, so keep it free of characters that need percent-encoding (@ : / ? # [ ] %) |
SQL Server (sqlserver) |
Its own sqlserver container: the Developer edition in development; in a release, the edition MSSQL_PID in .env.production names (Standard, Enterprise, … or a product key), Developer when unset — see SQL Server licensing. DB_* env vars (DB_CONNECTION=sqlsrv) plus DB_URL with trust_server_certificate=true (the container's certificate is self-signed), the app database and a login owning it created on first boot, pdo_sqlsrv and Microsoft's ODBC driver (added to the image automatically, in production too) |
Nothing on Laravel. In production .env.production must set DB_PASSWORD and DB_ROOT_PASSWORD. Passwords must meet SQL Server's policy (8+ characters from three of upper/lowercase, digits, symbols, and not containing the login's name: with the default DB_USERNAME=app, a password containing "app" is refused) — the defaults do; DB_PASSWORD also goes into DB_URL, so keep it free of characters that need percent-encoding. DB_USERNAME can't be sa. Needs about 2 GB of RAM, and the image is amd64-only (emulated on Apple Silicon) |
SQL Server licensing
Development runs SQL Server's Developer edition, which Microsoft licenses for
development and testing at no cost. A release runs the edition MSSQL_PID in
.env.production names — Standard, Enterprise, or your product key — and
the Developer edition when it's unset. That lets you put a release on a
server and try it before you buy a license; ship build, ship release and
ship config:test warn while it would run as the Developer edition. A named
instance reads its own, <NAME>_MSSQL_PID. Licensing is yours: the container
accepts Microsoft's license terms (ACCEPT_EULA=Y) as the image requires.
Cache (cache)
| Service | Wired automatically | Still needed in the app |
|---|---|---|
| Redis | CACHE_STORE/SESSION_DRIVER/REDIS_*, redis PHP extension |
Nothing — works out of the box |
Valkey (valkey) |
CACHE_STORE/SESSION_DRIVER (redis, the driver Valkey serves), REDIS_*, redis PHP extension; persisted like Redis |
Nothing — works out of the box. Also serves Centrifugo's Redis engine |
Memcached (memcached) |
CACHE_STORE=memcached, MEMCACHED_HOST/MEMCACHED_PORT, memcached PHP extension (added to the image automatically) |
Nothing. It's cache only: nothing survives a restart, so sessions stay on the app's own driver (SESSION_DRIVER is left alone) |
Search (search)
| Service | Wired automatically | Still needed in the app |
|---|---|---|
| Meilisearch | SCOUT_DRIVER/MEILISEARCH_* |
composer require laravel/scout meilisearch/meilisearch-php |
| Elasticsearch | Single node with security on, ELASTICSEARCH_HOST/USERNAME/PASSWORD (the elastic user), JVM heap capped at 1 GB in development |
An Elasticsearch client package of your choice, configured from those variables (Laravel has no built-in driver, so SCOUT_DRIVER is left alone). On Linux, raise vm.max_map_count to 262144 for real workloads |
Typesense (typesense) |
SCOUT_DRIVER=typesense, TYPESENSE_HOST/PORT/PROTOCOL/API_KEY; persisted |
composer require laravel/scout typesense/typesense-php, and a collection schema per searchable model in config/scout.php (Scout's Typesense docs). In production .env.production must set TYPESENSE_API_KEY |
Object storage (storage)
| Service | Wired automatically | Still needed in the app |
|---|---|---|
| Garage / SeaweedFS / RustFS / Silo | AWS_* env vars (S3-compatible) |
composer require league/flysystem-aws-s3-v3, and set FILESYSTEM_DISK=s3 yourself. Garage auto-provisions its own default bucket; RustFS/SeaweedFS/Silo don't — create it yourself once (Silo has a web console for this at ${SILO_CONSOLE_PORT:-9001}; RustFS's own console doesn't currently work, see that class's own docblock). Silo has two image variants — see Silo on older CPUs |
Silo on older CPUs
Silo publishes two images of every release, and they don't run on the same set of machines:
siloImage |
Image | What's in it |
|---|---|---|
standard (default) |
pgsty/silo:<release> |
The server on a RHEL 9 base, with a shell and the usual tools. |
distroless |
pgsty/silo:<release>-distroless |
The server binary only. No shell, so ship shell silo can't open one. |
RHEL 9 requires a CPU with the x86-64-v2 instruction set. On an older CPU — or a virtual machine configured with a generic CPU model, which hides those instructions from the guest — the standard image's container fails to start. The distroless image of the same release has no such requirement.
ship init explains this and asks which image to use whenever Silo is
selected, then records the answer in ship.json:
"siloImage": "distroless"
ship.json is shared by everyone who runs the project, so pick distroless
if any machine that will run this stack might be affected: yours, a
teammate's, or the production server. To check a Linux machine:
/lib64/ld-linux-x86-64.so.2 --help | grep x86-64-v2
x86-64-v2 (supported, searched) means the standard image will run there.
You can change your mind later: edit siloImage and run ship up again (or
cut a new release). Both images are the same Silo release and mount the same
data volume, so buckets and objects carry over. The setting applies to every
Silo instance, including ones added through additionalServices.
Mail (mail)
| Service | Wired automatically | Still needed in the app |
|---|---|---|
| Mailpit | MAIL_HOST/MAIL_PORT |
Nothing (fresh Laravel already defaults MAIL_MAILER=smtp) |
Message broker (broker)
| Service | Wired automatically | Still needed in the app |
|---|---|---|
| RabbitMQ | Its own rabbitmq container with the management UI on 127.0.0.1:${RABBITMQ_MANAGEMENT_PORT:-15672} (development only), RABBITMQ_HOST/PORT/USER/PASSWORD/VHOST, sockets PHP extension (always in the image) |
composer require vladimir-yuldashev/laravel-queue-rabbitmq, then set QUEUE_CONNECTION=rabbitmq yourself |
WebSockets (broadcasting)
| Service | Wired automatically | Still needed in the app |
|---|---|---|
| Reverb | Its own reverb container + published port, BROADCAST_CONNECTION=reverb, server-side REVERB_HOST=reverb/REVERB_PORT/REVERB_SCHEME (Docker DNS — app talking to reverb), browser-side VITE_REVERB_HOST=localhost/VITE_REVERB_PORT/VITE_REVERB_SCHEME (what Echo in the browser actually connects to) |
composer require laravel/reverb, then php artisan install:broadcasting inside the container once (generates REVERB_APP_ID/KEY/SECRET into .env — real per-app credentials, not something ship provisions). ship init warns at selection time if the package isn't installed yet, since the reverb container won't start without it. |
Centrifugo (centrifugo) |
Its own centrifugo container (the framework-agnostic alternative to Reverb, no app code), published on 127.0.0.1:${CENTRIFUGO_PORT:-8001} in development with its admin UI (password ${CENTRIFUGO_ADMIN_PASSWORD:-ship}), server-side CENTRIFUGO_URL/CENTRIFUGO_API_KEY/CENTRIFUGO_TOKEN_SECRET, browser-side VITE_CENTRIFUGO_URL |
A client: composer require centrifugal/phpcent to publish from PHP (its API is CENTRIFUGO_URL + /api), and centrifuge (npm) in the browser, with connection tokens signed using CENTRIFUGO_TOKEN_SECRET. On Laravel, a broadcasting driver package if you want broadcast(); BROADCAST_CONNECTION is left alone. Runs in memory; see Centrifugo with Redis for running more than one Centrifugo server. In production .env.production must set CENTRIFUGO_API_KEY, CENTRIFUGO_TOKEN_SECRET and CENTRIFUGO_ALLOWED_ORIGINS (space-separated, e.g. https://example.com): with no allowed origins Centrifugo refuses every browser |
Reverb: a service or a process?
A Laravel app can run Reverb in one of two ways. Pick one, not both: both would start a Reverb server.
| Ship's Reverb service | Reverb as a process | |
|---|---|---|
| How to choose it | ship init: Broadcasting → Reverb |
ship init: Broadcasting → None, then tick Reverb in the process checklist (or write it in processes yourself) |
| Development | Runs with ship up, its port published |
Not started; run it from docker-compose.override.yml (see processes) |
| Production | Runs, in release.json's http[] |
Runs, in http[] |
| Address the browser uses | VITE_REVERB_HOST, baked into the frontend when the release is built |
Any setting you name in its urlSetting (e.g. REVERB_PUBLIC_HOST), so the app can read it at runtime |
Take the service unless your frontend gets Reverb's address at runtime.
ship init only suggests Reverb as a process while the service isn't
chosen, so with Broadcasting → Reverb it doesn't appear in the process
checklist.
Centrifugo with Redis
By default Centrifugo keeps everything in memory, which is right for one Centrifugo server. Switch it to Redis when you run more than one Centrifugo server for the same app (several machines behind a load balancer, say). With Redis, the servers act as one: a message published to any of them reaches every client, whichever server it is connected to. Without it, each server only knows its own clients, so a browser connected to one server misses what's published to another.
You don't need Redis for a single server. Clients reconnect and resubscribe on their own after a restart either way; the only things memory loses on a restart are presence information and message history, and only if you use those features.
It's opt-in, with two settings. They are read when Compose starts the stack,
so they go in .env for development and in .env.production for a release
(not in ship.json), and changing them needs no rebuild:
| Setting | Default | Meaning |
|---|---|---|
CENTRIFUGO_ENGINE |
memory |
Set to redis to turn the Redis engine on. |
CENTRIFUGO_REDIS_ADDRESS |
The project's own cache when it is Redis or Valkey (redis://redis:6379, redis://valkey:6379, following a serviceNames rename); none otherwise |
The Redis to use, as redis://host:port. A password goes in the URL: redis://:password@host:6379. |
Using the project's own Redis. With Redis or Valkey (which speaks the
same protocol) selected as the cache, turning it on is one line:
CENTRIFUGO_ENGINE=redis
Centrifugo's keys all start with centrifugo, so sharing the app's Redis
doesn't collide with its cache, sessions or queues. When Redis or Valkey is
selected, centrifugo also starts after it (whichever engine is used).
Memcached can't serve as Centrifugo's engine.
Using another Redis. For a Redis outside the project, such as a shared one that every Centrifugo server can reach, name it as well:
CENTRIFUGO_ENGINE=redis CENTRIFUGO_REDIS_ADDRESS=redis://:the-password@redis.internal:6379
This is also how several servers share one Redis: deploy the same release on
each, with the same CENTRIFUGO_REDIS_ADDRESS (and the same
CENTRIFUGO_API_KEY and CENTRIFUGO_TOKEN_SECRET, so a token signed for one
server works on all of them). Without a project Redis, CENTRIFUGO_ENGINE=redis
needs CENTRIFUGO_REDIS_ADDRESS; there's nothing to default to.
Turning it on. After changing the settings, ship up in development, or
docker compose up -d from the release folder in production, recreates the
centrifugo container with the new engine. Nothing has to be migrated: the
memory engine had nothing to keep. Turning it off again is the same, with
CENTRIFUGO_ENGINE=memory or the line removed.
Checking it works. Centrifugo's info API lists every server it is
connected to through Redis. From the release folder (or the project, with
ship exec in place of docker compose exec):
docker compose exec centrifugo sh -c \ 'wget -qO- --header "X-API-Key: $CENTRIFUGO_HTTP_API_KEY" --post-data "{}" http://127.0.0.1:8000/api/info' \ | grep -o '"uid"' | wc -l
It prints the number of Centrifugo servers acting as one: 1 with the memory engine, or with Redis and a single server; the number of servers once they share a Redis.
When it can't reach Redis, Centrifugo exits at once and the container
restarts in a loop. Its log (docker compose logs centrifugo) says why, in
a line with "level":"fatal":
WRONGPASS invalid username-password pair: the password inCENTRIFUGO_REDIS_ADDRESSis wrong.dial tcp 127.0.0.1:6379: connect: connection refused: no address was given (CENTRIFUGO_ENGINE=rediswithout a project Redis and withoutCENTRIFUGO_REDIS_ADDRESS), so it tried its own container.- Any other
dial tcp ...error: the address is wrong, or that Redis isn't reachable from Centrifugo's network.
Both settings appear in a release's release.json under env.referenced, so
a deployment tool knows it may supply them.
Application runtime (runtime)
| Service | Wired automatically | Still needed in the app |
|---|---|---|
| php-fpm + nginx (default, no runtime selected) | app runs php-fpm behind a webserver nginx container, which also serves the built static assets |
Nothing |
| Octane (Swoole/RoadRunner/FrankenPHP) | swoole PHP extension (Swoole only), OCTANE_SERVER |
composer require laravel/octane, then php artisan octane:install inside the container once (downloads the RoadRunner binary if that's the one picked) |
Browser testing (testing)
| Service | Wired automatically | Still needed in the app |
|---|---|---|
| Dusk | Selenium container, DUSK_DRIVER_URL, and APP_URL set to the app's internal address (http://webserver, or http://app:8000 with Octane) |
composer require --dev laravel/dusk |
| Playwright | Browser server container (Chromium, Firefox, WebKit), PW_TEST_CONNECT_WS_ENDPOINT so the test runner in app launches every browser there, PLAYWRIGHT_BASE_URL set to the app's internal address |
npm install -D @playwright/test@1.65 (the same minor version as the server — Playwright refuses a mismatch), and use: { baseURL: process.env.PLAYWRIGHT_BASE_URL } in playwright.config. No npx playwright install needed. Run with ship npm exec playwright test |
| Cypress | Cypress container (Electron, plus Chrome, Firefox and Edge on amd64) with the project mounted at /e2e, CYPRESS_BASE_URL set to the app's internal address, CYPRESS_INSTALL_BINARY=0 on app so npm install there skips the binary |
npm install -D cypress. Run with ship exec cypress cypress run (--browser chrome etc.). Test artifacts (screenshots, videos) are written as root on a Linux bind mount |
Browser tests and Vite
Dusk's, Playwright's and Cypress's browsers run in their own containers
and reach the app at its internal address, not localhost, so they can't
load assets from Vite's dev server (ship npm run dev writes
http://localhost:5173 into public/hot). Run browser tests against built
assets: stop the dev server (which removes public/hot) and
ship npm run build first.
Frontend (frontend)
| Service | Wired automatically | Still needed in the app |
|---|---|---|
| Node.js, npm, Yarn, pnpm | Installed unconditionally in the base image, at the version ship init's "Node.js version" prompt sets (ship.json's node field, default 24), with Yarn and pnpm through Corepack; ship npm run dev works regardless of whether this group is selected |
See Frontend dev server below for HMR, and JavaScript package managers |
JavaScript package managers
A project uses one of npm, Yarn (1 or 2+) and pnpm. ship decides which in one place, the same way for every command and for the production build:
package.json'spackageManagerfield, e.g."packageManager": "pnpm@12.21.0";- otherwise the project's lockfile:
package-lock.json(ornpm-shrinkwrap.json),yarn.lockorpnpm-lock.yaml; - otherwise nothing is decided yet: any of them can make the first install, and the production build uses npm.
Yarn and pnpm run through Corepack
(installed in the image at a pinned version, since Node stopped bundling
it), which runs exactly the version packageManager names and downloads it on
first use. Downloaded versions are kept in a volume, so a rebuilt image
doesn't download them again. npm is the one Node comes with.
ship init asks which package manager the project uses, defaulting to the
one it already uses, and records it in packageManager: Yarn's and pnpm's
current version (a Yarn 1 project stays on Yarn 1), or the npm the project's
Node version comes with. Choosing a different tool than the project uses
records the choice, and ship up reminds you to finish the switch with
ship package-manager, which needs the container.
Mixing package managers breaks a project quietly: each reads only its own
lockfile, and they lay out node_modules differently. So ship stops it
early, and every message points at the one command that fixes it:
ship yarn add …in an npm project (or any other tool than the project's) is refused, with the command to use instead;ship config:test,ship buildandship releasereport lockfiles of more than one tool, andship upreminds you;ship package-manager <tool>switches the project. It lists what it will remove (the other tools' lockfiles,node_modules, Yarn's Plug'n'Play files) and asks first, records the tool, and installs with it. Pick the version withship package-manager pnpm@10oryarn@4; without one, Yarn gets the current stable release and pnpm the latest. Run with the tool the project already uses, it only updates the recorded version (ship package-manager pnpm@latest). Commitpackage.jsonand the new lockfile afterwards.
To run another tool on purpose anyway (a one-off pnpm dlx … in an npm
project), ship exec app pnpm dlx … isn't checked.
Configuration (ship.json)
ship init writes this file; you normally don't hand-edit it, but it's a
plain, readable JSON document:
{
"$schema": "https://raw.githubusercontent.com/ship-ecosystem/spec/main/schemas/ship.schema.json",
"php": "8.4",
"node": "24",
"services": {
"database": "postgres",
"cache": "redis",
"frontend": "node",
"broadcasting": "reverb"
},
"additionalServices": [
{"group": "database", "service": "mysql", "name": "analytics"}
],
"extensions": []
}
-
$schema— the ship.json schema in the ecosystem's shared specification, whichship initwrites so editors validate and complete the file. Every Ship package uses it, so the field names below mean the same thing in all of them; this package keeps a copy inschema/that CI checks is identical. -
php— the PHP version built into the image (ARG PHP_VERSIONinship/Dockerfile). Keep it a bare branch ("8.4") so every build gets that branch's latest patch release. See PHP security floor for the versions ship refuses. -
node— the Node.js major version built into the image (ARG NODE_VERSION), independent of whether thefrontendgroup's Node service is selected — Node installs unconditionally either way (see the Services table above). -
services— one selected service key per group; a group with no entry means "none selected". A service's key is also its compose service name and names its data volume:postgresruns as thepostgresservice with theship-postgres-datavolume. -
additionalServices— extra, named instances beyond the one inservices(a second database, a second Redis, ...). See Multiple instances of a service below. -
extensions— fully-qualified class names of third-partyServiceDefinition/FrameworkAdapterimplementations to load. See Extending ship. -
serviceNames/externalNetwork— rename any compose service (app, webserver, database, cache, ...) and/or attach the app to a pre-existing Docker network. Omitted here since almost no project needs them — see Custom service names and an external network. -
phpExtensions— extra PHP extensions to install beyond the fixed set every project already gets (pdo_pgsql,pdo_mysql,intl,mbstring,opcache,pcntl,redis,zip,sockets), and beyond what a selected service adds on its own (mongodbfor MongoDB,memcachedfor Memcached,pdo_sqlsrvfor SQL Server), and beyond what your Composer packages declare: everyext-*requirement incomposer.lock(and your owncomposer.json) that the image lacks is installed without being listed here —bcmathfordragon-code/support, say. Development-only packages count for the development image only. So list an extension here only when your code needs one no package declares, e.g.gdfor image handling.ship initasks for these, after saying what's added anyway and why, and drops from the list any that are now added anyway:"phpExtensions": ["gd"]
Fed to
mlocati/docker-php-extension-installer, which handles each extension's own build dependencies for you. -
siloImage—"standard"(the default, omitted) or"distroless": which image the Silo storage service runs.ship initasks when Silo is selected — see Silo on older CPUs. -
publishPorts— defaults tofalse, so production publishes nothing to the host. A reverse proxy (Caddy, Traefik, ...) can reach the HTTP service when joined to the project'sshipDocker network, or throughexternalNetwork, which every HTTP-serving service joins. SetpublishPortstotrueonly when you intend to expose the generated host ports; they may bypass host firewalls and a proxy's TLS and headers. Production only — development always publishes what it needs. -
deployCommands— shell commands meant to run exactly once per deploy, before the app services start:"deployCommands": ["php artisan migrate --force", "php artisan telescope:setup-database"]
ship release --tagwrites these into the release's owndeploy-commands.shrather than running them itself — see Production releases — which brings up the database/cache services first (and waits for them to be healthy) before running each command in a one-off container of the app image, then stops if one fails, so the operator never starts new code against a schema it doesn't match. This is deliberately not where framework boot steps likeartisan optimizelive: those run at every container boot (see Production releases), which is exactly wrong for a migration — with more than one container from the same image, each would run it at once. Ignored in development. -
processes— extra long-running processes that run your app from the same image: a queue worker, Laravel Horizon, the scheduler. Name → shell command:"processes": { "horizon": "php artisan horizon", "scheduler": "php artisan schedule:work" }
Each becomes its own compose service (the name is the service name) built from the app's own build config, with the app's environment and networks — so it reaches the same database and any
externalNetwork— and no published ports. Separate containers rather than a second process supervised inside the app container: independently restartable, visible indocker compose ps, and each gets its own SIGTERM. They run aswww-data, and get a 60s stop grace period so Horizon or a worker can finish its job instead of being SIGKILLed after Compose's default 10s.Production only, and the reason development runs "almost" the same stack.
ship updoesn't start them: a long-running worker loads your code once, so in development it would keep running the old code after every edit until restarted. Start the ones you need yourself, in another terminal, inside the app container:In production In development php artisan horizonship artisan horizon(after changing a job: Ctrl+C and start it again)php artisan queue:workship artisan queue:listen(reloads your code for every job)php artisan schedule:workship artisan schedule:workphp artisan reverb:start …(anhttpprocess)a service in docker-compose.override.yml, below: the browser needs its port, whichship artisancan't publishphp bin/console messenger:consume …ship console messenger:consume … -vvphp tempest command:monitorship tempest command:monitorWithout them, everything else works: requests, Vite, the database. Only the work those processes do (queued jobs, scheduled tasks, WebSockets) waits until you start them.
To have one start with
ship upanyway, or to reach anhttpprocess from the browser, add it todocker-compose.override.ymlyourself, from the app's development image, with the code mounted and its port published on 127.0.0.1:services: reverb: image: 'myproject-app' # <name>-<app service>, the dev image `ship up` builds depends_on: [app] command: ['php', 'artisan', 'reverb:start', '--host=0.0.0.0', '--port=8080'] volumes: ['.:/var/www/html'] ports: ['127.0.0.1:8080:8080'] networks: [ship] env_file: [{path: .env, required: false}] environment: SHIP_DEV_SKIP_INSTALL: '1' # the app container runs composer install restart: unless-stopped
After changing code such a worker runs, restart it with the same files
ship upuses:docker compose -f ship/docker-compose.generated.yml -f docker-compose.override.yml --project-directory . restart reverb.Write each command as a plain shell command,
$VARreferences included —shipescapes every$for you so Compose's own interpolation never sees (and silently blanks out) a variable meant for the container's shell instead.A process that receives HTTP itself (your own WebSocket server, a second HTTP service) says so with the object form, whose
httpblock has the same fields as a release'shttp[]entry:"processes": { "reverb": { "command": "php artisan reverb:start --host=0.0.0.0 --port=8080", "http": {"port": 8080, "role": "websocket", "urlSetting": "REVERB_PUBLIC_HOST"} } }
portandrole(site,websocket, or anything else for plain HTTP) are required;health(a path that answers 2xx) andurlSetting(the name of the setting holding its public address) are optional. Such a process is listed inrelease.json'shttp[], so a deployment tool routes to it; it's attached toexternalNetworklike the site; its healthcheck asks it over HTTP (itshealthpath, or any answer at all without one); and withpublishPortsits port is published at${<NAME>_PORT:-<port>}(REVERB_PORThere). Use this rather than the built-in Reverb service when the app reads Reverb's public address at runtime instead of fromVITE_REVERB_HOST— see Reverb: a service or a process?.A process can also bring its own health check, a shell command run in its container that exits 0 while it works. It replaces the default check (over HTTP, or "stayed up"):
"horizon": {"command": "php artisan horizon", "healthcheck": "php artisan horizon:status"}
horizon:statusexits 0 only while Horizon runs, so a deployment waits for Horizon itself, not just its container.ship initadds it when you tick Horizon.
Host-side port collisions (running more than one ship project, or
another tool already using a default port) are handled with environment
variables at ship up time, not by editing ship.json — see
Running more than one project at once.
Adding a service later
There are two ways to add a service to an existing project.
For most services, add the entry directly to ship.json's services
object (e.g. "broadcasting": "reverb") and run ship up again — it
reads ship.json fresh every time, regardless of how it got there. The
one exception is Garage, which needs a config file ship init publishes
into ship/garage/, so add that one by re-running ship init.
Re-running ship init works for every service. It asks about each group
again, but every prompt defaults to whatever's already selected, so press
Enter to keep it; existing additionalServices entries are kept without
being asked about at all. Every field it doesn't prompt for
(serviceNames, externalNetwork, phpExtensions, publishPorts,
deployCommands, processes, hostUser, name, extensions) carries
over from the existing ship.json unchanged.
It also republishes the stub files in ship/, overwriting them. If
you edited any by hand (the Dockerfile, the nginx config, the dev
entrypoint), commit or back them up first and re-apply your changes
afterwards.
Upgrading the php-ship/ship package itself is different: ship up
doesn't republish stub files on its own — only ship init does — so
it warns instead, comparing the version recorded at the last ship init against what's currently installed, and telling you to re-run
ship init if they differ.
ship build, ship release and ship config:test go further when it
matters: the published files carry a revision (ship/.stub-revision), and
when the compose files this version generates depend on something newer
than the published files have (the healthchecks' php-fpm ping, say), they
refuse to build until ship init republishes them, instead of producing a
release whose images don't match its compose file.
Multiple instances of a service
ship.json's services object holds exactly one selection per group —
enough for a project with one database, one cache, one of everything.
Some projects genuinely need more: a Postgres primary plus a MySQL
connection into a legacy system, a second Redis kept separate from the
default cache/session store, an S3-compatible bucket used only for
backups. additionalServices is for that — each entry adds one more
instance of a service, under a name of your choice:
"additionalServices": [ {"group": "database", "service": "mysql", "name": "analytics"} ]
ship init offers to add these interactively too, right after the main
picker ("Add a named additional service instance?"), and validates the
name you type there. Editing ship.json by hand instead, that name
must be lowercase letters, digits, and underscores only, starting with
a letter (analytics, queue_2 — not Analytics, my analytics, or
2nd-db) — it becomes two things at once:
- The env vars this instance's connection details use — instead of the
default instance's
DB_HOST/DB_CONNECTION/etc., you getANALYTICS_DB_HOST/ANALYTICS_DB_CONNECTION/etc. Wire it into your own app config the same way you would for any second connection — for Laravel, a second entry inconfig/database.php'sconnectionsarray reading thoseANALYTICS_*variables. - The compose service name —
mysql-analyticshere, distinct from the plainmysqla default MySQL selection would produce, so named volumes (ship-mysql-analytics-data) andship db analytics(open that instance's shell specifically, instead of the default database's) both resolve unambiguously.
Not every group supports this — only ones where a second instance
actually means something: database, cache, storage, search, and
mail. A second application runtime, frontend toolchain, testing
driver, broadcasting server or message broker isn't a coherent idea, so
those stay single-select only.
Custom service names and an external network
By default every compose service uses a fixed name — the PHP container
is app, its nginx container is webserver, a selected database is its
engine's own key (mysql, postgres, ...), and so on. Fine for one project
on its own, but not once several ship-managed projects need to sit on
the same Docker network: Compose gives every container a network alias
matching its service name, so two projects each running, say, an app
or a mysql collide the instant they join that network together.
Not prompted by ship init — hand-edit ship.json when you actually
need it:
{
"serviceNames": {
"app": "client-app",
"webserver": "client-web",
"mysql": "client-db"
},
"externalNetwork": "shared_infra"
}
serviceNames— maps a service's default compose name to a custom one. Everyshipcommand that picks a service for you (ship shellwith no argument,ship db,ship composer/ship npm/ship yarn/ship pnpm/ship artisan, Mutagen sync) follows the rename automatically, as does the env var carrying that service's own hostname (DB_HOST,REDIS_HOST, ...) — only the hostname changes; a driver identifier that happens to read the same as the old name (DB_CONNECTION=mysql) is left alone. Rename as many or as few as you need; anything not listed keeps its default name. Doesn't apply toadditionalServicesentries — those already get their own distinct compose name via their ownname. Commands where you type the service (ship exec <service> …,ship logs <service>,ship shell <service>) take the literal compose name, so after renamingapptoadmin-appthat'sship exec admin-app …. Renamingappspecifically also needsship initre-run afterward (when nginx is in use, i.e. no Octane runtime selected) — the publishedship/nginx/default.confbakes the app service's name into its upstream atship inittime, and only re-running it updates that file;ship upwarns if it ever falls out of sync with a hand-editedserviceNames.externalNetwork— a Docker network created outsideship(by another compose project, e.g. one running your shared MySQL/Redis/etc., or a reverse proxy), or a list of them (["proxy", "monitoring"]), attached in addition toship's own internal network to the app service and to every service that receives HTTP:webserver(or the app itself under Octane) and Reverb. This is what lets the app reach that shared infrastructure — point your own.env(DB_HOST,REDIS_HOST, ...) at whatever hostname that other project's containers are reachable as — and what lets a proxy on that network route to the site. Databases and other infrastructure stay off it.
A project that doesn't select any of ship's own database/cache/storage
services (an empty, or mostly empty, services object) is exactly the
shape externalNetwork is for: infrastructure lives in another compose
project entirely, and this project's app container just needs a way in.
serviceNames is for the separate, narrower case of a service ship
does provision locally (your own project's database, say) needing a
name that won't collide with an unrelated container already using its
default alias on a network you share.
Production releases
Production is two commands, not a flag on ship up:
ship build # build every project-owned production image ship release --tag 1.2.0 # build + assemble the portable release artifact
Both build a materially different image from ship up's dev one, not the
same one with a flag flipped:
-
No bind mount.
devbind-mounts.:/var/www/htmlso edits are live immediately;proddeliberately doesn't, since a real deploy target shouldn't depend on the host filesystem it happened to build on. Code getsCOPY'd into the image at build time instead, via thebuilder→assets→prodstage chain inship/Dockerfile. -
Frontend assets get built.
ship/build-assets.sh(skipped without apackage.json) runs in theassetsstage, sopublic/buildexists beforeprod/prod-nginxcopy the tree out. It installs with the project's package manager, exactly as the lockfile says (npm ci,yarn install --immutableor--frozen-lockfilefor Yarn 1,pnpm install --frozen-lockfile), so a lockfile that no longer matchespackage.jsonfails the build. It then runs thebuildscript with the same tool and removesnode_modules. A project with more than one tool's lockfile isn't built at all. There is no Vite dev server in production — see Frontend dev server below for that, which only applies in development. -
Opcache is on, the JIT is off. PHP 8.5.12's tracing JIT crashes php-fpm workers (a segfault on every request of a plain Tempest app), and a web request mostly waits on I/O, where the JIT gains little. Turn it back on in
ship/prod/php.iniif you need it. -
Each framework's own optimize command runs at container boot, not build time. Laravel gets
php artisan optimize; Symfony getsphp bin/console cache:clear; Tempest getsphp tempest cache:clear --internal --all --force(so no cache from local development survives into the image) andphp tempest discovery:generate, its deployment guide's steps. This has to happen at boot rather than during the image build because these commands bake real environment values into compiled files, which only exist once the orchestrator injects them at container start, not during the build.Ship\Contracts\FrameworkAdapter::releaseCommands()is the extension point for this — a third-party adapter for another framework returns its own list of boot-time commands the same way. -
An Octane server runs as
www-data, not root — Swoole, RoadRunner and FrankenPHP alike. php-fpm's master starts as root only to drop each worker towww-dataitself, so plain php-fpm is fine. Octane is its own long-lived server with no such split — left alone, every request handler would run as root — so the generated entrypoint runs its root-only steps (artisan optimize, fixing ownership ofstorage/and friends) and then drops towww-databefore starting the server. -
nginx serves static assets itself.
webserverbuilds from the sameship/Dockerfileasapp(aprod-nginxtarget that copies from theassetsstage), so it has access topublic/'s built CSS/JS instead of only being able to proxy PHP requests toapp. -
Every service has a healthcheck, so
docker compose up --wait(anddeploy-commands.sh, and any deployment tool) waits until the whole release really serves, not just until its containers started:Service Healthy when app(php-fpm)php-fpm answers its ping over FastCGI webserver(nginx)nginx passes that ping through to php-fpm app(Octane), Reverbtheir HTTP server answers a request (any status) processesworkersthe worker has stayed up for 10 seconds, which a worker that crashes on boot and restarts in a loop never does processeswithhttptheir healthpath answers 2xx, or without one, their HTTP server answers at alldatabases, caches, search, storage, ... their own checks, as in development These check that the server serves, not that the app works: a deployment tool requests
release.json'shttp[].health(Laravel's/up) for that. Development has no app healthchecks, since the first boot runscomposer install, which can take minutes.
PHP security floor
ship refuses to build on a PHP release with known security vulnerabilities. The current floor comes from the October 2026 critical releases, which fixed two unauthenticated remote code execution bugs: CVE-2026-109618 (OOM corruption) and CVE-2026-109619 (stale global state).
| Branch | Oldest release ship builds on |
|---|---|
| 8.2 | 8.2.35 |
| 8.3 | 8.3.36 |
| 8.4 | 8.4.27 |
| 8.5 | 8.5.12 |
| 8.6 (pre-release) | 8.6.0RC4 |
| 8.1 and older | none (end of life, no upstream fixes) |
It is enforced at three points:
ship initand every command that generates a compose file reject an end-of-lifephpbranch, or a pinned patch release below the floor ("8.4.20").- The Dockerfiles'
basestage checks the PHP that is actually in the base image, and fails the build if it is below the floor. This catches a stalephp:8.4-fpm-alpinethat Docker keeps reusing from its local cache. The fix is in the error message:docker pullthat image and build again. ship build/ship releasealways pull fresh base images (build.pull: truein the production compose file), so a release never ships on a cached, outdated PHP.ship updoesn't force a pull, so it still works offline.
Both php.ini overlays also set session.upload_progress.enabled=Off,
which PHP's advisory recommends keeping off even on patched releases when
nothing uses it. The production overlay sets fatal_error_backtraces=Off,
which only exists on PHP 8.5 and is ignored on older branches.
The Dockerfile check is part of the published ship/Dockerfile, which only
ship init writes; ship up warns when the published stubs are older than
the installed ship. The floor lives in Ship\Support\PhpSecurityFloor,
raised whenever php.net ships a security release.
.env.production
A single project-level file, .env.production, is the one source of
production credentials and config — you create and fill it; ship never
generates one. ship init adds it to the project's .gitignore; if it was
previously committed, remove it from history and rotate its secrets.
ship build/ship release make its values available to
docker compose build (for a hand-edited ship/Dockerfile's own build
args, via Compose's own ${VAR} substitution — nothing is baked into an
image layer just because it's in this file), and ship release copies the
whole file to the release's own .env (unless --no-env), read by the
containers at boot the same way a dev project's .env already is. ship release fails with a
clear error if .env.production doesn't exist — there's no silent
"production ran with no config" failure mode.
VITE_* settings are baked in at build time. Vite copies every
VITE_* setting into the JavaScript it builds, so a release carries the
values .env.production held when it was built: Reverb's or Centrifugo's
public address (VITE_REVERB_HOST, VITE_CENTRIFUGO_URL), VITE_APP_NAME,
and so on. ship build/ship release pass only the VITE_* settings to the
production asset build (they end up in public JavaScript anyway; nothing
else from the file does), with ${OTHER} references resolved the way Laravel
resolves them. Changing one means building a new release, and a release must
be served at the address it was built for — release.json's http[].urlSetting
names the setting, so a deployment tool can read it.
Selected services' own credentials (DB_PASSWORD, MEILISEARCH_KEY,
AWS_SECRET_ACCESS_KEY, ...) are required here, not just read: docker compose itself refuses to build or start anything at all if one was never
set, rather than silently falling back to the same friendly default
development uses — one every project that forgot would otherwise share.
This applies to ship build too, not only ship release: both check for
a missing required credential up front and fail with a message naming it,
before Docker is invoked at all. ship build only needs .env.production
to exist once a project has a credentialed service selected; ship release
always does.
What ship release --tag produces
dist/ship/1.2.0/
├── release.json # describes the release (the ship-release contract) — no secrets
├── docker-compose.yml # final image tags, no build:, pulled images pinned by digest
├── images/
│ ├── app.tar # docker save -- one per *unique* image, not per service
│ └── webserver.tar
├── .env # copied from .env.production (not with --no-env)
├── deploy-commands.sh # only when ship.json's deployCommands is set
└── README.md # the exact deploy steps for this release
The folder is a public contract, ship-release, so deployment tools can
read it. The contract lives in the ecosystem's shared specification,
ship-ecosystem/spec: its document describes
every file and every release.json field, next to the JSON Schema, example
releases and a checker any tool can run. release.json names the app, its images (with IDs and
archive checksums), the services and their roles, which ones receive HTTP
(and the framework's health path), the data volumes, the settings by name
only, the deploy commands, and how to run commands in the running app (its
service, the user to run them as, its shell, and the framework's console
commands such as artisan). The ship commands themselves (ship shell,
ship artisan, ...) are for development: a server has nothing but Docker, so
a deployment tool runs those through Compose with what release.json says,
e.g. docker compose exec -u www-data app php artisan migrate:status. The
contract is a draft until it has been tested end to end with a deployment
tool.
A few rules keep a release trustworthy:
ship.jsonneeds aname. It is the release'sappand the Compose project name on the server, which prefixes the data volumes, so it can't depend on the folder the release happens to be built in.ship releasestops and suggests the name the project resolves to today; keep that one if the project is already deployed, or the server gets new, empty volumes.- A tag is never overwritten silently. An existing
dist/ship/<tag>is refused;--forcereplaces it, and only once the new release is complete. A symlink there is always refused. - A release is complete or absent. It's written under a temporary name
and renamed into place at the end,
release.jsonlast; a failure (say, an image that fails to export) leaves nothing behind. - Images ship doesn't build are pinned.
ship releasepulls each one (Postgres, Redis, ...) and writesname:tag@sha256:...into both the compose file andrelease.json, so the server runs exactly what was released, not whatever the tag points to later. - Settings the framework can't run without are required. Laravel's
APP_KEY, or Tempest'sSIGNING_KEYandENVIRONMENT(without it Tempest runs aslocal), has to be in.env.production, alongside every credential the selected services need. --no-envleaves.env.productionout of the release, for platforms that keep settings themselves. It's still required and checked, andrelease.jsonstill lists the settings by name; whoever deploys provides them (see the contract's "Settings").
dist/ship/ is git-ignored (ship init adds it to .gitignore for you) —
a release is generated output, and often genuinely sensitive (it carries
your .env.production), so it's never meant to be committed. On POSIX systems,
ship release makes the release directory accessible only to its owner and
sets .env permissions to 0600. On Windows, restrict access to the release
folder with filesystem ACLs before sharing or uploading it. The artifact is
also excluded from the Docker build context (.dockerignore,
/dist/ship specifically — not your project's whole dist/, in case you
keep other build output there), along with .env/.env.*, auth.json,
and .npmrc — without that, a second release built in the same project
would bake every earlier release's own .env/images straight into the
next image via the builder stage's COPY . .. ship init writes this
guard, and ship build/ship release re-apply it too, in case
.dockerignore was edited or removed since. Project-owned
services that build from an identical Dockerfile/target/args (most
commonly app and every ship.json processes entry, which build from
the exact same config) share one image and one .tar, listed once in
release.json's images with every service that runs it.
This is deliberately one artifact, not three different formats for a
DevOps handoff, a developer's own manual deploy, and CI/CD. A deploy, once
the folder is on the target machine with nothing but Docker installed
(no PHP, no source, no .env committed anywhere), is:
docker load -i images/app.tar
docker load -i images/webserver.tar
sh deploy-commands.sh # only present when ship.json's deployCommands is set
docker compose up -d
The release's own README.md lists these steps for that exact release.
With the default publishPorts: false, this starts the services without a
public HTTP endpoint. Put a TLS reverse proxy on a network named by
externalNetwork (every HTTP-serving service joins it; release.json's
http says which, and on which port), or set publishPorts: true in
ship.json before creating the release if your deployment intentionally
uses host ports.
ship deliberately stops there — there's no ship deploy that SSHes
anywhere or runs any of this remotely for you. Getting the folder onto the
server (scp, a CI artifact upload, a DevOps handoff) and running those
few commands is on you; what ship guarantees is that the artifact itself
needs nothing else once it's there.
Built ship release on Windows: deploy-commands.sh's executable bit
can't actually be set there (NTFS has no Unix executable bit for chmod()
to set), and ship warns about this when it applies. Either
chmod +x deploy-commands.sh on the server first, or run it as
sh deploy-commands.sh instead of ./deploy-commands.sh.
CI/CD
The same commands, the same artifact — CI is not a third release format:
- run: vendor/bin/ship release --tag ${{ github.ref_name }} - run: # upload dist/ship/${{ github.ref_name }} however your pipeline deploys
ship release fails immediately if --tag is missing in a non-interactive
run (no tty) rather than prompting and hanging the pipeline — pass --tag
explicitly in CI. Interactively, a plain ship release with no --tag
asks for one.
HTTPS / TLS
webserver only listens on plain HTTP (port 80) — ship doesn't
terminate TLS itself. This is a deliberate scope boundary, not an
oversight: TLS termination is meant to happen in front of ship, the
same way it would in front of any other containerized app —
- a load balancer or reverse proxy you already run (an ALB/NLB, Cloudflare,
a Caddy/Traefik/another nginx instance) forwarding plain HTTP to
webserverafter you explicitly enablepublishPorts, or - a sidecar you add yourself via
docker-compose.override.yml— for example acaddyortraefikservice in front ofwebserver, with your certs mounted in.
Serving real traffic over the bare ${APP_PORT:-80}:80 mapping with
publishPorts: true and nothing in front of it means serving it over plain
HTTP. Put a TLS-terminating layer in front before that port reaches the
public internet.
Backing up data volumes
Every stateful service (ship-postgres-data, ship-mysql-data,
ship-mariadb-data, ship-mongodb-data, ship-sqlserver-data,
ship-elasticsearch-data, ship-typesense-data, ship-rabbitmq-data,
ship-redis-data, ship-valkey-data, ship-seaweedfs-data,
ship-meilisearch-data, ...)
persists to a named Docker volume, not a bind mount — docker volume ls
lists them, prefixed with the Compose project name (ship.json's name,
or the project directory's name when it's unset). ship doesn't
back these up or rotate them; that's left to whatever backup tooling
your deploy target already uses. A one-off manual backup of a single
volume looks like:
docker run --rm -v <project>_ship-postgres-data:/data -v "$PWD":/backup \ alpine tar czf /backup/postgres-data.tar.gz -C /data .
and restoring is the same in reverse (tar xzf into a fresh volume
mounted the same way). For anything beyond an occasional manual backup —
scheduled snapshots, offsite storage, point-in-time recovery — use your
database engine's own tooling (pg_dump/mysqldump/mariadb-dump/mongodump, or
the volume backup approach above pointed at a proper backup destination)
rather than relying on the named volume alone.
Frontend dev server (Vite HMR)
ship npm run dev runs Vite's dev server inside the app container. Its
port (${VITE_PORT:-5173} by default) is published to the host
automatically in development, so the browser can reach it — but Vite itself
needs to know to bind somewhere reachable from outside the container, and to
tell the browser the right address to connect back to for the HMR
WebSocket. Add this to your vite.config.js (this is Laravel's own
documented fix for running Vite inside Sail/WSL2 — same underlying problem):
export default defineConfig({ // ... server: { host: '0.0.0.0', // bind inside the container, not just loopback port: Number(process.env.VITE_PORT ?? 5173), strictPort: true, // fail fast instead of silently picking another // port — one the compose file doesn't publish hmr: { host: 'localhost' }, // what the *browser* should connect back to }, });
Reading process.env.VITE_PORT rather than hard-coding 5173 matters if
you ever need a non-default port — e.g. two ship-managed projects run
side by side (see
Running more than one project at once),
or a project that already used a different port before adopting ship.
Both the compose port mapping and Vite's own bind port read the exact same
VITE_PORT from your project's .env (app's env_file: loads the same
file Compose interpolates ${VITE_PORT:-5173} from) — set it once there
and both sides follow it. Only the compose side has a built-in default;
without ?? 5173 here, an unset VITE_PORT would leave Vite's own port
option undefined.
strictPort matters more than it looks: without it, if Vite's default port
is already taken inside the container (e.g. a previous ship npm run dev
that wasn't stopped cleanly), Vite silently starts on the next free port
instead — one the compose file never published — and HMR fails with a
generic connection error that gives no hint the port even changed.
The actual app (Blade-rendered pages, API routes, ...) still serves from
:80 as normal through webserver/nginx — Vite's dev server is a separate
HTTP+WebSocket server on its own port, the same architecture Laravel Sail
uses, not something proxied through the same port as the app. ship
doesn't auto-edit an existing vite.config.js to add this, since reliably
patching arbitrary existing JS config isn't something worth the fragility —
ship init prints this exact snippet as a reminder instead, whenever it
detects vite in package.json and the existing config doesn't already
look like it handles this.
File ownership in dev (why containers run as root)
Dev's app/webserver containers run every process as root — deliberate,
not an oversight. The project root is bind-mounted straight from the host,
so it keeps whatever host UID/GID created it; on a real Linux host (native
Linux, WSL2, this project's own CI) that's essentially never the fixed UID
a container's own unprivileged user would run as (www-data, Laravel
Sail's sail, ...). Matching that fixed UID against the bind mount's
UID (Sail's own approach, via WWWUSER/WWWGROUP) only works when they
happen to coincide — otherwise every write (a compiled view, storage/,
bootstrap/cache/) hits a hard permission-denied. Running as root instead
works unconditionally, on every host, without ever touching host file
ownership to force a match.
The tradeoff: anything the container writes — vendor/, public/build,
storage/ — ends up owned by root on the host too, on hosts where
your own user isn't root (native Linux, WSL2). Harmless for ship itself
(nothing here needs to read those files as a specific non-root user), but
occasionally annoying outside it — e.g. your editor or a host-side shell
command refusing to touch a root-owned file.
If it bothers you, opt in to running as your own user. The objection
above — a fixed container UID only works when it matches the bind mount's —
doesn't apply when the UID comes from the host, so ship.json can ask for
exactly that:
"hostUser": true
ship up reads your UID/GID and builds the dev image with them; php-fpm's
workers, the boot-time composer install, and an Octane server then run as
you (php-fpm's master stays root — it has to, to drop its workers), and ship exec/ship shell/ship composer/ship npm/ship yarn/ship pnpm/ship artisan pass --user for
the app service, so vendor/, public/build and storage/ come out owned by
you. Development only, and only where there's a non-root POSIX user to match:
on native Windows (no UIDs; Docker Desktop's bind mounts don't have this
problem) it does nothing, and it isn't combined with SHIP_MUTAGEN —
ship up prints why it was skipped rather than silently running as root.
Re-run ship up after changing it; it's a build argument, so the image
is rebuilt.
Or fix it after the fact, for just the paths that bother you, by chowning them back from inside the container (root there can chown to any UID, including your own host one):
ship exec app chown -R $(id -u):$(id -g) storage bootstrap/cache vendor public/build
(ship exec takes the literal compose service name, so if you renamed app
via serviceNames, use that name here instead — ship exec admin-app chown ….
ship shell, ship artisan, ship composer, ship npm, ship yarn and ship pnpm already follow
the rename on their own.)
Production is unaffected either way — those files are baked into the image at build time, at a known ownership, not written by a running container into a bind mount at all.
Xdebug (off by default)
The dev image always has Xdebug installed, but xdebug.mode defaults to
off — a loaded-and-active Xdebug slows every request (develop mode
especially) and is documented as unsafe inside Swoole coroutines. Turn it on
per project with Xdebug's own env var in your .env:
XDEBUG_MODE=debug # or develop,debug
app loads .env (env_file:), and Xdebug's XDEBUG_MODE overrides the
ini setting, so it takes effect on the next ship up with no rebuild — for
php-fpm requests and CLI commands alike. host.docker.internal is already
routed to your host, and xdebug.start_with_request=trigger means it only
connects when your IDE or browser extension asks it to.
Faster file sync on Windows/macOS (Mutagen)
ship up's default dev bind mount (the project root, live-mounted into
app/webserver) is simple and always in sync, but Docker Desktop's
translation layer between the host filesystem and its Linux VM makes
filesystem-heavy work — composer install, npm install, a large test
suite — noticeably slower on Windows and macOS than the same thing on
native Linux, where containers talk to the filesystem directly.
Mutagen syncs the project root into the container in
the background instead, which avoids that translation-layer overhead. It's
opt-in, off by default, and a personal machine preference rather than a
project setting — it's pure overhead with zero benefit on Linux, so it
isn't something to bake into ship.json for a whole team. Set the
SHIP_MUTAGEN environment variable before running ship up:
SHIP_MUTAGEN=1 vendor/bin/ship up
ship up creates the sync session after the stack starts and waits for the
initial sync to finish before reporting success; ship down tears the
session down again automatically. Requires
Mutagen
itself to already be installed and on PATH — ship up fails with a clear
error naming it if it isn't.
Never applies in production: the production image bakes the source into itself at build time (see Production releases), so there's no bind mount there to begin with, and nothing to sync either way.
vendor/ and node_modules/ are deliberately excluded from the sync, for
two reasons — not just the sheer file count. Some Composer packages, and
any npm package with a native build step (esbuild, sharp, sass,
swc-based tooling), install platform-specific compiled binaries; syncing
a copy installed on Windows/macOS into the Linux container would hand it
binaries built for the wrong platform outright. The container bootstraps
its own vendor/ the same way it already does without Mutagen (the dev
image runs composer install on boot if vendor/autoload.php is
missing); node_modules/ needs a ship npm install, exactly as it does
with the bind mount.
Running more than one project at once
Every generated compose file carries a top-level name: (ship.json's own
name, or the project directory's basename if it's unset) — every named
volume and the default network alias are keyed off it. Set name in
ship.json whenever it has to stay the same wherever the project is
checked out; ship release requires it, since it names the release and
the volumes on the server.
Every published port has an env var override, read at ship up time from
your shell or a .env file in the project root:
| Port | Variable | Default |
|---|---|---|
| App / nginx | APP_PORT |
80 |
| Octane runtime (serves HTTP itself) | APP_PORT |
8000 |
| Vite dev server | VITE_PORT |
5173 |
| Reverb | REVERB_PORT |
8080 |
| Centrifugo (and its admin UI) | CENTRIFUGO_PORT |
8001 |
| RabbitMQ management UI | RABBITMQ_MANAGEMENT_PORT |
15672 |
| Mailpit web UI | MAILPIT_WEB_PORT |
8025 |
If a default is already taken — by another ship project, or an unrelated
container — override it for one invocation:
APP_PORT=8081 VITE_PORT=5174 REVERB_PORT=8082 vendor/bin/ship up
Every one of these binds to 127.0.0.1 in development, not every
interface — reachable from your own machine, not from another device on
the same network or the internet. Production publishes no ports by default;
set publishPorts: true to enable its host mappings (see
Configuration).
Customizing the stack
ship/docker-compose.generated.yml is exactly that — generated fresh from
ship.json on every ship up, so hand-editing it directly doesn't stick.
To add your own services, or override anything ship's generated file sets,
add a docker-compose.override.yml at your project root — the same file
name and merge behavior Docker Compose itself documents.
Every ship command that shells out to docker compose picks it up
automatically if it exists — except ship build/ship release,
deliberately: it's a dev convenience, and a dev-only build: override
has no business silently reaching a production image or release artifact.
# docker-compose.override.yml services: adminer: image: adminer:4 ports: - '8099:8080' networks: - ship
This works for anything Compose supports — adding a whole new service (like
the Adminer example above), mounting an extra volume, or pointing app's
build.dockerfile at your own Dockerfile instead of ship/Dockerfile
entirely. Nothing here is ship-specific; it's just Compose doing what it
already does, on top of a file ship happens to regenerate for you.
If your project renamed app/webserver/etc. (ship.json's
serviceNames, see
Custom service names and an external network),
key your override entries under the renamed service, not the literal
app — Compose merges override files by that top-level key, so an entry
still keyed app either does nothing or creates an unrelated, empty
service by that name instead of extending the one you actually meant.
For the Dockerfile and nginx/php config ship init publishes into ship/
itself, no override file is needed — ship up never rewrites those, so
editing them directly is safe and persists across every ship up (until
you re-run ship init, which does overwrite them — see the ship init
row in Commands).
Running a command on every container boot
ship/dev/entrypoint.sh is one of those publish-once, hand-editable files
— add your own command there, right before the final exec "$@", and it
runs every time the app container starts, not just the first time (the
file's existing composer install step only runs once, guarded on
vendor/autoload.php being missing):
# ship/dev/entrypoint.sh if [ -f artisan ]; then php artisan telescope:setup-database --no-interaction || true fi exec "$@"
This is the dev equivalent of what EntrypointScriptBuilder already
generates for ship build/ship release (see FrameworkAdapter::releaseCommands())
— useful for anything that needs to run against a real, reachable database
on every boot (creating a package's own tables if they're missing, warming
a cache, ...), not just once when dependencies are first installed.
Extending ship
Third-party packages can contribute their own services or framework
support without forking this package. List fully-qualified class names in
ship.json's extensions array:
{
"extensions": ["Acme\\Ship\\MeilisearchProService"]
}
Each class must already be autoloadable (a normal Composer dependency of your project) and implement one of the two extension points:
Ship\Contracts\ServiceDefinition— an optional infrastructure piece (database, cache, runtime, ...). A service can also implement any of these:ProvidesDatabaseShell— a database's client shell, forship db.ConfigAwareService— readship.json(a setting, or the other selected services) before building its fragment.RequiresPhpExtensions— PHP extensions its client library needs, added to the app image.ExposesHttp— its own HTTP entry point (a WebSocket server), joined toexternalNetworkand listed inrelease.json.NeedsAppUrl— the app's internal URL, for a browser testing driver.
Ship\Contracts\FrameworkAdapter— framework-specific console commands (likeship artisan) and production boot-time release commands. An adapter can also implementDescribesRelease— the framework's name, health path and required settings, forship release.
See docs/adding-a-service.md for a worked
example.
Architecture
src/Contracts/ServiceDefinition.php— the extension point. Every optional piece of the stack (database, cache, runtime, storage, ...) implements this.src/Contracts/FrameworkAdapter.php— the seam a framework-specific wrapper hooks into (ship artisan), without the core package importing that framework.src/Docker/ComposeFileBuilder.php— merges selected services' compose fragments into a generateddocker-compose.yml. Merges rather than overwrites when two services target the same compose service name (e.g. an Octane runtime overridingapp's command while keeping its build/volumes).src/Docker/EntrypointScriptBuilder.php— renders the production container's boot-time entrypoint script from the matchedFrameworkAdapter'sreleaseCommands().src/Docker/ReleaseWriter.phpandReleaseManifest.php— write a release folder and itsrelease.json, the ship-release contract.HttpEntryPoints.phpdecides which services receive HTTP, for both the external network andrelease.json.src/Extensions/ExtensionLoader.php— resolvesship.json'sextensionsarray into registered services/adapters, so third-party packages don't require forking this one.stubs/docker/php/Dockerfile— multi-stage;dev/builder/assets/prod(theappservice) anddev-nginx/prod-nginx(thewebserverservice) all build from this one file.
Contributing
See docs/adding-a-service.md for how to add
a new ServiceDefinition or FrameworkAdapter.
composer install composer test # phpunit composer analyse # phpstan, level 8 composer cs-check # php-cs-fixer --dry-run
License
MIT. See LICENSE.md.