Discussion: multi-process apps and the single-start-command model (Laravel as the case study)

[sudanese]

Context

Opening this as a discussion rather than a bug report, because the interesting question underneath it seems to be about the app model generally rather than about Laravel specifically.

I traced how PHP stacks are built and run today to see where Laravel actually stands. Verified against 210d5eb.

The laravel and symfony stack entries are identical in every field except name and detection (packages/core/src/stacks.ts:678 and :692) — same category, outputDirectory, defaultPort, defaultBuildCommand, and byte-for-byte the same defaultStartCommand. Laravel support today is the generic PHP recipe plus a display name and an icon.

That recipe runs a single web role — php-fpm and nginx in one container — which is right for a plain PHP app. Laravel isn't a plain PHP app: a production deployment is a web role, a queue worker, a scheduler, and a release step. Three consequences, each checkable in a minute:

1. A deploy discards everything the app has written.
StackDefinition (stacks.ts:162) has no volume or persistent-path concept — grep -ci volume packages/core/src/stacks.ts returns 0, and the app deploy path creates containers with no volume mounts at all.

This is worse than it first looks, because of what current Laravel defaults to. The shipped .env.example on 13.x is DB_CONNECTION=sqlite, SESSION_DRIVER=database, CACHE_STORE=database, QUEUE_CONNECTION=database. So for an app deployed on stock defaults, the entire application database — rows, sessions, cache, queued jobs — is a container-local file at database/database.sqlite, and it's gone on the next deploy. Uploads, compiled views, and logs under storage/ go with it.

The reason this is quiet rather than loud is that pdo_sqlite is compiled into the official php:* base images, so the app boots, serves traffic, and looks healthy.

Worth noting a storage/ volume alone wouldn't fix this — database/ is a sibling of storage/, not inside it.

The primitive does already exist one layer over: the service catalog has a defaultVolumes field used by 20 entries — e.g. local-service-catalog.ts:328 gives MinIO defaultVolumes: ["minio_data:/data"], and the services deploy path does mount volumes. Services can declare default volumes; app stacks can't. So possibly less "add a new concept" than "is the asymmetry deliberate" — which is part of what I'm asking.

2. pdo_mysql is the only driver the recipe installs, so PostgreSQL apps can't connect.
packages/adapters/src/runtime/docker-build-plan.ts:144 and :151 hardcode docker-php-ext-install pdo_mysql. The comment at :142 is upfront that this is the common denominator and that app-specific extensions are a follow-on, so this looks like a known edge rather than an oversight — flagging it mainly because it's what makes the sqlite default above silently "work". Also absent: pcntl (Horizon requires it), redis, bcmath, intl, zip, gd, opcache.

Minor related note: the php language entry pins php:8.3-cli / php:8.3-fpm (stacks.ts:82-83). Laravel 13's minimum is PHP 8.3, so that satisfies it exactly — but with no headroom for an app or dependency wanting 8.4+.

3. No queue worker, no scheduler, no release phase.
queue:work, schedule:run, schedule:work, and migrate --force have zero occurrences anywhere in the repo. A deployed Laravel app therefore doesn't process queued jobs, doesn't run scheduled tasks, and doesn't migrate — all silently rather than erroring, which is the part that makes them hard to notice. Assets aren't built either (no Node stage in the PHP branch), so an app using Vite ships without compiled CSS/JS.

The part I'd like to discuss

These don't feel like three independent bugs. StackDefinition allows exactly one defaultStartCommand, so a stack can't express "one image, several runtime roles" even if the extensions and the volume existed. Laravel is the clearest case, but the shape recurs — Rails (Sidekiq or Solid Queue, plus cron), Django (Celery worker plus beat), and anything else where the web process isn't the whole app.

So the question:

Is the single-process app model a deliberate boundary — with multi-process apps expected to use --type services and bring their own Compose file — or is "a stack declares multiple runtime roles" something you'd want in the app model eventually?

Three shapes seem defensible, and I genuinely don't know which fits openship best:

• Roles in the stack definition. openship detects Laravel and the worker and scheduler simply exist — consistent with how the rest of stack detection behaves, and the zero-config promise holds. Cost: a real change to the runtime model, and it would need to compose with any multi-node direction.
• A process supervisor inside one image. One container per app, with a supervisor running nginx, php-fpm, the worker(s) and the scheduler side by side. The appeal is that the deployment model doesn't change at all — openship still builds one image and runs one container, and everything above stays a build-time concern. Cost: roles can't be scaled or restarted independently, and a crashed worker isn't visible from outside the container unless the supervisor surfaces it. Worth saying this is a proven shape rather than a hypothetical — it's the arrangement Coolify recommends for Laravel, via a repo-level config that layers Supervisor into the container.
• Keep apps single-process, push the rest to --type services. Simplest model, clearest boundary. Cost: the auto-detected Laravel path stays quietly incomplete for anything using queues or scheduling, which is most production apps — and since detection succeeding reads as "this is supported", users probably won't realise.

If it's the third, that's a completely reasonable answer and largely a documentation problem — worth saying plainly that queues and scheduling need the services path.

The runtime base matters for all three

Something that cuts across whichever shape you'd pick, and which I think is the highest-leverage change independent of the model question: the generated Dockerfile builds on the official php:*-fpm image and adds nginx via apt. That image is a fine starting point but it isn't a production process host, and two gaps bite specifically once anything other than a web process exists:

