openship.json

openship.json is a repo-root file that tells Openship how to build, run, route, and scale a project. It mirrors what you'd otherwise set in the deploy wizard, so a repo becomes "ready to ship on Openship" and auto-deploy on push and openship deploy become deterministic — no wizard needed.

When refreshing services for a project with a saved subfolder, Openship uses that subfolder's openship.json when present. Otherwise, it uses the repository-root manifest, preserving existing service definitions and environment defaults. The saved build directory still applies.

Add the $schema line for editor autocomplete and inline validation:

{
  "$schema": "https://openship.io/openship.schema.json",
  "framework": "nextjs",
  "port": 3000
}

Validate it any time with the CLI:

openship config init       # scaffold a starter openship.json
openship config validate   # check it against the schema

It's JSON, not JSONC — no comments, no trailing commas.

Build

Runtime version selection

runtimeVersion is one setting shared by runtime policies; it is not a global PHP enum. The selected or detected stack validates supported versions and chooses matching build/runtime images. Explicit selection currently supports PHP 8.3 and 8.4 for generated Docker builds. Other runtimes keep their existing repository detection and defaults; an explicit unsupported selection fails before a project write or build instead of being ignored.

For the Laravel and Symfony stacks, select a version in the deploy wizard's build settings or declare it in openship.json:

{
  "framework": "laravel",
  "runtimeVersion": "8.3",
  "installCommand": "composer install --no-dev --optimize-autoloader"
}

A new selection keeps Composer installation enabled even when there is no JavaScript asset build. You can disable Build when your source already contains its prepared dependencies.

These are the currently tested selections. Other major/minor or patch selections are rejected. Both selected stages verify their actual PHP major/minor version. The generated recipe checks production Composer requirements in the builder and runtime, including PHP and extensions. Composer's platform check uses the real platform, even if config.platform or the install command's --ignore-platform-reqs pretends otherwise. An incompatible build fails before activation, leaving the current deployment available.

A declared buildImage overrides the managed builder, while the selected FrankenPHP runtime stays fixed. The custom builder must provide the selected PHP version and support the generated Composer/extension setup; known incompatible official PHP tags are rejected immediately and custom images are checked during the build. Changing the version replaces a previously managed builder default, but does not overwrite a custom builder. When you select a different version with a custom builder, update both settings together.

This project-level setting applies to generated Docker builds on self-hosted and managed Cloud Docker destinations. It cannot configure a user-owned Dockerfile, Compose/monorepo service image, bare runtime, static site, or prebuilt image. Explicit selection on these paths is refused; configure PHP in their own image instead. Existing projects and user Dockerfiles without runtimeVersion are unchanged.

The API and SDK accept runtimeVersion in project creation, ensure/update and build options. Send null in project options to restore the default PHP version; custom builder overrides are preserved. Folder scans, the SDK source deployment flow, and openship deploy --folder preserve repository declarations. The CLI validates this field with openship config validate. Version and resolved image references are frozen in each deployment snapshot; rollback reuses that release's retained application image rather than the latest project setting. Openship Edge, TLS, routing and resource monitoring continue through the existing deployment path.

Runtime

Laravel cache warming

php artisan optimize warms Laravel's config, route, event, and view caches. A warmed web role answers each request faster. The default is off, so an existing project keeps its exact web command until it opts in.

Warming helps the web role only. It does not fix cold start, because cold start is dominated by PHP opcode compilation, not cache state. Workers and schedulers gain little, so leave them unwarmed.

Opt-in flag

Set optimize: true to warm the web role. The flag prefixes the web command and keeps the rest of the command unchanged.

{
  "framework": "laravel",
  "optimize": true
}

Warming runs before the server through &&. A failing php artisan optimize short-circuits the chain, so the web role never boots. Opt in only when the command succeeds reliably in your runtime environment.

optimize: true always prepends php artisan optimize && . Do not also put php artisan optimize in a custom startCommand, or it runs twice. The repeat is harmless but wasteful.

Override the web command directly

