Openship Release Notes: Architecture, Components, and Deployment Guide

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. 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. 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, lockfiles, Docker Compose files, or optional 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:

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

# or: npm i -g openship

Initialize a project in your repository:

cd my-project
openship init

This creates .openship metadata and generates an openship.json file for custom overrides, storing configuration data in the API module.

Deploy using push‑to‑deploy functionality:

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:

openship up --compose

This command spawns Docker Compose using the configuration defined in docker/docker-compose.yml, launching Postgres, Redis, API, Dashboard, and Edge services.

For macOS or systems without Docker, use Bare mode:

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 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 demonstrates the shared component architecture, providing UI elements consumed by both desktop and web applications.

docker/docker-compose.yml defines the complete Compose stack, specifying service dependencies including Postgres, Redis, API, Dashboard, and the OpenResty Edge container.

README.md (root) contains the authoritative documentation covering quick‑start procedures, architectural decisions, and interface specifications.

CONTRIBUTING.md and 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 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) 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.

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