Openship Project Structure: Modular Architecture and Core Components Guide

Openship organizes its deployment platform into a monorepo where packages/core orchestrates the API and CLI, packages/edge handles routing and TLS, and apps/ delivers Desktop, Web, and CLI interfaces that share a unified control plane.

Openship is an open-source, self-hostable deployment platform developed by oblien/openship that bundles CI/CD pipelines, reverse proxying, and application runtime into a single system. Understanding the Openship project structure reveals how its modular architecture separates the control plane from build pipelines, edge routing, and user interfaces while maintaining consistency across all interaction modes.

Core Control Plane (packages/core)

The central nervous system of Openship resides in packages/core, implementing the API server, command-line interface, and internal orchestration logic.

CLI Bootstrap

packages/core/src/cli.ts serves as the entry point for the command-line interface. This file parses user commands such as openship up, openship init, and openship deploy, then delegates execution to the appropriate handlers within the control plane.

API Server Initialization

packages/core/src/app.ts creates the HTTP server that exposes REST endpoints, MCP (machine-to-machine communication) protocols, and static assets for the web dashboard. This Express-style application server handles incoming requests from all three interfaces (Desktop, Web, and CLI).

Service Registry

packages/core/src/index.ts acts as the wiring harness, instantiating and connecting subsystems including the database layer, Docker integration, edge proxy management, and build pipelines. It exposes these services through a unified API surface used by the rest of the application.

Build and Deployment Pipeline

Openship implements a four-stage deployment pipeline managed through dedicated modules in the core package.

Stack Detection

packages/core/src/pipeline/detect.ts inspects project metadata—specifically package.json, lockfiles, docker-compose.yml, and optional openship.json configurations—to automatically infer the technology stack, package manager, build commands, and exposed ports.

Build Execution

packages/core/src/pipeline/build.ts executes the resolved build process either inside an isolated Docker container or directly on the host system (Bare mode). This module produces immutable artifacts ready for deployment, handling both containerized and binary releases.

Edge Routing and TLS Termination

The packages/edge directory contains the OpenResty-based (NGINX + Lua) reverse proxy implementation.

packages/edge/src/proxy.ts dynamically generates virtual-host configurations for each deployed project and automatically provisions Let's Encrypt certificates via HTTP-01 challenges. The edge proxy runs in host-network mode on ports 80 and 443, routing incoming traffic to the appropriate application containers or processes.

User Interfaces and Applications

Openship provides three distinct interfaces that consume the same control-plane API, ensuring consistent behavior regardless of how users interact with the platform.

• Desktop Application: An Electron-based GUI located in apps/desktop that runs the control plane locally and can drive remote servers via SSH, ideal for solo developers requiring visual deployment management.

• Web Dashboard: A Next.js single-page application configured via apps/dashboard/next.config.mjs, served by the API server at packages/core/src/app.ts, designed for team collaboration and centralized management.

• CLI Tool: A thin, scriptable client that bundles the API and dashboard binary for headless deployments and CI/CD integration.

Adapters and Extensibility

The packages/adapters directory contains pluggable modules that integrate with external services such as cloud providers and secret stores. Each adapter follows a contract-based pattern—implementing required methods and registering with the core service registry defined in packages/core/src/index.ts—allowing developers to extend Openship functionality without modifying core logic.

Self-Hosting Configuration

For production deployments, docker/docker-compose.yml defines the complete infrastructure stack including PostgreSQL for persistence, Redis for caching, the API server, dashboard assets, and the edge proxy.

Practical Usage Examples

Initialize a new project and deploy using the CLI:

# Install the CLI

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

# Create openship.json and link repository

openship init

# Execute full pipeline: detect → build → run → route

openship deploy

Launch a self-hosted instance using Docker Compose:

git clone https://github.com/oblien/openship.git
cd openship
cp .env.example .env
docker compose -f docker/docker-compose.yml up -d

Query the control-plane API directly:

curl -H "Authorization: Bearer $OPENSHIP_TOKEN" \
     http://localhost:3000/api/v1/projects

Summary

• Openship project structure follows a monorepo pattern with clear separation between packages/core (orchestration), packages/edge (routing), and apps/ (interfaces)
• packages/core/src/cli.ts parses all command-line input and initializes the control plane
• packages/core/src/app.ts bootstraps the API server handling REST endpoints and MCP protocols
• packages/core/src/pipeline/detect.ts and build.ts implement the automated build pipeline
• packages/edge/src/proxy.ts manages dynamic routing and automatic TLS certificate provisioning
• Three interfaces (Desktop, Web, CLI) share the same backend API via packages/core/src/index.ts service registry

Frequently Asked Questions

What is the main entry point for the Openship CLI?

The main entry point is packages/core/src/cli.ts, which bootstraps the command-line interface and parses commands such as openship up, openship init, and openship deploy before delegating to the appropriate handlers in the control plane.

How does Openship automatically detect the technology stack for a project?

Stack detection occurs in packages/core/src/pipeline/detect.ts, which inspects project files including package.json, lockfiles, and docker-compose.yml to automatically infer the build command, package manager, and exposed ports without requiring manual configuration.

Where does Openship handle SSL termination and reverse proxy configuration?

Routing and TLS termination are handled by the edge proxy in packages/edge/src/proxy.ts, which uses OpenResty (NGINX with Lua) to dynamically generate virtual-host configurations and automatically provision Let's Encrypt certificates via HTTP-01 challenges.

How do the Desktop, Web, and CLI interfaces interact with the backend?

All three interfaces communicate with the same control-plane API implemented in packages/core/src/app.ts. The Desktop app runs the control plane locally via Electron, the Web dashboard is a Next.js SPA served by the API, and the CLI provides scriptable access to the same endpoints, ensuring consistent behavior across all interaction modes according to the oblien/openship source code.

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