# Openship Release Notes: Architecture, Components, and Deployment Guide

> Explore Openship release notes for this self-hostable CI/CD platform. Discover architecture, components, and deployment guides for efficient project management.

- Repository: [oblien/openship](https://github.com/oblien/openship)
- Tags: release-notes
- Published: 2026-07-31

---

**Openship is a self‑hostable deployment platform that delivers a complete CI/CD pipeline, automatic TLS termination, and unified project management through a control‑plane ↔ target‑plane architecture.**

The latest Openship release provides developers with a comprehensive, self‑hosted alternative to proprietary deployment platforms. These Openship release notes detail the current version's technical architecture, core components, and source file organization as implemented in the `oblien/openship` repository.

## Platform Architecture

Openship follows a **control‑plane ↔ target‑plane** model that separates management logic from execution environments. The architecture supports two distinct runtime modes selected automatically based on the host environment.

### Control Plane Components

The **CLI / Control Plane** serves as the primary entry point for installing, configuring, and managing Openship instances. It drives backend services through programmatic APIs and provides the `openship` and `openship‑dev` command sets.

The **API Server** (`packages/api`) implements a lightweight Node.js/Go service that stores project metadata, processes webhook events, and orchestrates build pipelines. It handles the core logic for the Detect → Build → Run workflow.

### Target Plane Components

The **Edge (OpenResty)** component runs as an Nginx/OpenResty container defined in [`docker/docker-compose.yml`](https://github.com/oblien/openship/blob/main/docker/docker-compose.yml). It automatically writes per‑domain reverse‑proxy vhosts and provisions **Let's Encrypt** certificates via HTTP‑01 challenges.

The **Dashboard (Web UI)** renders as a React‑based Next.js application. The primary entry point resides at `apps/web/src/app/(site)/dashboard/page.tsx`, presenting the same interface available in the desktop client.

The **Desktop App** provides an Electron‑based client configured via [`apps/desktop/forge.config.js`](https://github.com/oblien/openship/blob/main/apps/desktop/forge.config.js). It runs the control plane locally in **solo mode**, offering real‑time logs and one‑click deployment through a native GUI.

## Runtime Modes

Openship automatically selects between deployment strategies based on host capabilities, with manual override flags available.

**Compose Mode** (Docker‑Compose) represents the default on Linux systems with Docker available. This mode runs a full stack including Postgres, Redis, API, Dashboard, and Edge services, hosting user applications on the same host.

**Bare Mode** operates on macOS, Windows, or Linux without Docker. It launches as a single process with an embedded database, deploying applications to remote SSH hosts or Openship Cloud.

## Deployment Workflow

The Openship release implements a five‑stage deployment pipeline:

1. **Detect** – Inspects [`package.json`](https://github.com/oblien/openship/blob/main/package.json), lockfiles, Docker Compose files, or optional [`openship.json`](https://github.com/oblien/openship/blob/main/openship.json) to infer stack configuration, build commands, and exposed ports.
2. **Build** – Constructs either Docker images (Compose mode) or bare binaries/processes (Bare mode). The resolved configuration persists as a **snapshot** for reproducible redeploys.
3. **Run** – Starts artifacts as containers with private loopback ports or as supervised host processes.
4. **Route + Secure** – The Edge service generates reverse‑proxy vhosts and automatically provisions TLS certificates.
5. **Push‑to‑Deploy** – GitHub webhooks retrigger the pipeline on every push, rebuilding only affected services in monorepo configurations.

## Getting Started with Openship

Install the CLI using the one‑liner installer:

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

# or: npm i -g openship

```

Initialize a project in your repository:

```bash
cd my-project
openship init

```

This creates `.openship` metadata and generates an [`openship.json`](https://github.com/oblien/openship/blob/main/openship.json) file for custom overrides, storing configuration data in the API module.

Deploy using push‑to‑deploy functionality:

```bash
openship deploy

```

The CLI contacts the API server, triggering the build stage, storing a snapshot, starting the application, and requesting the Edge service to create domain‑specific vhosts.

Run a self‑hosted instance in Compose mode:

```bash
openship up --compose

```

This command spawns Docker Compose using the configuration defined in [`docker/docker-compose.yml`](https://github.com/oblien/openship/blob/main/docker/docker-compose.yml), launching Postgres, Redis, API, Dashboard, and Edge services.

For macOS or systems without Docker, use Bare mode:

```bash
openship up --bare

```

This launches a single Go binary embedding SQLite that directly invokes the build pipeline for remote SSH targets.

Access the web dashboard at `http://localhost:3000` after server initialization, rendered by the Next.js route at `apps/web/src/app/(site)/dashboard/page.tsx`.

## Key Source Files

The Openship release organizes code within a **Turborepo monorepo** structure split between `apps/*` and `packages/*`.

**[`apps/desktop/forge.config.js`](https://github.com/oblien/openship/blob/main/apps/desktop/forge.config.js)** configures the Electron‑Forge build system for the desktop client, enabling solo mode operation with embedded control plane binaries.

**`apps/web/src/app/(site)/dashboard/page.tsx`** serves as the Next.js entry point for the web‑based dashboard, implementing the React interface used across platforms.

**[`packages/ui/src/components/button.tsx`](https://github.com/oblien/openship/blob/main/packages/ui/src/components/button.tsx)** demonstrates the shared component architecture, providing UI elements consumed by both desktop and web applications.

**[`docker/docker-compose.yml`](https://github.com/oblien/openship/blob/main/docker/docker-compose.yml)** defines the complete Compose stack, specifying service dependencies including Postgres, Redis, API, Dashboard, and the OpenResty Edge container.

**[`README.md`](https://github.com/oblien/openship/blob/main/README.md)** (root) contains the authoritative documentation covering quick‑start procedures, architectural decisions, and interface specifications.

**[`CONTRIBUTING.md`](https://github.com/oblien/openship/blob/main/CONTRIBUTING.md)** and **[`SECURITY.md`](https://github.com/oblien/openship/blob/main/SECURITY.md)** provide community guidelines and vulnerability disclosure policies respectively.

## Summary

- Openship implements a **control‑plane ↔ target‑plane** architecture supporting both Docker Compose and bare‑metal deployments.
- The platform provides **three interchangeable interfaces**: Desktop app, Web dashboard, and CLI, backed by a unified MCP/REST API.
- **Automatic TLS termination** and reverse‑proxy configuration occur via the OpenResty Edge service.
- The **monorepo structure** utilizes Turborepo to share components between `apps/desktop`, `apps/web`, and `packages/ui`.
- Source code critical paths include `packages/api` for orchestration logic and [`docker/docker-compose.yml`](https://github.com/oblien/openship/blob/main/docker/docker-compose.yml) for service definitions.

## Frequently Asked Questions

### What deployment modes does Openship support?

Openship supports **Compose mode** for Docker‑based deployments on Linux and **Bare mode** for single‑process operation on macOS, Windows, or Linux without Docker. The CLI automatically selects the appropriate mode based on the host environment, though you can force a specific mode using `--compose` or `--bare` flags.

### How does Openship handle SSL certificates?

The **Edge service** (OpenResty/Nginx) automatically provisions **Let's Encrypt** certificates using HTTP‑01 validation. When you deploy an application, the Edge container writes a domain‑specific reverse‑proxy vhost and obtains TLS certificates without manual intervention.

### Where is the web dashboard source code located?

The web dashboard source resides in `apps/web/src/app/(site)/dashboard/page.tsx`. This Next.js React component renders the same interface available in the Electron desktop application, sharing UI components from `packages/ui/src/components/`.

### What is the difference between the Desktop App and the Web Dashboard?

The **Desktop App** (configured in [`apps/desktop/forge.config.js`](https://github.com/oblien/openship/blob/main/apps/desktop/forge.config.js)) runs the control plane locally in **solo mode** as a background process, providing native OS integration and offline capabilities. The **Web Dashboard** connects to a remote or local API server via browser and is served from `apps/web`.