fcakyon/claude-codex-settings / plugins/openship-skills/skills/openship-config
openship-config
VerifiedThis skill should be used when the user asks to "create openship.json", "configure an OpenShip deployment", "make a repo deployable on OpenShip", or fix "openship config validate" errors.
| File | Kind | Size |
|---|---|---|
| LICENSE | other | 11.1 KB |
| SKILL.md | skill md | 3.1 KB |
| references/compose-multi-service.mdx | markdown | 21.5 KB |
| references/environment-variables.mdx | markdown | 18.0 KB |
| references/fields.md | markdown | 7.9 KB |
| references/openship-json.mdx | markdown | 3.6 KB |
| references/openship.schema.json | config | 16.2 KB |
| references/upstream.json | config | 4.0 KB |
references/fields.md
View on GitHub# `openship.json` — full field reference
Every field is optional. Present fields override auto-detection; absent fields keep the detected
value. Validated by `openship config validate` (same parser the deploy uses).
## Build
| Field | Type | Notes |
|---|---|---|
| `framework` | enum | Stack slug (see list below). Overrides detection. |
| `packageManager` | enum | `npm` `yarn` `pnpm` `bun` `go` `cargo` `pip` `poetry` `pipenv` `uv` `bundler` `composer` `maven` `gradle` `dotnet` `mix` |
| `rootDirectory` | string | App dir relative to repo root (e.g. `./`, `apps/web`). |
| `composePath` | string | Compose file outside the detected root — the file (`deploy/stack.yml`, which also covers non-standard names) or the folder holding it (`deploy/docker-compose`). Makes the project a compose deploy; `build:` contexts resolve relative to that folder, as compose does. |
| `installCommand` | string | Dependency install command. |
| `buildCommand` | string | Build command. |
| `startCommand` | string | Production start command. |
| `releaseCommands` | string[] | Commands run ONCE per deploy, after the build and before the new version goes live, typically migrations. Each runs with the start command's env; a non-zero exit fails the deploy and the previous version keeps serving. On Docker they run in a throwaway container, so only effects outside it persist (the database, a mounted volume): keep cache warms and `storage:link` in the start command. Laravel: `["php artisan migrate --force"]`. Rails: `["bundle exec rails db:prepare"]`. Omit for no release phase (the default — nothing is auto-injected). Requires a single-app Docker/Bare deployment; unsupported runtimes and full Compose/static deployments fail before activation. Rollbacks and explicitly service-scoped actions skip it. Commands must be idempotent; code rollback does not undo database changes. |
| `outputDirectory` | string | Build output dir (`dist`, `.next`, `build`, `out`, …). |
| `buildImage` | string | Build Docker image (e.g. `node:22`). |
| `productionPaths` | string[] | Paths shipped as the production artifact. |
**`framework` values:** `nextjs` `farmjs` `nuxt` `sveltekit` `remix` `astro` `vite` `angular` `gatsby`
`cra` `vue` `react` `express` `fastify` `hono` `nestjs` `koa` `adonis` `elysia` `go` `gin`
`fiber` `echo` `rust` `actix` `axum` `rocket` `python` `django` `flask` `fastapi` `rails`
`sinatra` `laravel` `symfony` `springboot` `quarkus` `kotlin` `dotnet` `blazor` `phoenix`
`node` `static` `docker` `docker-compose` `webmail`.
## Runtime
| Field | Type | Notes |
|---|---|---|
| `runtime` | `bare` \| `docker` | Runtime isolation for a single app. Services/docker projects are always `docker`. Seeds a new deploy's runtime. |
| `productionMode` | `host` \| `static` \| `standalone` | `static` ⇒ served as files, no server (sets `hasServer=false`). |
| `port` | integer 1–65535 | Server port. |
| `volumes` | string[] | Paths kept across deploys. Bare path = relative to the app (`storage`), or a full mount (`uploads:/app/storage`, `/srv/data:/app/var`). Omit to inherit the framework defaults (Laravel keeps `storage/`); `[]` turns persistence off. Compose services use `services[].volumes` instead. |
| `optimize` | boolean | Laravel only. Opt-in cache warming for the web role, default `false`. `true` prefixes the web command with `php artisan optimize && ` to warm Laravel's config/route/event/view caches. An absent or `false` flag keeps the web command byte-identical. Web role only (workers/schedulers stay unwarmed). Warms per-request throughput, not cold start. Runs at startup only: `config:cache` freezes the env present when it runs and makes `env()` outside `config/*.php` return `null`, so never put it in `buildCommand` or `releaseCommands`. To warm a worker, re-declare `roles` and prefix each `command` with `php artisan optimize && `. |
## Env
`env` is an object. A value is either a plain string, or `{ "value": string, "secret"?: boolean }`.
`secret: true` marks the variable for encryption at rest.
```json
"env": {
"PUBLIC_URL": "https://app.acme.com",
"API_KEY": { "value": "sk_live_…", "secret": true }
}
```
## Domains
`domains` is an array. Each entry is either a hostname string, or an object:
| Field | Type | Notes |
|---|---|---|
| `domain` | string | Hostname. Bare label = free subdomain; dotted = custom. |
| `port` | integer | Which port this hostname routes to. |
| `targetPath` | string | Path prefix on the target (default `/`). |
| `type` | `free` \| `custom` | Overrides the free/custom inference. |
## Routes
`routes` compiles to the reverse proxy at deploy.
| Field | Type | Notes |
|---|---|---|
| `rewrites` | `{ source, destination }[]` | Internal rewrites (e.g. SPA fallback). |
| `redirects` | `{ source, destination, permanent?, statusCode? }[]` | 3xx redirects. |
| `headers` | `{ source, headers: { key, value }[] }[]` | Response headers per path. |
| `cleanUrls` | boolean | Strip `.html`. |
| `trailingSlash` | boolean | Enforce/remove trailing slash. |
## Resources
`resources` is a named tier OR explicit values. Explicit values become the `custom` tier.
**Self-hosted defaults to `unlimited`** — no caps, because the machine is the operator's own and
is itself the ceiling. Only declare this to deliberately cap a container. A non-zero value is
validated against the TARGET MACHINE's real capacity, so a big box can be used fully. Cloud
workspaces are metered and must be sized: `unlimited` is rejected there and an omitted value
falls back to `low`.
| Field | Type | Range |
|---|---|---|
| `tier` | `unlimited` \| `micro` \| `low` \| `medium` \| `high` | `unlimited` is self-hosted only |
| `cpuCores` | number | `0` = no limit; otherwise ≥ 0.25, up to the machine's cores |
| `memoryMb` | integer | `0` = no limit; otherwise ≥ 128, up to the machine's RAM |
| `diskMb` | integer | `0` = no limit; otherwise 64–204800 (cloud workspaces only) |
## Services (compose)
`services` is an array; declaring it makes the project a multi-service (Docker) project.
To deploy an EXISTING compose file instead of re-declaring its services here, set
[`composePath`](#build) and leave `services` out.
| Field | Type | Notes |
|---|---|---|
| `name` | string | **Required.** |
| `image` | string | Prebuilt image (e.g. `postgres:17`). |
| `build` | string | Build context path. |
| `dockerfile` | string | Dockerfile path. |
| `ports` | string[] | e.g. `["3000"]`, `["5432:5432"]`. |
| `volumes` | string[] | e.g. `["pgdata:/var/lib/postgresql/data"]`. |
| `dependsOn` | string[] | Other service names. |
| `env` | env object | Same shape as top-level `env`. |
| `command` | string | Override the container command. |
| `restart` | `no` \| `always` \| `on-failure` \| `unless-stopped` | Restart policy. |
| `exposed` | boolean | Publicly routed. |
| `exposedPort` | string | Which container port is exposed. |
| `domain` | string | Public hostname for this service. |
| `healthcheck` | object | `{ test, interval, timeout, retries, startPeriod, disable }`. |
| `resources` | object | Per-service caps, overriding the top-level `resources` field by field. Same shape; `0` = no limit. |
A compose file's own `mem_limit` / `cpus` / `deploy.resources.limits` are read and applied the
same way — no need to restate them here.
## Monorepo
`monorepo` overrides detected sub-apps.
| Field | Type | Notes |
|---|---|---|
| `workspace.packageManager` | string | Root workspace package manager. |
| `workspace.prepareCommand` | string | Runs once at the repo root before per-app builds. |
| `apps[]` | array | Per-sub-app build overrides. |
Each `apps[]` entry (`name` + `rootDirectory` required) overrides the detected sub-app at that
`rootDirectory`. Supported overrides: `framework`, `packageManager`, `installCommand`,
`buildCommand`, `startCommand`, `outputDirectory`, `buildImage`, `port`. (Per-app `domain`/`env`
are set in the wizard, not here.)
## Not supported (do not add)
`sleepMode`, monorepo `sharedPaths`, and per-app `domain`/`env`/`exposed` are validated leniently
but **not applied** — leave them out.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |