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

> Explore the oblien openship configuration system. Learn how openship.json manages deployments through declarative settings, auto-detection, overlay merging, and schema validation.

- Repository: [oblien/openship](https://github.com/oblien/openship)
- Tags: architecture
- Published: 2026-07-29

---

**The oblien/openship configuration system uses a declarative [`openship.json`](https://github.com/oblien/openship/blob/main/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`](https://github.com/oblien/openship/blob/main/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`](https://github.com/oblien/openship/blob/main/package.json), lockfiles, and [`docker-compose.yml`](https://github.com/oblien/openship/blob/main/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`](https://github.com/oblien/openship/blob/main/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`](https://github.com/oblien/openship/blob/main/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`](https://github.com/oblien/openship/blob/main/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`](https://github.com/oblien/openship/blob/main/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`](https://github.com/oblien/openship/blob/main/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`](https://github.com/oblien/openship/blob/main/schema.ts) lines 18-22).
- **ProductionMode** – Defines hosting strategy as `"host"`, `"static"`, or `"standalone"` ([`schema.ts`](https://github.com/oblien/openship/blob/main/schema.ts) lines 24-29).
- **Services** – Docker Compose-style definitions including image, build context, ports, environment variables, and healthchecks ([`schema.ts`](https://github.com/oblien/openship/blob/main/schema.ts) lines 67-82).
- **Resources** – Tiered allocations (e.g., `"tier": "medium"`) or explicit CPU/memory/disk limits ([`schema.ts`](https://github.com/oblien/openship/blob/main/schema.ts) lines 108-113).
- **Domains and Routing** – Hostname bindings, port mappings, and Vercel-style routing objects ([`schema.ts`](https://github.com/oblien/openship/blob/main/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`](https://github.com/oblien/openship/blob/main/openship.json) in your repository root. Add `--force` to overwrite existing files. Implementation resides in [`apps/cli/src/commands/config.ts`](https://github.com/oblien/openship/blob/main/apps/cli/src/commands/config.ts).

```bash
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).

```bash
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.

```typescript
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`](https://github.com/oblien/openship/blob/main/parse.ts) lines 373-420).

## Summary

- The oblien/openship configuration system relies on a repo-root [`openship.json`](https://github.com/oblien/openship/blob/main/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`](https://github.com/oblien/openship/blob/main/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`](https://github.com/oblien/openship/blob/main/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`](https://github.com/oblien/openship/blob/main/openship.json) is absent, Openship infers settings from [`package.json`](https://github.com/oblien/openship/blob/main/package.json), lockfiles, and [`docker-compose.yml`](https://github.com/oblien/openship/blob/main/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`](https://github.com/oblien/openship/blob/main/apps/api/src/modules/deployments/prepare.service.ts) specifically searches the repo file list for [`openship.json`](https://github.com/oblien/openship/blob/main/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`](https://github.com/oblien/openship/blob/main/packages/core/src/openship-config/schema.ts) lines 67-82.