You can warm the web role without the flag. Override startCommand and keep the exec form. optimize runs first. exec then hands PID 1 to FrankenPHP, so SIGTERM still drains in-flight requests.

{
  "framework": "laravel",
  "startCommand": "php artisan optimize && SERVER_NAME=\":$PORT\" exec frankenphp run --config /etc/frankenphp/Caddyfile --adapter caddyfile"
}

Warm a worker or scheduler

Warming a worker gives a small, one-time benefit, so prefer warming the web role only. To warm a worker anyway, declare it in roles, and keep any other roles you declared there. Prefix its command with php artisan optimize && and keep the exec form. The fields and rules are in Runtime roles.

{
  "roles": [
    { "name": "queue", "kind": "worker", "command": "php artisan optimize && exec php artisan queue:work", "stopGracePeriod": "90s" },
    { "name": "scheduler", "kind": "scheduler", "command": "php artisan optimize && exec php artisan schedule:work", "stopSignal": "SIGTERM", "stopGracePeriod": "10s", "singleton": true }
  ]
}

These are example shutdown budgets. Longer scheduled runs may need a larger grace period on a Laravel version verified to drain.

Custom runtime images

Docker source builds offer a Runtime image field under Advanced build settings. It is a production base image, separate from the builder and the final application image. Omit it in openship.json, or send runtimeImage: null through project options, to restore the managed default.

{
  "framework": "laravel",
  "runtimeVersion": "8.3",
  "runtimeImage": "registry.example.com/team/php-runtime:8.3"
}

The stack selects its Docker recipe, even when a custom image has a different name. A PHP runtime base must provide the selected PHP version, FrankenPHP, install-php-extensions, and the www-data user. The recipe checks these capabilities and Composer's actual platform. Known incompatible official PHP image/version combinations are rejected before settings are saved. Other custom interpreter images compare the actual builder/runtime fingerprint during the build (runtime ABI or version, architecture, and libc where applicable). Compiled-native applications continue through deployment readiness checks. A failed build does not replace the live application.

Overrides must support the generated recipe's shell, directories and package setup. Use your own Dockerfile for a different server implementation or filesystem layout. Project-level overrides are refused for bare runtimes, prebuilt images, static extraction and service-owned Compose/monorepo builds. Those paths manage their images directly.

Omitted options preserve a saved override; null clears it. A version change preserves custom image overrides and validates the new combination. Version, resolved images and the override flag are frozen in each deployment snapshot, so retained-image rollback restores its original application without changing the current project settings.

Release commands

releaseCommands runs once per deploy, after the build and before the new version goes live: the place migrations belong. Each command runs in order, its output streams into the deploy log, and a non-zero exit fails the deploy: nothing cuts over, and the version that was already serving keeps serving.

{
  "releaseCommands": ["php artisan migrate --force"]
}

Nothing is injected for you. A framework's release set is a choice, so an app with no releaseCommands runs no release phase at all. The equivalents elsewhere:

Rails uses db:prepare rather than db:migrate because it also creates the database and loads the schema when it is empty, which is exactly the state of a first deploy.

Set these commands in Build settings → Before activation, openship.json, or the project API/SDK. A repository scan seeds a new project; existing projects keep their saved commands, including an explicit empty list. The list is frozen on each deployment.

Each command gets the same environment variables as your start command and a 10-minute budget. It runs once per forward deployment attempt, in list order. Failure, timeout, or cancellation stops activation and leaves the previous application running.

On Docker, each command runs in a temporary container using the candidate image, the project's persistent mounts, and its connected-service networks. It publishes no ports and does not restart. Openship removes the container and its anonymous scratch volumes afterwards. On Bare, commands run in the staged release directory after persistent paths are linked, before the supervisor changes the running app. When a forward deploy reuses a retained Bare release, the command gets a temporary copy so it cannot edit the live application's files.

Runtime roles

roles declares extra long-running processes that run beside your web app, from the same built image: queue workers and schedulers. Each replica is its own container, so a worker can scale without scaling the web app, and a scheduler runs exactly once.

