openship-config
This 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.
Install
npx skills add https://github.com/fcakyon/claude-codex-settings/tree/main/plugins/openship-skills/skills/openship-config
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install fcakyon-claude-codex-settings@llmmart
git clone https://github.com/fcakyon/claude-codex-settings.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole fcakyon/claude-codex-settings collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
Design openship.json
Use OpenShip's upstream configuration workflow: inspect the repo, declare only necessary overrides, then validate. Auto-detection supplies omitted fields. Prefer self-hosted deployment unless the user selects cloud.
Design the configuration
- Inspect package scripts, lockfiles, framework settings, Dockerfiles, compose files, workspace layout, and an existing
openship.json. - Choose a single app, compose services, or detected monorepo apps. Do not combine those shapes casually.
monorepo.appsoverrides detected apps by root directory. It does not discover new applications. - Read fields for names and meanings and the bundled JSON schema for editor validation. Use compose guidance for service topology, ports, dependencies, and persistent volumes.
- Start with
openship config initonly when the file is absent. Preserve an existing config and add only values that need to override detection. Keep its$schemaset tohttps://openship.io/openship.schema.json. - Run
openship --json config validateusing the deployment's CLI version. Fix errors and review warnings: unknown keys can be ignored by the runtime even though the editor schema rejects them.
A minimal server config can be:
{
"$schema": "https://openship.io/openship.schema.json",
"port": 3000,
"runtime": "docker",
"domains": ["app.example.com"]
}
Self-hosted details
- Self-hosted defaults to unlimited resources in the bundled release. Declare caps only when intended. Service-level caps override project caps field by field. Check target capacity separately from local config validation.
- Use named persistent volumes for state that must survive an application deploy. Expose only the services intended to receive public traffic.
- Keep actual secret values out of committed JSON.
secret: truecontrols storage handling after ingestion. It does not encrypt a credential in a Git file. Read environment variables for instance-managed values. openship.jsonexpresses desired configuration. It does not prove an existing domain has moved or the running deployment has changed. The companionopenship-deployskill handles deployment and live verification.
Source and version
The workflow and field reference derive from the official upstream config skill. upstream.json records the release and links to its CLI validator, runtime parser, types, parser tests, and deployment preparation code. Consult those sources when docs disagree or a behavior depends on the installed version. The parser and actual deployment implementation decide runtime behavior. The JSON schema serves editor validation.
Read the configuration guide for additional examples. Do not copy example credentials into a repository.
Files (claude-codex-settings)
-
references
-
compose-multi-service.mdx 21.5 KB · in bundle
-
environment-variables.mdx 18 KB · in bundle
-
fields.md 7.9 KB
Loading… -
openship-json.mdx 3.6 KB · in bundle
-
openship.schema.json 16.2 KB
Loading… -
upstream.json 4 KB
Loading…
-
-
LICENSE 11.1 KB · in bundle
-
SKILL.md 3.1 KB
--- name: openship-config description: This 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. --- # Design openship.json Use OpenShip's upstream configuration workflow: inspect the repo, declare only necessary overrides, then validate. Auto-detection supplies omitted fields. Prefer self-hosted deployment unless the user selects cloud. ## Design the configuration 1. Inspect package scripts, lockfiles, framework settings, Dockerfiles, compose files, workspace layout, and an existing `openship.json`. 2. Choose a single app, compose services, or detected monorepo apps. Do not combine those shapes casually. `monorepo.apps` overrides detected apps by root directory. It does not discover new applications. 3. Read [fields](references/fields.md) for names and meanings and the bundled [JSON schema](references/openship.schema.json) for editor validation. Use [compose guidance](references/compose-multi-service.mdx) for service topology, ports, dependencies, and persistent volumes. 4. Start with `openship config init` only when the file is absent. Preserve an existing config and add only values that need to override detection. Keep its `$schema` set to `https://openship.io/openship.schema.json`. 5. Run `openship --json config validate` using the deployment's CLI version. Fix errors and review warnings: unknown keys can be ignored by the runtime even though the editor schema rejects them. A minimal server config can be: ```json { "$schema": "https://openship.io/openship.schema.json", "port": 3000, "runtime": "docker", "domains": ["app.example.com"] } ``` ## Self-hosted details - Self-hosted defaults to unlimited resources in the bundled release. Declare caps only when intended. Service-level caps override project caps field by field. Check target capacity separately from local config validation. - Use named persistent volumes for state that must survive an application deploy. Expose only the services intended to receive public traffic. - Keep actual secret values out of committed JSON. `secret: true` controls storage handling after ingestion. It does not encrypt a credential in a Git file. Read [environment variables](references/environment-variables.mdx) for instance-managed values. - `openship.json` expresses desired configuration. It does not prove an existing domain has moved or the running deployment has changed. The companion `openship-deploy` skill handles deployment and live verification. ## Source and version The workflow and [field reference](references/fields.md) derive from the official upstream config skill. [upstream.json](references/upstream.json) records the release and links to its CLI validator, runtime parser, types, parser tests, and deployment preparation code. Consult those sources when docs disagree or a behavior depends on the installed version. The parser and actual deployment implementation decide runtime behavior. The JSON schema serves editor validation. Read the [configuration guide](references/openship-json.mdx) for additional examples. Do not copy example credentials into a repository.
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.