Search by

php-ship / ship

shaprk

Framework-agnostic, cross-platform Docker development environment for PHP — no WSL required.

v0.9.1 2026-10-28 15:50 UTC

This package is auto-updated.

Last update: 2026-11-19 10:59:05 UTC


README

CI Packagist Version Packagist Downloads License

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?

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 up and 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 are FrameworkAdapters (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 same ship.json, not something you reassemble for production.
  • "Almost": processes run only in production. In development you start the ones you need yourself (see processes), 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 .env holds. ship publishes no database port at all (ship db opens the client shell inside the container), and every development port it does publish binds 127.0.0.1 only. 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 serviceNames plus externalNetwork let projects share a Docker network (or a reverse proxy) without name clashes.
  • Files you own on Linux: hostUser runs 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=1 replaces the slow bind mount with a Mutagen sync.
  • Extend it without forking: a docker-compose.override.yml layers on top of what ship generates, and a Composer package can add its own services or framework adapter through ship.json's extensions.

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 ship itself.
  • Docker Desktop (or another Docker Engine + Compose v2 setup) — this is what actually runs your project; ship just drives docker compose.
  • A composer.json in 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/reverb is installed and ship's own Reverb service isn't chosen — see Reverb: a service or a process?; Messenger workers for the transports messenger.yaml configures 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 (see processes);
  • 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.example and .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's DB_URL, as references ("…${DB_PASSWORD}…"), so it follows them. .env.example is created if there's none, and .env as its copy;
  • .env.production: the settings a release can't run without (the services' passwords, the framework's own such as APP_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 in CENTRIFUGO_REDIS_ADDRESS is wrong.
  • dial tcp 127.0.0.1:6379: connect: connection refused: no address was given (CENTRIFUGO_ENGINE=redis without a project Redis and without CENTRIFUGO_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:

  1. package.json's packageManager field, e.g. "packageManager": "pnpm@12.21.0";
  2. otherwise the project's lockfile: package-lock.json (or npm-shrinkwrap.json), yarn.lock or pnpm-lock.yaml;
  3. 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 build and ship release report lockfiles of more than one tool, and ship up reminds 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 with ship package-manager pnpm@10 or yarn@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). Commit package.json and 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, which ship init writes 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 in schema/ that CI checks is identical.

  • php — the PHP version built into the image (ARG PHP_VERSION in ship/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 the frontend group'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: postgres runs as the postgres service with the ship-postgres-data volume.

  • additionalServices — extra, named instances beyond the one in services (a second database, a second Redis, ...). See Multiple instances of a service below.

  • extensions — fully-qualified class names of third-party ServiceDefinition/FrameworkAdapter implementations 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 (mongodb for MongoDB, memcached for Memcached, pdo_sqlsrv for SQL Server), and beyond what your Composer packages declare: every ext-* requirement in composer.lock (and your own composer.json) that the image lacks is installed without being listed here — bcmath for dragon-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. gd for image handling. ship init asks 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 init asks when Silo is selected — see Silo on older CPUs.

  • publishPorts — defaults to false, so production publishes nothing to the host. A reverse proxy (Caddy, Traefik, ...) can reach the HTTP service when joined to the project's ship Docker network, or through externalNetwork, which every HTTP-serving service joins. Set publishPorts to true only 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 --tag writes these into the release's own deploy-commands.sh rather 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 like artisan optimize live: 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 in docker compose ps, and each gets its own SIGTERM. They run as www-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 up doesn'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 horizon ship artisan horizon (after changing a job: Ctrl+C and start it again)
    php artisan queue:work ship artisan queue:listen (reloads your code for every job)
    php artisan schedule:work ship artisan schedule:work
    php artisan reverb:start … (an http process) a service in docker-compose.override.yml, below: the browser needs its port, which ship artisan can't publish
    php bin/console messenger:consume … ship console messenger:consume … -vv
    php tempest command:monitor ship tempest command:monitor

    Without 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 up anyway, or to reach an http process from the browser, add it to docker-compose.override.yml yourself, 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 up uses: 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, $VAR references included — ship escapes 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 http block has the same fields as a release's http[] entry:

    "processes": {
        "reverb": {
            "command": "php artisan reverb:start --host=0.0.0.0 --port=8080",
            "http": {"port": 8080, "role": "websocket", "urlSetting": "REVERB_PUBLIC_HOST"}
        }
    }

    port and role (site, websocket, or anything else for plain HTTP) are required; health (a path that answers 2xx) and urlSetting (the name of the setting holding its public address) are optional. Such a process is listed in release.json's http[], so a deployment tool routes to it; it's attached to externalNetwork like the site; its healthcheck asks it over HTTP (its health path, or any answer at all without one); and with publishPorts its port is published at ${<NAME>_PORT:-<port>} (REVERB_PORT here). Use this rather than the built-in Reverb service when the app reads Reverb's public address at runtime instead of from VITE_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:status exits 0 only while Horizon runs, so a deployment waits for Horizon itself, not just its container. ship init adds 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 get ANALYTICS_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 in config/database.php's connections array reading those ANALYTICS_* variables.
  • The compose service name — mysql-analytics here, distinct from the plain mysql a default MySQL selection would produce, so named volumes (ship-mysql-analytics-data) and ship 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. Every ship command that picks a service for you (ship shell with 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 to additionalServices entries — those already get their own distinct compose name via their own name. Commands where you type the service (ship exec <service> …, ship logs <service>, ship shell <service>) take the literal compose name, so after renaming app to admin-app that's ship exec admin-app …. Renaming app specifically also needs ship init re-run afterward (when nginx is in use, i.e. no Octane runtime selected) — the published ship/nginx/default.conf bakes the app service's name into its upstream at ship init time, and only re-running it updates that file; ship up warns if it ever falls out of sync with a hand-edited serviceNames.
  • externalNetwork — a Docker network created outside ship (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 to ship'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. dev bind-mounts .:/var/www/html so edits are live immediately; prod deliberately doesn't, since a real deploy target shouldn't depend on the host filesystem it happened to build on. Code gets COPY'd into the image at build time instead, via the builder → assets → prod stage chain in ship/Dockerfile.

  • Frontend assets get built. ship/build-assets.sh (skipped without a package.json) runs in the assets stage, so public/build exists before prod/prod-nginx copy the tree out. It installs with the project's package manager, exactly as the lockfile says (npm ci, yarn install --immutable or --frozen-lockfile for Yarn 1, pnpm install --frozen-lockfile), so a lockfile that no longer matches package.json fails the build. It then runs the build script with the same tool and removes node_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.ini if you need it.

  • Each framework's own optimize command runs at container boot, not build time. Laravel gets php artisan optimize; Symfony gets php bin/console cache:clear; Tempest gets php tempest cache:clear --internal --all --force (so no cache from local development survives into the image) and php 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 to www-data itself, 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 of storage/ and friends) and then drops to www-data before starting the server.

  • nginx serves static assets itself. webserver builds from the same ship/Dockerfile as app (a prod-nginx target that copies from the assets stage), so it has access to public/'s built CSS/JS instead of only being able to proxy PHP requests to app.

  • Every service has a healthcheck, so docker compose up --wait (and deploy-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), Reverb their HTTP server answers a request (any status)
    processes workers the worker has stayed up for 10 seconds, which a worker that crashes on boot and restarts in a loop never does
    processes with http their health path answers 2xx, or without one, their HTTP server answers at all
    databases, 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's http[].health (Laravel's /up) for that. Development has no app healthchecks, since the first boot runs composer 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 init and every command that generates a compose file reject an end-of-life php branch, or a pinned patch release below the floor ("8.4.20").
  • The Dockerfiles' base stage checks the PHP that is actually in the base image, and fails the build if it is below the floor. This catches a stale php:8.4-fpm-alpine that Docker keeps reusing from its local cache. The fix is in the error message: docker pull that image and build again.
  • ship build/ship release always pull fresh base images (build.pull: true in the production compose file), so a release never ships on a cached, outdated PHP. ship up doesn'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.json needs a name. It is the release's app and 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 release stops 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; --force replaces 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.json last; a failure (say, an image that fails to export) leaves nothing behind.
  • Images ship doesn't build are pinned. ship release pulls each one (Postgres, Redis, ...) and writes name:tag@sha256:... into both the compose file and release.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's SIGNING_KEY and ENVIRONMENT (without it Tempest runs as local), has to be in .env.production, alongside every credential the selected services need.
  • --no-env leaves .env.production out of the release, for platforms that keep settings themselves. It's still required and checked, and release.json still 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 webserver after you explicitly enable publishPorts, or
  • a sidecar you add yourself via docker-compose.override.yml — for example a caddy or traefik service in front of webserver, 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, for ship db.
    • ConfigAwareService — read ship.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 to externalNetwork and listed in release.json.
    • NeedsAppUrl — the app's internal URL, for a browser testing driver.
  • Ship\Contracts\FrameworkAdapter — framework-specific console commands (like ship artisan) and production boot-time release commands. An adapter can also implement DescribesRelease — the framework's name, health path and required settings, for ship release.

See docs/adding-a-service.md for a worked example.

Architecture

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.