• Signal handling. A queue worker needs SIGTERM to mean "finish the current job, then exit". Under a naive php-fpm -D && nginx launch there's no supervision tree propagating signals, so a container stop can kill a worker mid-job. For a payment or email job that's a real correctness problem, not a tidiness one — and it's invisible until it happens under load.
• Non-root execution. The generated image runs as root, which is worth avoiding regardless of the rest.

Purpose-built production PHP base images exist that solve both — serversideup/php is the widely used one (MIT, vendor-neutral): non-root by default, S6 process supervision with correct signal propagation, native healthchecks, env-var configuration, and separate fpm-nginx and cli variants that map cleanly onto the web / worker / scheduler split. It also handles migrations at container boot via AUTORUN_ENABLED with AUTORUN_LARAVEL_MIGRATION_ISOLATION, which is replica-isolation-aware by construction — a stronger guarantee than a release-script migrate --force gives you.

Mentioning it because the S6 supervision is what makes the supervisor-in-one-image option cheap rather than something you'd hand-roll, and the signal handling is what makes the multi-role option safe. So the base-image choice isn't independent of the design question — it partly determines which shapes are easy.

One related question, since it shapes any answer: #163 asks how volumes behave once containers can reschedule across nodes. If there's already a view on that, it probably constrains whether a stack-declared volume is the right primitive at all.

On storage, since it isn't one thing

Noting this in case it's useful for #188 too — storage/ is several kinds of data with different correct answers, and only some can live in object storage:

Path	What it is	Can it go to S3?	Container-appropriate answer
database/database.sqlite	the whole DB on stock Laravel 11+ defaults — incl. sessions, cache, jobs	❌ no	a real database service
storage/app/, storage/app/public/	user uploads	✅ yes	S3 — effectively required above 1 replica
storage/framework/cache/, sessions/	only when drivers are set to file	❌ no	Redis or database
storage/framework/views/	compiled Blade templates	❌ never — no driver exists	ephemeral; recompiled on demand, optionally pre-warmed with view:cache
storage/logs/	application logs	❌ no	stderr
bootstrap/cache/	where optimize writes its caches	❌ no	writable at runtime — the deployment docs call out bootstrap/cache alongside storage as directories the app must be able to write

So a well-configured containerised Laravel app needs very little persistent local storage — real DB service, uploads to S3, cache and sessions to Redis, logs to stderr, compiled views disposable. But a stock app isn't configured that way, and a stock app is what openship gets when someone points it at a Laravel repo and presses deploy.

Which suggests both paths matter rather than one replacing the other: something local as the zero-config correctness floor, and object storage as the path the platform steers people toward as they scale. They're also coupled — a local volume with more than one web replica gives split-brain uploads, invisible intermittently across containers and presenting as random 404s.

Encouragingly most of the machinery exists: packages/adapters/src/backup/destinations/s3.ts is a complete S3-compatible client (AWS, R2, Wasabi, B2, MinIO, Spaces, Ceph, Storj, path-style addressing, multipart), and MinIO is in the service catalog. What's missing is wiring a provisioned bucket to an app's filesystem config — #188's territory rather than something to duplicate here.

If the direction is "yes, eventually"

Sketching roughly what it would involve, only to make the discussion concrete — not a plan I'm proposing to execute:

1. Laravel-appropriate PHP extensions, a Node build stage when package.json has a build script, and some answer for persistence.
2. A release phase — commands running once per deploy, after build and before cutover, failing the deploy if they fail. Generic across stacks; for Laravel on 13.x that's migrate --force, optimize (the single command that caches config, events, routes and views), storage:link, and reload — the last being 13's umbrella for cycling long-running services, superseding queue:restart for deployment purposes since it also covers Reverb and Octane. (Or fewer of these, if the base image handles migrations at boot as noted above.)
3. Whichever multi-role shape follows from the question above.
4. Laravel ships a /up health route out of the box (configurable in bootstrap/app.php), so a default healthcheck is close to free for any app on a current skeleton.

Related

• Clarification needed: Multi-node clustering storage and volume handling strategy #163 — multi-node volume/storage strategy.
• Feature Request: Native Object Storage Support #188 — native object storage. Reads as the other half of the storage picture rather than an alternative: S3 covers uploads and becomes necessary past one replica, while compiled views are unconditionally local and the stock defaults are local too.
• Deploy Hooks (like Vercel/Railway) #206 — deploy hooks. Different thing despite the similar name, flagged only so the terminology doesn't collide: that's an inbound trigger to start a deploy, whereas the release phase above runs during one.

Mostly I'd like to know whether multi-process app support is on the roadmap or deliberately out of scope, since that determines whether the rest is worth discussing further. Happy to be told the services path is the intended answer.

[Hydralerne]

hello, the multi process app is supported, with small bottleneck we will fix: it only work in case of monorepo / docker compose
but anyway, we will review all these samples this week, our focus was to establish the infra, most tests happend on nodejs based projects, so we glad to provide the required support for other stacks too, if you have any suggestion / idea would help us become laravel native support, would be glad to Discuss it

[sudanese]

Hi, thanks for the great product, and for taking time on the samples review.

I pointed Claude fable/opus at a sample empty Laravel app to see how far it could get deploying it. Here's what came out, in case it helps.

Two things block it. The second one has no workaround.

1. A fresh laravel new is detected as vite

Scanning it gives:

{
"stack": "vite",
"category": "frontend",
"buildImage": "node:22",
"outputDirectory": "dist",
"port": 5173,
"startCommand": "",
"packageManager": "composer",
"installCommand": "composer install --no-dev --optimize-autoloader"
}

