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

> Explore Openship usage examples to deploy applications using CLI, desktop, or Docker. This comprehensive platform simplifies your self-hosted deployments with a unified control plane.

- Repository: [oblien/openship](https://github.com/oblien/openship)
- Tags: how-to-guide
- Published: 2026-07-31

---

**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.

```bash

# 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`](https://github.com/oblien/openship/blob/main/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.

```bash
cd my-project
openship init

```

The `init` command writes a [`.openship/project.json`](https://github.com/oblien/openship/blob/main/.openship/project.json) file containing the project identifier and deployment target. According to the source in [`apps/cli/src/commands/init.ts`](https://github.com/oblien/openship/blob/main/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).

```bash
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`](https://github.com/oblien/openship/blob/main/packages/core/src/openship-config/parse.ts) inspects your repository for [`package.json`](https://github.com/oblien/openship/blob/main/package.json), `Dockerfile`, [`openship.json`](https://github.com/oblien/openship/blob/main/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`](https://github.com/oblien/openship/blob/main/packages/core/src/service-routing.ts)).
4. **Route and Secure** – The OpenResty Edge proxy (managed via [`packages/core/src/edge-image-ref.ts`](https://github.com/oblien/openship/blob/main/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`](https://github.com/oblien/openship/blob/main/docker/docker-compose.yml).

### Configure Custom Domains and Automatic TLS

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

```bash
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`](https://github.com/oblien/openship/blob/main/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.

```bash
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`](https://github.com/oblien/openship/blob/main/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.

```bash
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`](https://github.com/oblien/openship/blob/main/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.

```bash
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.

```bash
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`](https://github.com/oblien/openship/blob/main/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`](https://github.com/oblien/openship/blob/main/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`](https://github.com/oblien/openship/blob/main/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`](https://github.com/oblien/openship/blob/main/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`](https://github.com/oblien/openship/blob/main/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`](https://github.com/oblien/openship/blob/main/.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`](https://github.com/oblien/openship/blob/main/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`](https://github.com/oblien/openship/blob/main/packages/core/src/openship-config/parse.ts) scans for [`package.json`](https://github.com/oblien/openship/blob/main/package.json) (Node.js), [`requirements.txt`](https://github.com/oblien/openship/blob/main/requirements.txt) (Python), [`Cargo.toml`](https://github.com/oblien/openship/blob/main/Cargo.toml) (Rust), `Dockerfile`, and [`openship.json`](https://github.com/oblien/openship/blob/main/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`](https://github.com/oblien/openship/blob/main/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`](https://github.com/oblien/openship/blob/main/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`](https://github.com/oblien/openship/blob/main/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.