Openship Usage Examples: Deploy Applications with CLI, Desktop, and Docker

Openship is a self-hostable deployment platform that bundles CI/CD, TLS termination, routing, databases, and backups into a single control plane, enabling you to deploy applications through a desktop GUI, web dashboard, or CLI that all invoke the same backend services.

Openship (oblien/openship) unifies deployment workflows across three interchangeable interfaces while automatically detecting your stack, building containers, and securing traffic with Let's Encrypt. Whether you self-host on a VPS or use the managed service, the platform handles the entire pipeline from source code to running application. Below are practical Openship usage examples derived from the source code, covering initialization, deployment, monitoring, and maintenance.

Installing the Openship CLI and Initializing Projects

Install the CLI or Desktop Application

You can install Openship through several distribution channels. The CLI is distributed as a standalone binary, an npm package, or bundled within the desktop application.

# Download the official installer script (detects OS and architecture)

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

# Alternative: Install via npm

npm i -g openship

# Linux users can also run the AppImage directly

chmod +x Openship.AppImage && ./Openship.AppImage

The installer places the openship binary in your system path, enabling immediate access to deployment commands documented in docs/installation.md.

Initialize a Local Project

Before deploying, you must link your local source directory to an Openship project. This creates a persistent configuration file that subsequent commands reference.

cd my-project
openship init

The init command writes a .openship/project.json file containing the project identifier and deployment target. According to the source in apps/cli/src/commands/init.ts, this JSON file serves as the anchor for all subsequent operations like deploy, logs, and env management.

Deploying Applications with Openship

Deploy Your Application

The core deployment command triggers a five-stage pipeline that works identically across all three interfaces (desktop, web, CLI).

openship deploy

The pipeline executes the following steps as implemented in the source:

1. Detect – The parser in packages/core/src/openship-config/parse.ts inspects your repository for package.json, Dockerfile, openship.json, and other markers to infer the language, package manager, and start command.
2. Build – The system produces either a Docker image (Compose mode) or a native binary artifact, storing the result as a deployment snapshot in the storage layer.
3. Run – The worker runtime launches the artifact. In Compose mode, this spins up a Docker container; in Bare mode, it supervises a host process (see packages/core/src/service-routing.ts).
4. Route and Secure – The OpenResty Edge proxy (managed via packages/core/src/edge-image-ref.ts) writes virtual-host configurations, obtains TLS certificates, and enables HTTP/3 and Brotli compression.
5. Push-to-Deploy – If configured, GitHub webhooks automatically re-trigger this pipeline on every push to the repository.

If targeting a self-hosted server, the CLI automatically provisions the full infrastructure stack (Postgres, Redis, API, Dashboard, Edge) using the Compose file at docker/docker-compose.yml.

Configure Custom Domains and Automatic TLS

Openship automates domain routing and certificate management through the edge proxy.

openship domain add myapp.example.com

The edge proxy performs HTTP-01 validation against Let's Encrypt and writes the vhost configuration without interrupting running applications. As implemented in packages/core/src/edge-image-ref.ts, certificate failures surface as "action required" states in the dashboard rather than deployment crashes.

Monitoring and Maintenance Operations

Stream Logs in Real-Time

The unified logging pipeline aggregates output from both containerized and bare-metal processes.

openship logs <deployment-id> -f --tail 100

The -f flag enables live streaming, while --tail limits historical output. The implementation in packages/core/src/service-status.ts normalizes log streams from Docker daemon sockets or supervised process pipes into a single interface.

Update the Control Plane

Self-hosted instances can upgrade to the latest release without manual container management.

openship update

This command pulls the latest release artifacts and restarts the control plane services while preserving persistent data volumes defined in docker/docker-compose.yml.

Reset Admin Credentials

If you lose access to the web dashboard on a self-hosted instance, regain entry without database manipulation.

openship reset-admin-password

This command rewrites the local admin authentication token directly, bypassing the standard OAuth flow as documented in the repository's security section.

Self-Hosting with Raw Docker Compose

You can deploy the entire Openship infrastructure without using the CLI installer by running the official Compose stack directly.

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

# Edit .env to set your domain and secrets

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

This launches the complete control plane including the API server, web dashboard, Postgres, Redis, and OpenResty edge proxy. The configuration in docker/docker-compose.yml matches the orchestration logic used internally by the openship deploy command.

Architecture Overview

Understanding the components referenced in these usage examples helps troubleshoot deployments:

• Control Plane (apps/cli, apps/api): Orchestrates builds, stores metadata, and exposes the REST API that all three interfaces consume.
• OpenResty Edge (packages/core/src/edge-image-ref.ts): Reverse-proxy that terminates TLS, handles domain routing, and manages certificate renewals.
• Worker Runtime (packages/core/src/service-routing.ts): Executes built artifacts in either containerized or bare-metal mode.
• Metadata Parser (packages/core/src/openship-config/parse.ts): Detects application stacks and extracts build commands from configuration files.
• Storage Layer (packages/core/src/object-storage.ts): Persists project definitions, deployment snapshots, and backup archives.

Summary

• Install Openship using the official installer, npm, or AppImage to access the CLI and desktop interface.
• Initialize projects with openship init to create .openship/project.json and link local folders to remote projects.
• Deploy effortlessly using openship deploy, which automatically detects your stack, builds containers, and provisions TLS certificates.
• Monitor logs in real-time with openship logs, supporting both Docker and bare-mode deployments through a unified pipeline.
• Self-host completely by running docker/docker-compose.yml directly on any Linux server with Docker Engine installed.

Frequently Asked Questions

How does Openship detect my application stack?

Openship analyzes your repository root for common configuration files. The parser in packages/core/src/openship-config/parse.ts scans for package.json (Node.js), requirements.txt (Python), Cargo.toml (Rust), Dockerfile, and openship.json to infer the build command, start command, and exposed ports without requiring manual configuration.

What is the difference between Docker Compose mode and Bare mode?

Docker Compose mode builds a container image and runs it via the Docker daemon, providing full isolation and supporting complex multi-service definitions. Bare mode compiles native binaries and supervises them as host processes, which reduces overhead on resource-constrained machines or when running the desktop application locally. The routing logic in packages/core/src/service-routing.ts abstracts this difference so that domain management and logging work identically in both scenarios.

How does Openship handle SSL certificates?

The OpenResty Edge proxy (configured via packages/core/src/edge-image-ref.ts) automatically provisions Let's Encrypt certificates using HTTP-01 validation when you add domains via openship domain add. Certificates persist in the storage layer and renew automatically without application downtime.

Can I use Openship without installing the CLI?

Yes. The repository includes a complete Docker Compose stack at docker/docker-compose.yml that launches the API, dashboard, and edge proxy. You can manage deployments entirely through the web dashboard or REST API once the containers are running, though the CLI provides convenient wrapper commands for local development workflows.

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