Openship Documentation: Architecture, Deployment, and API Reference

Openship is an open-source, self-hostable deployment platform that bundles a full CI/CD pipeline, edge routing, TLS termination, and a multi-interface control plane for zero-configuration application hosting.

This guide covers the complete Openship documentation based on the oblien/openship repository, detailing its architecture, core components, and practical usage for developers who need self-hosted deployment infrastructure.

Control Plane Architecture

The control plane orchestrates builds, stores configuration snapshots, and drives deployments across three interfaces: the CLI (openship), desktop application, and web dashboard. All interfaces communicate with the same backend services located in apps/api and core libraries under packages/core.

API Entry Points

The primary API surface resides in apps/api/src/lib/git-forwarding/README.md, which documents the git-forwarding utilities and core API entry points. The system exposes a REST/MCP API that all client interfaces consume, with the MCP (Machine-Callable-Program) endpoint deliberately limited to safe, permission-checked operations that never expose raw credentials.

Data Persistence

Openship persists project metadata, deployment history, and user information using PostgreSQL as the primary database and Redis for caching. Database schemas and migration scripts are located in the packages/core package, automatically applied when running the Docker stack defined in docker/docker-compose.yml.

Edge Proxy and Routing

The edge proxy handles reverse-proxy routing, automatic Let's Encrypt TLS certificates, and HTTP/3/CDN features. Implemented with OpenResty (NGINX + Lua) and bundled as a Docker container, the edge writes vhost files dynamically and renews certificates after each successful deployment.

According to the source code, failure to obtain a certificate does not abort the deployment. The application continues running while the system prompts the user to fix DNS or SSL configuration issues, ensuring zero-downtime deployments even during certificate provisioning delays.

CI/CD Pipeline

The build system detects your project stack, constructs Docker images (or bare releases), and runs the resulting service. Core detection logic lives in packages/core/src/apps, which parses package.json, lockfiles, Docker Compose files, or a custom openship.json to infer build commands and exposed ports.

Build Process

1. Detection – Reads manifest files to infer the required runtime stack
2. Build – Constructs Docker images or bare binaries on the target host, snapshotting configuration for reproducible rollbacks
3. Run – Launches artifacts as isolated containers (loopback-only) or supervised host processes
4. Routing – Provisions reverse-proxy vhosts and obtains Let's Encrypt certificates via HTTP-01
5. Push-to-Deploy – GitHub webhooks automatically re-run the pipeline on each push, rebuilding only changed services

Detailed pipeline documentation is available in packages/adapters/docs/BUILD-PIPELINE.md.

Installation Methods

CLI Installation

Install the bundled CLI, which includes the API server and dashboard:

# Option 1: Direct shell install

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

# Option 2: NPM global install

npm i -g openship

Quick Start Commands

Initialize and deploy a project using the CLI workflow:

# Initialize project (creates openship.json and links repo)

openship init

# Deploy current revision

openship deploy

# Open web dashboard in default browser

openship open

# Stop the control plane

openship stop

Docker Compose Deployment

For manual stack management without the CLI, use the raw Docker Compose configuration:

git clone https://github.com/oblien/openship.git && cd openship
cp .env.example .env

# Edit .env with your configuration

docker compose -f docker/docker-compose.yml up -d

This stack includes PostgreSQL, Redis, the API server, web dashboard, and the OpenResty edge proxy.

Bare Metal Mode

Run Openship as a single process without Docker:

openship up --bare

Or use the full containerized stack:

openship up --compose

API Usage Examples

Query deployment history using the REST API:

curl -H "Authorization: Bearer <YOUR_TOKEN>" \
     https://api.openship.example.com/v1/projects/<project-id>/deployments

The MCP API endpoint accepts structured requests for AI agents and automation tools, implementing strict permission checks on all operations.

Extensibility and Adapters

The packages/adapters directory contains plugins for various cloud providers, email services, and storage backends. Adapter architecture is documented in packages/adapters/docs/ARCHITECTURE.md, detailing how to extend Openship with custom build environments or deployment targets.

The platform bundles auxiliary services including automatic backups, built-in SMTP with DKIM/SPF/DMARC verification, CDN edge caching, and a lightweight administrative interface.

Summary

• Openship combines a control plane, edge proxy, and CI/CD pipeline into a single self-hosted platform located at oblien/openship
• Three interfaces (CLI, desktop, web) communicate with the same REST/MCP API defined in apps/api/src/lib/git-forwarding/README.md
• Stack detection occurs in packages/core/src/apps, supporting Node.js, Docker, and custom configurations via openship.json
• Edge routing uses OpenResty with automatic Let's Encrypt provisioning, continuing deployments even if certificate issuance fails initially
• Deployment modes include containerized (--compose) and bare metal (--bare) operation
• Extensibility is handled through the adapter system in packages/adapters/

Frequently Asked Questions

What is the difference between Openship's CLI and Docker Compose deployment methods?

The CLI (openship up --compose) provides orchestrated management with automated database migrations and service initialization, while manually running docker compose -f docker/docker-compose.yml up -d gives you direct control over the container stack defined in the repository. Both methods use the same underlying services—PostgreSQL, Redis, API, and OpenResty edge—but the CLI streamlines initialization and configuration management.

Where does Openship store deployment configuration and build snapshots?

Configuration snapshots and project metadata persist in PostgreSQL, with Redis handling caching layers. The database schemas and migration scripts reside in the packages/core package. This architecture enables reproducible rollbacks, as the system snapshots build configurations alongside deployment history.

How does Openship handle automatic HTTPS and certificate renewal?

The OpenResty-based edge proxy provisions certificates via Let's Encrypt HTTP-01 challenges after each successful deployment. The system writes vhost configurations dynamically and manages TLS termination. If certificate issuance fails due to DNS propagation delays, the deployment continues running on HTTP while alerting the user to fix SSL configuration, preventing downtime during certificate troubleshooting.

What file does Openship check to detect my project's build requirements?

The detection engine in packages/core/src/apps parses multiple manifest sources, including package.json (for Node.js projects), lockfiles, docker-compose.yml, or an explicit openship.json configuration file. This detection logic infers build commands, runtime environments, and exposed ports without requiring manual configuration for standard project structures.

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