# Openship Documentation: Architecture, Deployment, and API Reference > Explore Openship documentation for its architecture, deployment, and API. Deploy applications with zero configuration using this self-hostable CI/CD platform. Learn more now. - Repository: [oblien/openship](https://github.com/oblien/openship) - Tags: api-reference - Published: 2026-07-31 --- **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`](https://github.com/oblien/openship/blob/main/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`](https://github.com/oblien/openship/blob/main/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`](https://github.com/oblien/openship/blob/main/package.json), lockfiles, Docker Compose files, or a custom [`openship.json`](https://github.com/oblien/openship/blob/main/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`](https://github.com/oblien/openship/blob/main/packages/adapters/docs/BUILD-PIPELINE.md). ## Installation Methods ### CLI Installation Install the bundled CLI, which includes the API server and dashboard: ```bash # 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: ```bash # 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: ```bash 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: ```bash openship up --bare ``` Or use the full containerized stack: ```bash openship up --compose ``` ## API Usage Examples Query deployment history using the REST API: ```bash curl -H "Authorization: Bearer " \ https://api.openship.example.com/v1/projects//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`](https://github.com/oblien/openship/blob/main/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`](https://github.com/oblien/openship/blob/main/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`](https://github.com/oblien/openship/blob/main/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`](https://github.com/oblien/openship/blob/main/package.json) (for Node.js projects), lockfiles, [`docker-compose.yml`](https://github.com/oblien/openship/blob/main/docker-compose.yml), or an explicit [`openship.json`](https://github.com/oblien/openship/blob/main/openship.json) configuration file. This detection logic infers build commands, runtime environments, and exposed ports without requiring manual configuration for standard project structures.