How the Oblien Openship Configuration System Works: A Complete Guide to openship.json

The oblien/openship configuration system uses a declarative openship.json file combined with auto-detection, overlay merging, and schema validation to manage deployments.

The oblien/openship configuration system centers on a single, version-controlled manifest that bridges project detection and deployment execution. By placing an openship.json file in your repository root, you create an authoritative overlay that overrides auto-detected defaults while maintaining type safety through a strict validation schema implemented in the core package.

How the Configuration System Works

The oblien/openship configuration system operates through three distinct layers that transform repository contents into deployment-ready instructions.

Layer 1: Project Auto-Detection

Openship first inspects repository contents—checking for package.json, lockfiles, and docker-compose.yml—to infer the default stack and runtime environment. This detection runs automatically during the deployment preparation phase in apps/api/src/modules/deployments/prepare.service.ts, creating a base ProjectInfo object that reflects the discovered project structure.

Layer 2: Configuration Overlay

When present, the openship.json file acts as an authoritative overlay that overrides detected values. Omitted fields retain their auto-detected defaults, allowing partial configuration. The PrepareService reads the repo file list, extracts the openship.json entry (case-insensitive), and merges it onto the detected ProjectInfo between lines 95-143, ensuring manual settings take precedence over inferred ones.

Layer 3: Validation and Parsing

The raw JSON undergoes strict parsing via parseOpenshipConfig in packages/core/src/openship-config/parse.ts. This function validates the structure against the TypeScript schema defined in packages/core/src/openship-config/schema.ts, returning a ParseResult containing the typed config, errors, and warnings. This layer prevents malformed configurations from reaching the deployment pipeline.

Core Schema Concepts in openship.json

The schema defines several key concepts that control deployment behavior:

• Runtime – Specifies "bare" or "docker" execution environments (schema.ts lines 18-22).
• ProductionMode – Defines hosting strategy as "host", "static", or "standalone" (schema.ts lines 24-29).
• Services – Docker Compose-style definitions including image, build context, ports, environment variables, and healthchecks (schema.ts lines 67-82).
• Resources – Tiered allocations (e.g., "tier": "medium") or explicit CPU/memory/disk limits (schema.ts lines 108-113).
• Domains and Routing – Hostname bindings, port mappings, and Vercel-style routing objects (schema.ts lines 48-56).

CLI Commands for Configuration Management

The oblien/openship CLI provides dedicated commands for managing your configuration file.

Scaffolding a New Configuration

The openship config init command creates a starter openship.json in your repository root. Add --force to overwrite existing files. Implementation resides in apps/cli/src/commands/config.ts.

openship config init
openship config init --force

Validating Configuration Files

Use openship config validate to parse and verify your manifest before deployment. The command calls parseOpenshipConfig and prints errors (hard failures) and warnings (soft issues).

openship config validate
openship config validate path/to/openship.json

Programmatic Access to Configuration

Developers can parse configurations directly in Node.js applications using the core parser. This is useful for CI/CD pipelines that need to inspect deployment parameters before triggering builds.

import { parseOpenshipConfig } from '@openship/core/openship-config/parse';
import { readFileSync } from 'fs';

const raw = JSON.parse(readFileSync('openship.json', 'utf8'));
const { config, errors, warnings } = parseOpenshipConfig(raw);

if (errors.length) {
  console.error('Invalid config:', errors);
} else {
  console.log('Validated config:', config);
}

The parser returns a ParseResult object containing the validated configuration object, an array of errors, and an array of warnings (parse.ts lines 373-420).

Summary

• The oblien/openship configuration system relies on a repo-root openship.json file that overlays auto-detected project settings.
• Three layers—auto-detection, overlay merging, and schema validation—ensure flexible yet type-safe deployments.
• Core concepts include Runtime, ProductionMode, Services, Resources, and Domains defined in packages/core/src/openship-config/schema.ts.
• The CLI provides openship config init for scaffolding and openship config validate for verification.
• Programmatic access is available through parseOpenshipConfig in packages/core/src/openship-config/parse.ts.

Frequently Asked Questions

Does oblien/openship require a configuration file?

No. The oblien/openship configuration system operates on an auto-detection-first model. If openship.json is absent, Openship infers settings from package.json, lockfiles, and docker-compose.yml. The configuration file only serves to override specific auto-detected values, making it optional for standard deployments.

Where does openship.json need to be located?

The file must reside in the repository root. The PrepareService in apps/api/src/modules/deployments/prepare.service.ts specifically searches the repo file list for openship.json (case-insensitive) at the root level to apply the configuration overlay during the deployment preparation phase.

What happens if openship.json contains invalid syntax?

The validation layer catches errors during parsing. When running openship config validate or during deployment preparation, parseOpenshipConfig returns error objects that prevent deployment until resolved. Warnings are issued for non-critical issues but allow the deployment to proceed, giving developers flexibility to address recommendations asynchronously.

Can I define multiple services in one openship.json?

Yes. The schema supports Docker Compose-style service definitions within the services field, allowing you to configure multiple containers, their build contexts, port mappings, environment variables, and healthchecks in a single configuration file as defined in packages/core/src/openship-config/schema.ts lines 67-82.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}