Sail-Integration

Technical reference synchronized with Yard’s source. File names and development commands refer to the native app repository.

How Yard runs a Laravel Sail project (Docker Compose) without asking the user to learn anything new: myapp.test keeps working, with HTTPS, Studio, yard php, the dev server and Insights, while PHP and the databases run in Sail's containers.

Status: implemented and tested end to end (see §8). Workspaces for Sail projects are out of scope (§7).

1. Why Yard and Sail collide

Yard is "native binaries + nginx in front + *.test". Sail is "Docker Compose + everything in containers + localhost:80". Used side by side without integration:

2. Experiments (Docker Desktop 29.9.2, Apple Silicon, Sail from a real project)

Also verified in the sources:

• vendor/bin/sail sources .env, exports WWWUSER/WWWGROUP (used by the image build) and defaults APP_SERVICE to laravel.test. sail share uses http://host.docker.internal:$APP_PORT, so APP_PORT must stay a plain number (no 127.0.0.1: prefix trick).
• Sail's compose.stub already adds extra_hosts: host.docker.internal:host-gateway and reads SAIL_XDEBUG_MODE.
• laravel-vite-plugin (1.x) binds 0.0.0.0:${VITE_PORT} and writes http://localhost:${VITE_PORT} to public/hot when LARAVEL_SAIL is set.
• php artisan serve (Sail's web server) runs PHP as SAPI cli-server, which dump-loader.php treats as an HTTP request.

3. Design principles (ease of use first)

1. Zero configuration. Yard detects a Sail project (laravel/sail in composer.json + a compose file). The inspector shows a Sail section with one switch: Run with Sail. Yard never switches a project on its own.
2. One click. Turning it on assigns free ports, updates .env, creates the .test proxy (HTTPS if the site is secured) and starts the containers.
3. Start on visit. If the containers are stopped, myapp.test shows a "Starting Sail…" page that starts them and reloads when the app answers — the same idea as the existing 502 "Yard is fixing this site" page. If Docker Desktop / OrbStack is installed but not running, Yard opens it first.
4. No lock-in. Ports are pinned in .env, so ./vendor/bin/sail up in a terminal gives the same result and myapp.test keeps working. Turning the switch off restores every .env value Yard changed.
5. Yard never installs Docker (no Homebrew, nothing compiled by Yard). It explains what's missing.
6. Same commands. yard php … / yard composer …, Studio's terminal, Tinker, queue and dev server, and the coding agents run inside the container for Sail sites, so docs and agent prompts stay the same.

4. Architecture

Browser ─► myapp.test (Yard DNS) ─► nginx (Yard CA cert)
                                     ├─ /yard-studio → Studio (4421)
                                     └─ / → proxy_pass http://127.0.0.1:<APP_PORT>  ─► laravel.test container
                                          502 → /yard-error/sail.html → POST /api/sail/:site/up
container ─► host.docker.internal:2525 (Yard Mail), :2304 (Insights ingest)

4.1 Ports

On enable Yard reads every published port variable from the compose files (APP_PORT, VITE_PORT, FORWARD_DB_PORT, FORWARD_REDIS_PORT, …). A value is reassigned when it:

• is one of Yard's own ports (HTTP/HTTPS, API, Studio, dump, mail, DNS) or a Yard service port, or
• is used by another Sail site registered in Yard, or
• answers a TCP connect() on 127.0.0.1 while this project's containers are not running (E2).

New ports are searched from 8100 for APP_PORT and from default + 10000 otherwise (3306 → 13306), skipping ports in use. Ports that are free are left as they are, so projects that already set their own ports (e.g. APP_PORT=8081, FORWARD_DB_PORT=33060) are not touched.

4.2 .env changes (all reverted on disable)

The original values (or "unset") are stored in sites.json (SiteRegistry.sail[name].originalEnv), not in a file in the project. If the user edited one of those keys after Yard did, Yard keeps the user's value.

4.3 Override compose file (<Yard>/sail/<site>.yml)

Adds Yard's features to the app service without touching the project's compose file. Only read-only mounts — no environment variables, because artisan serve drops them (E7):

sail-prepend.php exports env.php into $_SERVER/getenv(), sets HTTPS=on for requests that came through Yard's proxy over HTTPS (X-Yard-Proxy + X-Forwarded-Proto: https; Laravel doesn't trust proxies by default, so URLs would otherwise be http:// — mixed content), then loads the dump loader, which sends to YARD_DUMP_HOST with Host: 127.0.0.1 (accepted by Yard's DNS-rebinding check).

4.4 Commands

5. Decisions

Supervised queue, scheduler and broadcasting workers pass the complete dockerCommandLine to the shell. That command already puts Docker's environment assignments before its own exec; prepending another exec would make the shell treat PATH=… as the executable. SailProjectRuntimeTests launches all three roles through a disposable recording Docker client, including restart, environment/quoting and tagged stop.

6. Failure states shown to the user

7. Out of scope / next steps

• Workspaces for Sail projects (each clone needs its own COMPOSE_PROJECT_NAME and ports).
• New Application → Sail (run artisan sail:install --with=… with Yard's PHP).
• Xdebug switch mapped to SAIL_XDEBUG_MODE.
• Yard Mail as an opt-in mailer for Sail sites (MAIL_HOST=host.docker.internal, MAIL_PORT=2525).
• Vite over HTTPS with Yard's certificate inside the container.

8. Implementation status

See §4 for the files. Unit tests: Tests/YardKitTests/SailTests.swift (detection, port parsing and allocation, .env round trip incl. a file without a final newline, user SAIL_FILES, Yard service ports, override file, PHP version detection, compose output parsing, warning filter, nginx config incl. nginx -t).

End-to-end (2026-11-05, Docker Desktop 29.9.2): a copy of a real Laravel 12 + MySQL + Redis + Mailpit Sail project, with an isolated YARD_HOME (path with a space), the app on its own ports and a real nginx:

Not covered end to end: Vite in the container (same exec/stop mechanism as the queue, which was verified) and Safari with HMR on an HTTPS site (§5). Seen once: right after Yard's PHP runtime files were replaced under a running container, one request got a 502 (upstream prematurely closed connection); the next requests were fine.

DockerEnvironmentTests uses a compiled multicall fixture with two symlink levels and paths containing spaces. It checks invocation identity, credential-helper PATHs, dangling links, launch failures, daemon connection errors, timeouts and old status JSON. YARD_DOCKER_CLIENT_PROBE=/path/to/docker adds a read-only --version probe of an installed CLI; it does not contact the engine or manage containers.