Odd part is packageManager and installCommand come back as composer, so it clearly sees the PHP side, but the stack still lands on vite.

To narrow it down we copied just artisan and composer.json into an empty folder, same project minus vite.config.js and package.json, and scanned that:

{ "stack": "laravel", "category": "fullstack", "buildImage": "php:8.3-cli", "outputDirectory": "public", "port": 8000 }

All correct. So Laravel detection works fine, it just never gets reached when Vite files are present. Laravel has shipped Vite in the default skeleton since v9, so this hits pretty much every Laravel app. Probably not only Laravel either, anything using Vite for assets on top of a backend framework would land the same way (Rails with vite_rails, Django with a Vite frontend).

Effect is the Vite path leaves startCommand empty, so the deploy gets refused up front with Missing required fields: start command. Setting the framework to Laravel by hand clears that, so everything downstream is fine.

2. PHP 8.3 is too old for a current Laravel app, and can't be changed

With the framework set manually, the Docker build fails:

symfony/clock v8.1.0 requires php >=8.4.1 -> your php version (8.3.32) does not satisfy that requirement.
symfony/console v8.1.1 requires php >=8.4.1 -> your php version (8.3.32) does not satisfy that requirement.
symfony/css-selector v8.1.0 requires php >=8.4.1 -> your php version (8.3.32) does not satisfy that requirement.

A current laravel new pulls in Symfony 8.1 components needing PHP 8.4.1+, but the images are pinned at 8.3.

We tried setting buildImage to php:8.4-cli. The builder picked it up, but the generated Dockerfile still had:

FROM php:8.4-cli <- builder, our override
FROM php:8.3-fpm AS runtime <- unchanged

We couldn't find a runtimeImage setting anywhere, so as far as we could tell there's no way to move the runtime off 8.3. That's what makes this a hard stop rather than just an annoyance.

Also noticed the runtime installs pdo_mysql only, so Postgres apps presumably can't connect, though we didn't get far enough to confirm.

Two things that tripped us up along the way

• Deploying to my own server failed with No GitHub token available for this request (purpose: remote). Setting the clone strategy to api-host fixed it since my machine already had git access. Wasn't obvious that was the knob.
• Free .opsh.io domains need Openship Cloud, so a self-hosted deploy needs a custom domain set first.

What we couldn't check

We never got a container running, so we couldn't test the things I mentioned earlier, whether the queue worker and scheduler run, whether storage/ and the sqlite database survive a redeploy. Those are still open questions rather than findings.

im already using other service for these deployment ,but got excited about openship and wanted to try it , understand it mostly geared nodejs :)

[sudanese]

Following up on my last comment — I kept going and got it deployed. It's live now on my own server, real domain, valid Let's Encrypt cert, HTTP→HTTPS redirect. It took six manual steps, two of which have to be repeated on every deploy.

It's a long comment, so a summary first and the detail below. All of it is from actually running things on Openship 0.4.5 — Laravel 13.22 from laravel new, Ubuntu 24.04, Docker runtime.

Summary

#	What	Workaround?
1	Adding any service destroys the app container and the deploy reports success. Not Laravel-specific — reproduces on a bare Node app in 2 minutes.	remove every service
2	Env changes stop reaching the app once a service exists. "Redeploy" and "Refresh env" both report success and don't apply.	same
3	No volumes on app containers — on stock Laravel defaults the whole database is destroyed every deploy	use a DB service (but see 1)
4	No release phase — nothing runs migrate, so a fresh deploy 500s until you docker exec in	manual, every deploy
5	Behind the edge, every Laravel app renders unstyled — TLS is terminated so Laravel emits http:// asset URLs and the browser blocks them	one line in the app
6	Stock laravel new detected as vite; PHP pinned at 8.3 (too old); only pdo_mysql; no zip, so composer can't extract	supply own Dockerfile
7	certbot isn't installed, and the failure surfaces as a DNS-looking verified: false	apt install certbot

1–4 are the ones I'd care about. 1 and 2 are the same root cause and I think are the most serious — doing the right thing (adding a real database) either takes the site down or silently ignores your config. 3 and 4 have no workaround at all.

Minimal repro for #1, no Laravel needed: deploy any trivial app → confirm it's running → add any service from the catalog → deploy → the app container is gone, deploy says success.

5–7 all have workarounds and are mostly a docs/sample matter. A tested Laravel Dockerfile that handles 6 is at the bottom.

---

---

⚠️ Read this one first — adding a database takes the app offline

I hit this after everything below, while testing with a real Postgres instead of the sqlite default. It's the most serious thing I found, so putting it at the top.

The first deploy after adding a service to a single-app project destroys the app container and never rebuilds it — and reports success.

What I did: added Postgres and MinIO to a working, live Laravel project (200, valid cert, everything healthy), then deployed.

What happened:

• The site went to 502 and has stayed there
• Zero app containers exist — docker ps shows only postgres and minio
• Every deploy since reports "Deployment Successful", Status: Ready, 2/2 running
• The project page still shows ● Live with the domain listed
• Redeploying does not bring it back — I've tried several times, from the API and from the Deploy button in the UI

The deploy log shows the path being chosen automatically:

→ Services require the Docker runtime — running this service deploy on Docker.
Build phase complete. Starting project service deployment...
Preparing shared service group for project services...
Service "postgres" unchanged - kept running (carried forward).
Service "minio" unchanged - kept running (carried forward).

It deploys the services and never rebuilds the app. The deployment panel now shows Type: Compose, and the pre-deploy warning says "This project has 2 services with exposed ports" — the app isn't counted at all any more.

