Authoring openship.json
openship.json is a repo-root file that declares how Openship builds, runs, routes, and
scales a project. It is an authoritative overlay: Openship auto-detects everything first,
then every field present in openship.json overrides the detected value. Absent fields keep
the detected value — so a good openship.json is small: declare only what you want to pin
or override, not the whole detected config.
Workflow
- Understand the repo. Look at
package.json (scripts, deps), lockfiles (package manager),
framework config (next.config.*, vite.config.*, astro.config.*, …), any
docker-compose.yml, and whether it's a monorepo (pnpm-workspace.yaml, turbo.json,
apps/*, packages/*).
- Decide what to override. If detection would already get it right, leave it out. Add a
field only when the repo needs a non-default (custom build command, a fixed port, a custom
domain, secrets, compose services, cloud sizing).
- Write
openship.json at the repo root. Always start with the $schema line for editor
autocomplete:{
"$schema": "https://openship.io/openship.schema.json"
}
- Validate with
openship config validate (or openship config validate path/to/openship.json).
Fix every reported error. openship config init scaffolds a starter if none exists.
The essentials (cover these first)
framework — only if detection guesses wrong. One of the stack slugs (see references/fields.md).
buildCommand / installCommand / startCommand — the commands. Omit any that match the
detected default.
outputDirectory — for static/SSG builds (e.g. dist, .next, build, out).
port — the port a server listens on.
env — a string is a plain value; { "value": "...", "secret": true } marks a secret
(encrypted at rest). Prefer per-key secret: true for anything sensitive.
domains — a bare label ("myapp") is a free subdomain; a dotted hostname ("app.acme.com")
is a custom domain.
Common shapes
Static site
{
"$schema": "https://openship.io/openship.schema.json",
"framework": "vite",
"buildCommand": "pnpm build",
"outputDirectory": "dist",
"productionMode": "static"
}
Server app with a custom domain + secret
{
"$schema": "https://openship.io/openship.schema.json",
"framework": "nextjs",
"port": 3000,
"runtime": "docker",
"env": {
"NEXT_PUBLIC_URL": "https://app.acme.com",
"DATABASE_URL": { "value": "postgres://…", "secret": true }
},
"domains": ["app.acme.com"]
}
Compose services — declaring services makes it a multi-service project (Docker runtime):
{
"$schema": "https://openship.io/openship.schema.json",
"services": [
{ "name": "web", "build": ".", "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" }
]
}
Rules & gotchas
- It's JSON, not JSONC — no comments, no trailing commas.
- Keep it minimal. Every field overrides detection; unused fields just add noise.
services (compose) and monorepo are alternatives to a single-app config, not additions.
monorepo.apps[] entries override detected sub-apps matched by rootDirectory; they don't
declare apps from scratch (Openship's detector finds the apps).
resources is a cloud concern (tier or explicit cpu/mem/disk); it's ignored on self-hosted.
runtime, productionMode, domains, resources seed the deploy wizard and headless
deploys. sleepMode and monorepo sharedPaths are not supported yet — don't add them.
The full field-by-field reference (every field, its type, allowed values, and what it maps to)
is in references/fields.md. Read it before writing anything non-trivial.
1---2name: openship-config3description: Author or fix an openship.json — Openship's declarative deploy config (like vercel.json / railway.toml). Use when the user asks to "make this repo deployable on Openship", "add an openship.json", "configure the Openship deploy", set the framework/build/env/domains/services/resources for an Openship deploy, or fix a failing `openship config validate`.4metadata:5 source: https://skillmd.com/skills/oblien/openship-config6---78# Authoring `openship.json`910`openship.json` is a repo-root file that declares how Openship builds, runs, routes, and11scales a project. It is an **authoritative overlay**: Openship auto-detects everything first,12then every field present in `openship.json` overrides the detected value. Absent fields keep13the detected value — so a good `openship.json` is **small**: declare only what you want to pin14or override, not the whole detected config.1516## Workflow17181. **Understand the repo.** Look at `package.json` (scripts, deps), lockfiles (package manager),19 framework config (`next.config.*`, `vite.config.*`, `astro.config.*`, …), any20 `docker-compose.yml`, and whether it's a monorepo (`pnpm-workspace.yaml`, `turbo.json`,21 `apps/*`, `packages/*`).222. **Decide what to override.** If detection would already get it right, leave it out. Add a23 field only when the repo needs a non-default (custom build command, a fixed port, a custom24 domain, secrets, compose services, cloud sizing).253. **Write `openship.json`** at the repo root. Always start with the `$schema` line for editor26 autocomplete:27 ```json28 {29 "$schema": "https://openship.io/openship.schema.json"30 }31 ```324. **Validate** with `openship config validate` (or `openship config validate path/to/openship.json`).33 Fix every reported error. `openship config init` scaffolds a starter if none exists.3435## The essentials (cover these first)3637- `framework` — only if detection guesses wrong. One of the stack slugs (see `references/fields.md`).38- `buildCommand` / `installCommand` / `startCommand` — the commands. Omit any that match the39 detected default.40- `outputDirectory` — for static/SSG builds (e.g. `dist`, `.next`, `build`, `out`).41- `port` — the port a server listens on.42- `env` — a string is a plain value; `{ "value": "...", "secret": true }` marks a secret43 (encrypted at rest). Prefer per-key `secret: true` for anything sensitive.44- `domains` — a bare label (`"myapp"`) is a free subdomain; a dotted hostname (`"app.acme.com"`)45 is a custom domain.4647## Common shapes4849**Static site**50```json51{52 "$schema": "https://openship.io/openship.schema.json",53 "framework": "vite",54 "buildCommand": "pnpm build",55 "outputDirectory": "dist",56 "productionMode": "static"57}58```5960**Server app with a custom domain + secret**61```json62{63 "$schema": "https://openship.io/openship.schema.json",64 "framework": "nextjs",65 "port": 3000,66 "runtime": "docker",67 "env": {68 "NEXT_PUBLIC_URL": "https://app.acme.com",69 "DATABASE_URL": { "value": "postgres://…", "secret": true }70 },71 "domains": ["app.acme.com"]72}73```7475**Compose services** — declaring `services` makes it a multi-service project (Docker runtime):76```json77{78 "$schema": "https://openship.io/openship.schema.json",79 "services": [80 { "name": "web", "build": ".", "ports": ["3000"], "exposed": true, "domain": "app.acme.com" },81 { "name": "db", "image": "postgres:17", "volumes": ["pgdata:/var/lib/postgresql/data"],82 "env": { "POSTGRES_PASSWORD": { "value": "…", "secret": true } },83 "restart": "unless-stopped" }84 ]85}86```8788## Rules & gotchas8990- It's **JSON, not JSONC** — no comments, no trailing commas.91- Keep it minimal. Every field overrides detection; unused fields just add noise.92- `services` (compose) and `monorepo` are alternatives to a single-app config, not additions.93- `monorepo.apps[]` entries **override detected sub-apps** matched by `rootDirectory`; they don't94 declare apps from scratch (Openship's detector finds the apps).95- `resources` is a cloud concern (tier or explicit cpu/mem/disk); it's ignored on self-hosted.96- `runtime`, `productionMode`, `domains`, `resources` seed the deploy wizard **and** headless97 deploys. `sleepMode` and monorepo `sharedPaths` are **not** supported yet — don't add them.9899The full field-by-field reference (every field, its type, allowed values, and what it maps to)100is in [`references/fields.md`](references/fields.md). Read it before writing anything non-trivial.