Openship SystemManager Prerequisite Checks: Installation and Validation Guide

Openship's SystemManager automatically validates Docker or Node 22+ environments before deployment via the checkPrerequisites() method invoked by the openship up CLI command.

The Openship SystemManager is the environment validation component in the oblien/openship repository that ensures your host satisfies minimal requirements before launching the control plane. Located in packages/adapters/src/runtime/index.ts, this class performs lightweight prerequisite checks for both Docker Compose and bare-metal deployment modes. Understanding these checks prevents deployment failures and ensures smooth initialization of Postgres, Redis, API, Dashboard, and OpenResty edge services.

How SystemManager Validates Prerequisites

The SystemManager class executes a predefined validation sequence when instantiated. According to the source code in packages/adapters/src/runtime/index.ts, the manager supports two operational modes: Compose mode (Docker-based) and Bare mode (single-process).

Docker Availability Verification

In Compose mode, the manager executes docker version to verify the Docker daemon is accessible. It pings the daemon to confirm responsive container runtime before attempting to load docker/docker-compose.yml.

Node.js Runtime Validation

For both modes, the manager checks the current Node.js version against the minimum supported release (≥ 22). This validation ensures compatibility with the modern JavaScript features used throughout the @openship/adapters package.

Host OS Capability Checks

On Linux systems, the manager verifies critical syscalls including setuid and network namespace support. These checks confirm the host can properly isolate and permission the control-plane services.

Installing and Running Prerequisite Checks

You can invoke the SystemManager either automatically through the CLI or programmatically via the library.

CLI Installation and Execution

Install the Openship CLI using the official installer. The CLI bundles the SystemManager and triggers prerequisite checks automatically when running openship up.

# Install CLI (requires Node 22+)

curl -fsSL https://get.openship.io | sh

# Run with automatic Docker detection (Compose mode)

openship up

# Run in bare mode (skips Docker checks)

openship up --bare

When checks pass, the CLI launches the Docker Compose stack or starts the bare runtime. If validation fails, the manager logs the specific missing prerequisite and exits with a non-zero status code.

Manual Library Integration

Import SystemManager directly from @openship/adapters to embed prerequisite checks in custom deployment scripts.

# Install the adapters package

npm i @openship/adapters

import { SystemManager } from '@openship/adapters/runtime';

async function validateEnvironment() {
  const manager = new SystemManager();
  const prerequisitesMet = await manager.checkPrerequisites();
  
  if (prerequisitesMet) {
    console.log('Environment validated successfully');
    // Proceed with custom deployment logic
  } else {
    console.error('Prerequisite checks failed');
    process.exit(1);
  }
}

validateEnvironment();

Source Code Architecture

The prerequisite validation logic is implemented across several key files in the oblien/openship repository:

• packages/adapters/src/runtime/index.ts: Contains the SystemManager class and its checkPrerequisites() method implementation.
• packages/adapters/docs/SYSTEM.md: Documents the prerequisite components and their roles in the runtime environment.
• docs/installation.md: Lists required external tools including Docker and Node 22+ with step-by-step installation commands.
• docker/docker-compose.yml: The Compose definition started automatically after Docker-based checks pass.

Summary

• The SystemManager class in packages/adapters/src/runtime/index.ts validates host environments before Openship deployment.
• Three validation stages verify Docker daemon availability (Compose mode), Node.js version ≥ 22, and Linux syscall capabilities.
• The openship up CLI command automatically invokes these checks, while the @openship/adapters library exposes them for programmatic use via checkPrerequisites().
• Failed checks abort deployment with descriptive error messages linking to relevant troubleshooting documentation.

Frequently Asked Questions

What happens if Docker is not installed when running openship up?

If Docker is unavailable, the SystemManager detects the missing requirement during its Docker availability verification phase and exits with a non-zero status. The CLI prints a clear error message indicating Docker is required for Compose mode, along with a link to the installation guide in docs/installation.md.

Can I skip the Docker prerequisite checks?

Yes. Use the --bare flag with the CLI command (openship up --bare) to run in bare mode. This mode skips Docker validation and instead verifies only Node.js 22+ and host OS capabilities, running the control plane as a single process without containerization.

How do I check prerequisites programmatically without starting services?

Import the SystemManager class from @openship/adapters/runtime and call the checkPrerequisites() method. This returns a boolean indicating validation status without triggering the deployment pipeline or starting Postgres, Redis, or other control-plane services.

Which Node.js versions are supported by Openship SystemManager?

The SystemManager requires Node.js 22 or higher. During initialization, it compares the current runtime version against this minimum threshold, aborting execution if the detected version is insufficient for running the modern JavaScript features utilized in the adapters package.

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