Worth noting projectType in the API still reads null, so the Compose classification looks like it's derived at deploy time from "does this project have services?" rather than stored. Once a project has one service, it seems the app stops being part of the deploy.

It isn't caused by a broken service. MinIO was crash-looping (see the sh -c note further down), so I removed it and deployed again with only a healthy Postgres — still no app, still 502. Then removed Postgres too and deployed again, and the app came straight back:

Services on the project	App container	Site
postgres + minio (minio crash-looping)	0	502
postgres only (healthy, running)	0	502
none	1 — deployed normally	200

So it's not the state of the service. Removing every service is the only thing that brought the app back, which isn't much of a workaround when the service is your database.

It has nothing to do with Laravel, or with my custom Dockerfile. I wondered whether I'd caused it myself, so I built a control: a throwaway Node project — a 12-line http.createServer and a package.json, no Dockerfile at all, so Openship generated its own. Deployed it, confirmed the container was running, added a single Valkey service from the catalog, deployed again:

BEFORE:  openship-control-node-dep_z7Hf7vLnMWzQ-L8l  (Up 34 seconds)
AFTER:   openship-control-node-cache                 (Up 16 seconds)
         app containers: 0
log:     Stopped previous single-app container (e3098485ccaf).

Same line, same outcome, no PHP involved and one healthy service. So the minimal repro is framework-agnostic and takes a couple of minutes:

1. Deploy any trivial app, confirm it's running
2. Add any service from the catalog
3. Deploy again — the app container is gone and the deploy reports success

It fires on the transition, not on every deploy. Worth being precise, because it took me a while to pin down. The destructive step only happened once, and the log line for it was:

Stopped previous single-app container (05351c531c5d).

Later deploys with the same services present left the app alone — I've since redeployed several times with Postgres and Valkey attached and the app container was untouched, site stayed 200.

Looking at where that message comes from (compose/deploy.service.ts, around the prevWasServices check), the services deploy path destroys the previous container when the predecessor was a single-app deploy. That's presumably intentional — the comment right above it mentions fixing a related case where adding a service stopped the service it had just started. The problem is what happens next: the services path doesn't build the app, so once that container is destroyed nothing recreates it, and every subsequent deploy skips the reap because the predecessor is now a services deploy.

Net effect: the first deploy after adding a service to a single-app project takes the app offline permanently, while reporting success. After that it's stable — just stable with no app running.

The quieter version of the same problem: env changes stop reaching the app. Because a services deploy doesn't rebuild the app, the app container just stays as it was. I changed DB_CONNECTION from sqlite to pgsql (plus host/user/password and Redis settings), deployed, got ready — and the container was still the same one from 32 minutes earlier, still reading DB_CONNECTION=sqlite. No warning, no indication the new values weren't applied.

That's probably the more common way to hit this than the outage: you point your app at the database you just added, deploy, see "Deployment Successful", and nothing has changed.

I tried the Refresh env option under the Redeploy dropdown too, which looked like exactly the right tool — recreate the container with new env, no rebuild. It also reports success and also doesn't touch the app; the log is identical to a normal redeploy, recreating the service containers and never mentioning the app. So both "Redeploy Project" and "Refresh env" go down the services branch once any service exists.

Meanwhile the env panel shows all the values stored correctly (DB_CONNECTION=pgsql, DB_HOST=postgres, SESSION_DRIVER=redis, REDIS_HOST=valkey), so from the UI everything looks configured — it's just that nothing carries them into the running container. As far as I can tell the only route is removing every service so the deploy goes back down the single-app path, which also removes the database you were trying to connect to.

A concrete example of where that leaves you: I registered a user on the deployed app to check it worked. That account went into the SQLite file inside the app container — the Postgres and Valkey services were up, healthy, reachable on the project network, and completely idle (0 keys in Valkey, no users table in Postgres). The app was still running its original DB_CONNECTION=sqlite. So the data landed in the one place with no volume behind it, while the durable database sat unused.

The reason I'd rank this above everything else: adding a database is the correct thing to do — it's the fix for the sqlite data-loss problem further down. So the user does the right thing, gets a green "Deployment Successful", and either their site is down or their config silently didn't apply. There's no error anywhere to lead them to the cause.

One smaller related thing: deleting a service leaves its named volume behind. I deleted the Postgres service and re-added it from the catalog with different credentials, and the new POSTGRES_USER/POSTGRES_PASSWORD were silently ignored — Postgres only runs initdb on an empty data directory, so the old role and password were still in force while the UI showed the new ones. Keeping the volume is arguably the right default, but the config then says something untrue.

---

Credit first — the infra side was smooth

• Adding the server and installing Docker was completely hands-off
• The port-conflict detection is genuinely excellent. On an earlier attempt against a server already running nginx, it detected the conflict, listed all three sites it would affect with their document roots, and let me cancel. Most tools would have just taken port 80.
• The clone fallback: it noticed the server had no GitHub identity, fell back to cloning on the API host and rsyncing the context, and told me how to set it up properly
• Domain routing, cert issuance and the redirect all worked first try

The infrastructure layer feels solid. Everything below is the framework layer.

---

1–2. Detection and PHP version — covered in my last comment

Briefly, for continuity: a stock laravel new scans as vite (so startCommand is empty and the deploy is refused), and the generated Dockerfile can't build a current Laravel app — PHP 8.3 vs a lock file needing ≥8.4.1, only pdo_mysql installed, no zip/unzip so composer can't extract, and no Runtime Image field to change the 8.3 runtime.