{
  "roles": [
    {
      "name": "queue",
      "kind": "worker",
      "command": "exec php artisan queue:work --tries=3",
      "replicas": 2,
      "stopGracePeriod": "90s"
    },
    {
      "name": "scheduler",
      "kind": "scheduler",
      "command": "exec php artisan schedule:work"
    }
  ]
}

Roles are read from openship.json when a project is created from a repository scan. Like release commands, an existing project keeps the roles it has saved, so change those through the project API/SDK (roles; send [] to remove them). The list is frozen on each deployment, and a project holds at most 20 roles.

Fields

Where roles run

Roles run on single-app projects deployed to a Docker server. A deploy that declares roles is refused before the build starts, with no build, release command or container run, on:

• Openship Cloud
• direct (bare) hosts
• Kubernetes
• multi-service projects (Compose or monorepo)
• static sites

Moving a project that has roles to another server is refused as well.

What a role container gets

A role container starts from the same image as the web container and gets:

• the web container's environment variables, without PORT
• the project's persistent storage
• the same resource limits and restart policy

It publishes no port, gets no route and no network alias: only the web container answers to the app's network name. It joins the project network and the networks of any connected services before its process starts, so a worker can reach the database from its first instruction.

Deploy order

1. The build runs.
2. Release commands run.
3. Roles start.
4. The web container goes live.

Workers start beside the previous version's workers. The old ones keep running, and are removed only once the new web container is live.

Singletons (schedulers, or singleton: true) hand over stop-first. A new role continues a previous one only when it keeps the name, effective singleton status (kind: "scheduler" or singleton: true) and the command. For a continued singleton, the old container is stopped and retained before the new one starts.

Continuation compares saved role fields. It does not detect changes in behavior caused by a new deployment image, environment, inherited image settings or application code behind an unchanged command.

A previous singleton that no new role continues is outgoing. A rename, a command change, a name swap or a change to a scalable worker each make a singleton outgoing. When the deploy also adds or changes a role, Openship stops and retains each outgoing singleton after the unchanged workers pass their startup check, and before any added or changed role starts. Otherwise an outgoing singleton keeps running until the new web container is live.

When unwinding a failed deploy, Openship attempts to remove the new containers and restore retained singletons. A continued singleton is restored only after its replacement is confirmed removed. An outgoing singleton is restored only after every added or changed role is confirmed removed.

This ordering uses the previous deployment's saved role definitions. Without them, only a singleton that keeps its name hands over stop-first. Runtime failures or an interrupted deploy can leave containers unresolved. Reconcile them, and restart the scheduler if needed, before redeploying. A handover does not guarantee exactly-once scheduled execution, so keep application-level guards such as Laravel's onOneServer().

Startup check

Every role container must stay up through the stabilization window, 15 seconds by default. This check always runs for roles, whatever the project's readiness settings, because a role has no port to probe. If the role declares an exec health command, it runs once, after the window. A failed startup check fails the deploy and triggers the rollback attempt described above. The startup check runs only during a deploy. It does not continuously monitor role containers afterward.

Lifecycle

• Pausing, resuming and restarting the project act on its roles too.
• Deleting a deployment removes its role containers.
• Clearing a project's roles retires the running ones on the next deploy.

Persistent storage

Everything a container writes is discarded when the next version replaces it. volumes names the paths to keep.

A bare path is relative to the app; full compose syntax works too, so you can point a mount at a specific volume name or a host directory:

{
  "volumes": ["storage", "uploads:/app/public/uploads", "/srv/data:/app/var"]
}

Omit the field to inherit the framework's own defaults (a Laravel app keeps storage/ with no configuration). Declare [] to turn persistence off entirely — that is different from omitting it.

Named volumes are scoped per project, so two projects that both declare storage never share one. On a bare (non-container) deploy the same paths are kept outside the release directory and symlinked in. Openship Cloud has no volume primitive: a declared mount is reported and skipped there, so use object storage for uploads instead.