The way out for all of it: Openship uses a repo-root Dockerfile when one exists instead of generating its own. Mine is at the bottom of this comment — it deploys and runs cleanly and might be a reasonable basis for a Laravel sample.

3. Set env vars in the platform

Expected, just noting it in sequence — .env isn't shipped in the image (correctly), so APP_KEY etc. have to be set in Openship or the app 500s with MissingAppKeyException.

4. Trust the proxy, or every Laravel app renders unstyled

This one is Openship-specific and I think it will hit every Laravel user. It's the finding I'd most want in the docs.

The edge terminates TLS and forwards over plain HTTP. Laravel 11+ trusts no proxies by default, so it ignores X-Forwarded-Proto, believes the request is HTTP, and generates HTTP asset URLs on an HTTPS page:

<!-- page served over https, assets referenced over http -->
<link href="http://myapp.example.com/build/assets/app-B27gqgtm.css">

The browser blocks those as mixed content, so the site renders as raw unstyled HTML.

What makes it nasty is how healthy everything looks while it's broken. The page returns 200. /up returns 200. Fetching the CSS directly over https returns 200. Nothing errors anywhere. The natural suspicion is your own Vite build, which is the wrong place to look.

Fix is one line in bootstrap/app.php:

->withMiddleware(function (Middleware $middleware): void {
    $middleware->trustProxies(at: '*');
})

Worth documenting prominently or baking into the Laravel sample. Note that setting APP_URL to https does not fix it on its own — asset() takes its scheme from the request, not from config.

5. Shell in and run migrations — every deploy ⟵ recurring

The app builds, deploys, the container starts, /up returns 200. But every real request 500s, because nothing ever runs php artisan migrate. There's no post-build/pre-traffic step to hang it on.

I fixed it with docker exec into the container:

php artisan migrate --force && php artisan optimize

and / went 200 immediately. So that single missing step is the whole gap — but it has to be redone after every deploy, since each one is a fresh container.

6. apt install certbot — the SSL error points at the wrong thing

Domain verification failed with verified: false, which reads like a DNS problem. The real cause was only visible in the response body:

"message": "bash: line 1: certbot: command not found"

Openship shells out to certbot for verification but only auto-installs Docker. After apt install certbot, verification returned "Domain verified — certificate issued" and SSL came straight up. Worth either installing certbot alongside Docker or surfacing that message — I'd have gone off debugging DNS otherwise.

---

The two I couldn't work around

Everything above I could solve myself. These two I couldn't, and they're the reason for the write-up.

Nothing persists. docker inspect <container> --format '{{json .Mounts}}' returns NONE — no volumes at all. I tested it directly: wrote a row into the database and a file into storage/app, redeployed, and both were gone along with the sqlite file itself. On stock Laravel 13 defaults (DB_CONNECTION=sqlite, sessions/cache/queue all on database) that means the entire application database is destroyed on every deploy. Quietly, too — pdo_sqlite is compiled into the base image, so the app boots and looks healthy.

No release phase. Per point 5. Migrations are the obvious case but it's more general — on our own apps we also run a couple of idempotent seeders and a cache clear every deploy, so a migrations-only hook wouldn't cover it. Somewhere to run a few commands once per deploy, after build and before traffic moves over, would.

I verified both on two different servers to rule out anything about my setup.

---

Smaller things noticed

• composer install --no-dev --optimize-autoloader runs twice in the same layer, tagged step=install and again step=build — the Laravel entry seems to use the same command for both. Harmless but redundant, and it means there's no asset build step, so a Vite app deploys without compiled CSS/JS.
• Because buildCommand runs at image build time, anything running php artisan optimize there bakes config.php into the image — and once config is cached Laravel stops reading env entirely. Worth making sure cache-warming happens at container start rather than build.
• A service command is wrapped in sh -c rather than split into argv, which breaks any image whose entrypoint inspects $1. MinIO is the case I hit — command: server /data --console-address :9001 produced Cmd: ["sh","-c","server /data …"], and MinIO's entrypoint prepends minio when $1 != "minio", so it ran minio sh -c "server /data …" and crash-looped on 'sh' is not a minio sub-command. Compose would pass ["server","/data",…] and it'd work. There's no way round it from the UI — advanced only exposes healthcheck, so there's no entrypoint override. Postgres was fine only because it needs no command.
• Setting Build Image to empty fails preflight with Missing required fields: build image, even when a repo Dockerfile supplies its own FROM.
• A malformed body on PATCH /projects/:id/env returns a 500 rather than a validation error.
• The server detail page shows Auth: Password for a server registered with agent auth — the stored record says agent.

---

The Dockerfile

This is the exact file, tested end-to-end — builds, deploys, serves over HTTPS, /up returns 200.

# Laravel on Openship — replaces the auto-generated Dockerfile.
#
# Openship uses a repo-root Dockerfile when one exists, and only synthesizes
# its own when none is found. Building here lets us pick the PHP version and
# install the extensions Laravel actually needs.
#
# The runtime deliberately provides /etc/nginx/app.conf.template so Openship's
# default Laravel start command works unchanged:
#   envsubst '$PORT' < /etc/nginx/app.conf.template > /etc/nginx/conf.d/default.conf
#     && php-fpm -D && nginx -g 'daemon off;'

# ── Stage 1: PHP dependencies ────────────────────────────────────────────────
# Must run BEFORE the asset build: resources/css imports Flux's stylesheet from
# vendor/, so npm run build fails without vendor/ present.
FROM php:8.5-cli AS vendor
RUN apt-get update && apt-get install -y --no-install-recommends \
      libzip-dev libicu-dev libpq-dev unzip \
 && docker-php-ext-install zip intl bcmath pcntl pdo_mysql pdo_pgsql \
 && rm -rf /var/lib/apt/lists/*
COPY --from=composer:2 /usr/bin/composer /usr/bin/composer
WORKDIR /app
COPY composer.json composer.lock ./
RUN composer install --no-dev --optimize-autoloader --no-interaction --no-scripts
COPY . .
RUN composer dump-autoload --optimize --no-dev

# ── Stage 2: front-end assets (Vite) ─────────────────────────────────────────
FROM node:22-slim AS assets
WORKDIR /app
COPY package.json package-lock.json* ./
RUN npm ci --no-audit --no-fund
COPY . .
COPY --from=vendor /app/vendor ./vendor
RUN npm run build

# ── Stage 3: runtime (php-fpm + nginx) ───────────────────────────────────────
FROM php:8.5-fpm AS runtime
RUN apt-get update && apt-get install -y --no-install-recommends \
      nginx gettext-base libzip-dev libicu-dev libpq-dev \
 && docker-php-ext-install zip intl bcmath pcntl pdo_mysql pdo_pgsql \
 && rm -f /etc/nginx/sites-enabled/default \
 && rm -rf /var/lib/apt/lists/*

WORKDIR /app
COPY --from=vendor /app /app
COPY --from=assets /app/public/build /app/public/build

# storage/ and bootstrap/cache must be writable by the php-fpm user.
# database/ matters only for the sqlite default (irrelevant once you point
# DB_CONNECTION at a real Postgres/MySQL service) — but it's what `laravel new`
# ships with, so leave it writable. SQLite creates -journal/-wal files NEXT TO
# the db file, so the DIRECTORY must be writable, not just the file. Without
# this every write fails with "attempt to write a readonly database", which
# surfaces as a 500 on anything touching the session or DB.
RUN mkdir -p storage/framework/{cache,sessions,views} storage/logs bootstrap/cache database \
 && chown -R www-data:www-data storage bootstrap/cache database \
 && chmod -R 775 storage bootstrap/cache database

# nginx template consumed by Openship's start command via envsubst.
RUN printf '%s\n' \
  'server {' \
  '    listen ${PORT} default_server;' \
  '    root /app/public;' \
  '    index index.php index.html;' \
  '    client_max_body_size 32M;' \
  '    location / { try_files $uri $uri/ /index.php?$query_string; }' \
  '    location ~ \.php$ {' \
  '        fastcgi_pass 127.0.0.1:9000;' \
  '        fastcgi_index index.php;' \
  '        include fastcgi_params;' \
  '        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;' \
  '    }' \
  '    location ~ /\.(?!well-known).* { deny all; }' \
  '}' > /etc/nginx/app.conf.template

EXPOSE 8000
CMD ["sh", "-c", "envsubst '$PORT' < /etc/nginx/app.conf.template > /etc/nginx/conf.d/default.conf && php-fpm -D && nginx -g 'daemon off;'"]

Two notes on it: opcache is already compiled into php:8.5, so adding it to docker-php-ext-install fails the build; and redis needs pecl install redis rather than docker-php-ext-install.

Also worth a .dockerignore alongside it, or the build context picks up vendor/, node_modules/, the local .env and any dev sqlite file:

.git
node_modules
vendor
.env
auth.json
storage/logs/*
database/*.sqlite
tests

Happy to test anything against a real app — I've got a box set up for it now.

[Hydralerne]

thank you for your feedback, we will work on this soon

[sudanese]

Follow-up on the state-desync side of this. Same test project as above, left running since the last report.

The dashboard now shows the app as Stopped, with Logs Error: Service has no running container — while the site serves fine. Both are true at once, and the reason turned out to be more concrete than "the UI is stale".

What's actually on the box

openship-openship-laravel-test-dep_YsF9N_5RNkQ29q2w   Up 31 hours   127.0.0.1:20000->8000/tcp

Container ff6defd64f1a, image bld_YI7w_51KPeKWgR7y, started 2026-07-28T11:32:58. Serving 200s with fresh session cookies, so it's genuinely executing, not cached.

What the API says is active

GET /projects reports activeDeploymentId: dep_RgIgQaCACNmofHhW.

That deployment's recorded containerId is 24cbcd61d211…. Inspecting it:

name  = /openship-openship-laravel-test-postgres
image = postgres:16-alpine

The app deployment record has the Postgres service container's ID in it. Two of the other recent deployments record container IDs that no longer exist at all.

How it got there

Last eight deployments for the project:

Deployment	buildDurationMs	imageRef	portCheck	status
dep_gKhrWiJmPnd4yhn2	46510	…:bld_bbzsy-TvOomh06AR	listening: true	ready
dep_YsF9N_5RNkQ29q2w ← still serving	8154	…:bld_YI7w_51KPeKWgR7y	listening: true	ready
dep_ovaozY8cMjyf3yWv	0	null	absent	ready
dep_cgUPXgqP__KdUQuE	1	null	absent	ready
dep_yGTIJPVJ2kUZwWSv	0	null	absent	ready
dep_RgIgQaCACNmofHhW ← "active"	0	null	absent	ready

Four consecutive deployments built no image, took ~0 ms, and were each marked ready. activeDeploymentId advanced to each in turn.

The portCheck column is the interesting one: both deployments that really built carry portCheck: [{ port: 8000, checked: true, listening: true }]. All four no-ops have no portCheck field at all. The check that would have caught this is skipped exactly in the case where it was needed.

Why the site keeps working

Routing is by fixed host port — the generated nginx config is proxy_pass http://127.0.0.1:20000, with no deployment identifier in it. Whichever container holds 20000 serves traffic.

So routing is deployment-agnostic while status and logs are deployment-scoped. When the active-deployment pointer moved to a deployment with no container, routing didn't notice and status broke. Nothing reconciles the two afterwards.

Why this is worth more than a wrong badge

• Four deploys reported success and shipped nothing. In this case every deployment carried the same commit, so nothing drifted — but a real code change would have silently not deployed, four times, with a green result each time.
• Rollback to any of those four can't work — imageRef is null, so there's no image to roll back to.
• Restart / Stop resolve to the wrong container, since the active deployment record points at Postgres.
• Logs are unreachable, which is the visible symptom.

This is the same root as the false-Live behaviour reported earlier in this thread, just inverted: there, a broken deployment read as healthy; here, a healthy one reads as stopped. Both come from the recorded deployment state and actual Docker state drifting apart with no reconciliation.

Smallest thing that would have caught it

Refusing to mark a deployment ready when it produced no image and ran no port check would have stopped the pointer moving off the working deployment. A reconcile on status read — compare the recorded container against what's actually running — would catch the drift after the fact.

Happy to pull any more detail off this box; it's a throwaway test project, so I can leave it in this state or try to reproduce from a clean one, whichever is more useful.

[sudanese]

Now that FrankenPHP supervises correctly and propagates SIGTERM (generatePhpDockerfile), a stopped worker drains its in-flight job instead of dying mid-run — which is what makes a queue worker viable at all, and unblocks the rest of this issue. So I'd like to pick up the Multi-role stacks checklist (TODO.md:405-408), still open, and propose a concrete shape for the production Laravel triple — web + queue:work + schedule:work — with a selectable Redis/Valkey backend. The invariant everything below protects: one generated FrankenPHP image, no per-project Dockerfile, run N times with a different Cmd. Web, worker, and scheduler are the same bytes. File:line refs are against 463668e.

The decision on the table

TODO.md:405 frames the fork: roles declared in StackDefinition (auto on detection) vs. keeping apps single-process and pushing extras to --type services. I'd go with roles in StackDefinition, for three reasons:

1. Zero-config survives — the exact property TODO.md:407 warns not to lose. A Laravel app auto-gains a worker + scheduler on detection; the services route means the operator hand-assembles rows and re-types env on every one.
2. It's the shape the existing same-image seam already supports (next section) — small wiring over primitives that exist, not a new subsystem.
3. The scheduler-singleton distinction has to live somewhere before per-service scaling ships. A flat service row can't say "this one is a singleton"; the day scaling lands, a schedule:work row scales like a queue:work row and every due job dispatches N times. role is the natural discriminator to hang max-replicas-1 off. Today per-service replicas doesn't exist on any user-facing deploy config, so the double-fire is latent — which is exactly why the discriminator should exist before it goes live.

Wiring, not a subsystem

Every primitive is already here; they've just never been composed:

• Per-container Cmd override, independent of the build — docker.ts:2166-2169 (if (config.startCommand) Cmd = ["sh","-c", startCommand]). The injection point for a role's command.
• Stable re-tag — tagImage() (docker.ts:2741-2751), today wired only for cross-server adoption. The built tag is stamped with the build session id (docker.ts:836-839) and moves every deploy; one tagImage() call after the build aliases it to a deploy-stable ref.
• Skip-build / skip-pull for openship/-namespaced images — build.service.ts:261-287 + docker.ts:3676-3696. Sibling roles reference the stable tag with zero rebuild.
• One deploy per project today — build-pipeline.ts:1497-1498. The single fan-out point to generalize.

Flow: build once → tagImage() stable alias → one deploy() per role against that one tag with the role's Cmd. Only web gets the HTTP health check + route (deploy-pipeline.ts:1-26); worker/scheduler are container-liveness only. Equivalently, the non-web roles can materialize into the existing MultiServiceDeployConfig service-workload fan-out riding the same skip-build path — then no new orchestration primitive at all.

Shape

StackDefinition (today a single defaultStartCommand, stacks.ts:169-230) gains an optional processes[], auto-populated for Laravel on detection (stacks.ts:698-699 is where the web command comes from today):

processes: [
  { role: "web",       command: <generated FrankenPHP run>,  replicas: 1 },
  { role: "worker",    command: "php artisan queue:work --tries=3 --max-time=3600",
                       replicas: 1, scalable: true },
  { role: "scheduler", command: "php artisan schedule:work", replicas: 1, scalable: false },
]

A processes JSON column on the project row overrides/extends the stack default — that's what the config UI writes. Roles stay per-framework as TODO.md:409 anticipates; Symfony later maps to messenger:consume plus a scheduler equivalent. --max-time=3600 recycles the worker hourly; worker replicas is stored but platform-capped at 1 until per-service scaling exists — the field exists now so scaling doesn't force a schema migration later.

Scheduler = enforced singleton, three layers: schema (role: "scheduler" ⇒ scalable: false, replicas coerced to 1), API (a zod .refine in deployment.schema.ts rejecting scheduler && replicas > 1), and a hard cap of 1 container at deploy fan-out regardless of the stored value.

schedule:work, not a cron sidecar: a long-running loop that sleeps to the minute and dispatches what's due — no OS cron, no crontab baked into the image, same FrankenPHP bytes with only a different Cmd, same clean SIGTERM stop. It must restart to pick up schedule changes, and every deploy restarts it — a non-issue in this model. (Distinct from the release-phase one-shot schedule:run in TODO.md:381-393 — that's the per-minute cron variant and belongs in release hooks; this is the persistent loop.)

Backing store (Redis / Valkey)

A picker that provisions the catalog service and auto-wires the env, structurally a copy of object storage — objectStorageEnvPreset (object-storage.ts:184-193) and buildObjectStorageEnv's laravel branch (:223-233) are the template. A buildCacheEnv laravel preset emits:

REDIS_HOST / REDIS_PORT / REDIS_PASSWORD (secret)
REDIS_CLIENT=phpredis        # the extension is already in the PHP recipe
QUEUE_CONNECTION=redis
CACHE_STORE=redis            # CACHE_DRIVER for Laravel <= 10
SESSION_DRIVER=redis

Valkey is wire-identical (RESP, 6379) — same env values; only the catalog image differs (redis:7-alpine at local-service-catalog.ts:124-136, valkey/valkey:8-alpine at :137-146). Two Valkey gaps to bundle: it has no defaultEnv today (so no password field in the UI), and the backup producer regex REDIS_IMAGE_RE = /^redis(\/|:)/i (backup/producers/redis.ts:30) skips it — a Valkey-backed queue silently has no backups where a Redis-backed one does. Both are one-liners; if not in the MVP they should ship as documented known-gaps.

The binder is a same-project bind, so it is not connectBundle — that path is cross-project by design and rejects source === target (project-connection.service.ts:191-193). Orchestration mirrors bindObjectStorage (project-storage.service.ts:228-301): resolve the service alias + port, read the password straight off the service env (the same read the backup producer already does, backup/producers/redis.ts:47), mergeEnvVars onto the project (app-settings.service.ts:285-289), one redeploy re-materializes all roles. Because it reads credentials directly, it does not block on the generic makeInternalOutput gap (app-settings.service.ts:513-524 returns bare http://alias:port, no creds) — that's adjacent cleanup, not a prerequisite. Env written once on the project + the processes fan-out means web/worker/scheduler inherit one truth — no per-row copies to drift.

What works today (and why it's fragile)

The --type services intermediate from TODO.md:405 works now: two extra kind:"monorepo" rows (same rootDirectory), startCommand = php artisan queue:work … / php artisan schedule:work, plus a Redis catalog service — then hand-setting REDIS_HOST/PORT/PASSWORD + QUEUE_CONNECTION/CACHE_STORE/SESSION_DRIVER identically on all three rows, because no auto-wire exists yet. (Also: redis:7-alpine doesn't act on REDIS_PASSWORD by itself — either --requirepass in the service command or passwordless on the private project network.) The fragilities: the 3-row env hand-sync fails silently (worker consumes a different queue than web enqueues to), the image builds N times (rows share the source tree, not built layers), and nothing marks the scheduler a singleton. That fragility is most of the case for doing it natively.

(The other "today" shape — an image:-only service pinned to openship/<slug>-web:<sessionId>, which deploys with zero rebuild via build.service.ts:261-287 — is a trap: the tag regenerates every deploy (docker.ts:836-839), so the worker silently pins stale. The tagImage() step above is what removes that class of bug in the native path.)

Ordering

Foundation to capstone:

1. The vendor→assets Dockerfile bug, first (a separate fix, landing on its own). This design assumes one correctly-built image gets fanned out to three roles — fan out a broken image and you triple the breakage instead of fixing it once.
2. Per-project env scaffolding, so all three roles share one env instead of three copies.
3. The DB picker — the backing-store picker above is its sibling pattern; natural to land alongside it.
4. This — processes + backing store — sits on top of 1–3.

The backing-store binder itself doesn't block on anything in this list except the env scaffolding.

Worth scoping the substrate once

These four aren't separate features — they're one architecture with a single spine, which is why it's worth sizing the substrate to carry all of it up front rather than retrofitting later. Env scaffolding writes APP_* + safe driver defaults to the project env; the DB picker (DB_URL) and the Redis/Valkey picker both append to that same project env via the object-storage binding pattern; and the processes fan-out means web/worker/scheduler inherit that one env unmodified (getEnvMap → mergeServiceDeployEnv, applied as the lowest, always-present layer, deploy.service.ts:276-287,778). Design the process fan-out to read a project-level env and all four land coherently with zero per-role hand-sync; design it in isolation and the env layer has to be retrofitted. Env scaffolding and the DB picker are their own TODO.md items, so I'd keep their detail on separate threads — I'm only flagging here that the env substrate this design sits on should be scoped to carry them, not just the process commands.

The ask

Two decisions to ratify before any code — they're the expensive ones to reverse once code exists, and everything else hangs off them:

1. processes[] lives on StackDefinition with a project-level override (vs. push-to-services).
2. Singleton enforcement hangs off the role discriminator (schema + zod + deploy cap), shipped before per-service scaling exists.

If both hold, I'll build the MVP: processes[] + Laravel auto-population, the build-once/tagImage()/fan-out deploy path, the enforced-singleton scheduler, and the Redis/Valkey picker with buildCacheEnv + the same-project binder. Natural follow-ups, not MVP: Horizon as an opt-in worker command (Redis-only; it's a supervisor itself, so its replicas stay 1 and /horizon is served by the web role), per-service worker scaling when clustering lands, the Valkey backup regex (REDIS_IMAGE_RE), and the protocol-aware/creds fix to the generic makeInternalOutput internal-connection view.