Compose services declare their own mounts under services[].volumes.

Environment variables

env is an object. A value is a plain string, or { "value", "secret" } to mark a secret (encrypted at rest — never returned to the client afterward). These declarations are active automatically; a value saved in the dashboard or CLI for the same key overrides the repository default.

{
  "env": {
    "NEXT_PUBLIC_URL": "https://app.acme.com",
    "DATABASE_URL": { "value": "postgres://…", "secret": true }
  }
}

Domains

domains is an array of hostnames or objects. A bare label ("myapp") is a free *.opsh.io-style subdomain; a dotted hostname ("app.acme.com") is a custom domain.

{ "domains": ["app.acme.com", { "domain": "api.acme.com", "port": 8080, "type": "custom" }] }

Routes

routes reproduces vercel.json-style routing, compiled to the reverse proxy at deploy.

Resources

CPU/memory limits for the project's containers — a named tier, or explicit values (which become the custom tier). See Sleep mode & resources.

{
  "resources": { "cpuCores": 4, "memoryMb": 8192 }
}

Services (compose)

Declaring services makes the project a multi-service (Docker) project — see Compose / multi-service. Each entry requires a name.

Already have a compose file? Don't re-declare it here — point composePath at it and leave services out. That works for a compose file anywhere in the repo (deploy/docker-compose/), under any filename (stack.yml), and keeps the file the single source of truth: its services are re-read on every deploy, and build: contexts resolve relative to it, exactly as compose does.

{ "composePath": "deploy/docker-compose/docker-compose.yml" }

{
  "services": [
    {
      "name": "web",
      "build": ".",
      "buildArgs": { "NEXT_PUBLIC_API_URL": null },
      "ports": ["3000"],
      "exposed": true,
      "domain": "app.acme.com"
    },
    {
      "name": "db",
      "image": "postgres:17",
      "volumes": ["pgdata:/var/lib/postgresql/data"],
      "env": { "POSTGRES_PASSWORD": { "value": "…", "secret": true } },
      "restart": "unless-stopped"
    }
  ]
}

dependsOn takes service names such as ["db"], without a port. It controls container startup order, not database availability during an image build. For ENOTFOUND db during next build, see Database access during a Next.js build.

Top-level env is available to Dockerfile builds as well as running containers. Use buildArgs when a service needs an explicit override or when you want the config to document which Dockerfile arguments it consumes. A service's own env is runtime-only and is never shared with sibling builds. Keep runtime-only credentials in service env where possible: Docker build arguments are not a secret-storage mechanism and can be retained in image metadata or build cache.

A compose file's own limits are honored too — Openship reads mem_limit / cpus and deploy.resources.limits.{memory,cpus} off each service and applies them over the project-wide setting.

Monorepo

monorepo overrides Openship's detected sub-apps. Entries in apps[] are matched to detected sub-apps by rootDirectory and override their build settings — they don't declare apps from scratch (the detector finds the apps).

Each override must have a different normalized rootDirectory. Declaring a web process and a worker at the same root is not a supported multi-app declaration. openship config validate rejects duplicate roots; source scans report unmatched apps and workspace overrides in the configuration diagnostics.

Create a monorepo through the repository import flow, which supplies the detected app metadata. The API/SDK also accepts that metadata as monorepoApps. Setting projectType: "monorepo" (or CLI project create --type monorepo) without it now fails before creating a project. A local CLI import scans the workspace first. For independent processes without containers, use separate projects pointed at the required roots and start commands.

{
  "monorepo": {
    "workspace": { "packageManager": "pnpm", "prepareCommand": "pnpm install && pnpm codegen" },
    "apps": [
      { "name": "web", "rootDirectory": "apps/web", "framework": "nextjs", "port": 3000 },
      { "name": "api", "rootDirectory": "apps/api", "framework": "hono", "port": 8080 }
    ]
  }
}

How it maps

See also

• Guide: deploy with openship.json
• Deploy from GitHub · Auto-deploy on push