# Openship Developer Documentation: A Complete Guide to Extending oblien/openship

> Explore the Openship developer documentation for oblien/openship. Learn about architecture, extension points, and API references to effectively extend this modular platform.

- Repository: [oblien/openship](https://github.com/oblien/openship)
- Tags: architecture
- Published: 2026-07-29

---

**Yes, oblien/openship provides comprehensive developer documentation covering architecture, extension points, and API references across its modular deployment platform.**

The oblien/openship repository is a modular, open-source deployment platform that supports desktop, self-hosted, and cloud configurations. This guide consolidates the essential developer resources, architecture patterns, and extension mechanisms found throughout the codebase to help you build upon the platform effectively.

## Architecture Overview

Openship is structured around three distinct architectural layers that work together to provide deployment orchestration, traffic management, and service abstraction.

### Control Plane

The **Control Plane** forms the core Openship backend, encompassing the API, dashboard, and CLI. It orchestrates builds, deployments, routing, and TLS certificate management. Depending on your deployment mode, this layer runs locally (desktop app) or on a persistent Linux server (self-hosted). The implementation details are documented in the repository's [`README.md`](https://github.com/oblien/openship/blob/main/README.md) under the "How It Works" section.

### Edge Layer

The **Edge Layer** utilizes OpenResty (NGINX + Lua) as a reverse proxy that terminates TLS via Let's Encrypt and routes traffic to deployed applications. In self-hosted environments, this component is defined in [`docker/docker-compose.yml`](https://github.com/oblien/openship/blob/main/docker/docker-compose.yml), which brings up the complete stack including Postgres, Redis, API, dashboard, and the edge proxy.

### Service Modules

Each supported technology stack (Node.js, Python, Go, Docker, etc.) is implemented as a plugin that defines build and runtime behaviors. The platform also includes a **self-hosted email service** built on iRedMail, with a dedicated Drizzle schema located in `packages/db-email`.

## Core Developer Concepts

Understanding these fundamental concepts is essential for navigating the oblien/openship developer documentation and contributing effectively.

### Projects

A **Project** represents a directory linked to an Openship project via the `openship init` command. Project metadata is stored locally in [`.openship/project.json`](https://github.com/oblien/openship/blob/main/.openship/project.json). The CLI command handling is implemented in `apps/cli`, with detailed references available in the README.

### Deployments

**Deployments** are pipelines that detect the application stack, build Docker images (or bare processes), and start services. The deployment logic resides in `apps/api/src/modules/deployments/`, where the API handles the complete CI/CD orchestration.

### Routing and TLS

OpenResty automatically generates virtual host configurations and obtains TLS certificates following successful deployments. The routing logic is controlled by the edge controller in `packages/core/src/mail-server/routing`, while the Docker composition is defined in [`docker/docker-compose.yml`](https://github.com/oblien/openship/blob/main/docker/docker-compose.yml).

### Mail Service

The email subsystem uses iRedMail for SMTP/IMAP functionality. The Openship admin UI writes directly to the `vmail` schema via Drizzle ORM, with no public admin endpoint exposed—all mailbox management is handled internally. The schema is defined in [`packages/db-email/src/schema/vmail.ts`](https://github.com/oblien/openship/blob/main/packages/db-email/src/schema/vmail.ts), and architectural details are documented in [`apps/email/ARCHITECTURE.md`](https://github.com/oblien/openship/blob/main/apps/email/ARCHITECTURE.md).

### Interfaces

Openship exposes three primary interfaces:

- **Desktop App**: GUI with embedded local control plane
- **Web Dashboard**: Browser-based interface sharing the same UI components
- **CLI**: Scriptable, CI-friendly interface also used for self-hosting operations

The UI component library shared across these interfaces is located in `packages/ui/src/components/`, such as [`packages/ui/src/components/button.tsx`](https://github.com/oblien/openship/blob/main/packages/ui/src/components/button.tsx).

## Extending Openship

The oblien/openship developer documentation outlines clear patterns for extending platform capabilities through modular additions.

### Adding a New Build Provider

To add support for a new technology stack:

1. Create a module under `apps/api/src/modules/<provider>/` implementing the detect-build-run contract
2. Register the provider in the central registry at [`packages/core/src/providers.ts`](https://github.com/oblien/openship/blob/main/packages/core/src/providers.ts)

This pattern allows the platform to automatically detect and build applications using your custom provider logic.

### Integrating a New Service

When adding services like custom databases:

1. Create a new Drizzle schema package (e.g., `packages/db-<name>/`)
2. Write migration files in `drizzle/*.sql`
3. Expose a client similar to [`packages/db-email/src/client.ts`](https://github.com/oblien/openship/blob/main/packages/db-email/src/client.ts)

This approach maintains consistency with the existing email service architecture.

### Customizing the Email Service

To modify email functionality:

1. Adapt the database creation logic in [`apps/email/engine/functions/postgresql.sh`](https://github.com/oblien/openship/blob/main/apps/email/engine/functions/postgresql.sh)
2. Update the Drizzle schema in `packages/db-email/src/schema/` to reflect additional columns or tables

The following example demonstrates creating a mailbox via the admin API:

```typescript
import { db } from "@repo/db-email";

async function createMailbox(userId: string, address: string) {
  await db
    .insertInto("mailbox")
    .values({
      username: address,
      domain: address.split("@")[1],
      password: await hashPassword("random-secure"),
      name: "New User",
      active: 1,
    })
    .run();
}

```

### Exposing New API Endpoints

To extend the API surface:

1. Define tRPC controllers in `apps/api/src/modules/<module>/controllers`
2. Implement permission checks using the policy framework in `packages/core/src/auth`

This ensures new endpoints maintain the platform's security standards and type safety.

## Essential Developer Resources

The oblien/openship developer documentation is distributed across these key files:

- **[`README.md`](https://github.com/oblien/openship/blob/main/README.md)** – High-level overview, quick-start guide, and architecture summary
- **[`docs/installation.md`](https://github.com/oblien/openship/blob/main/docs/installation.md)** – Detailed installation instructions for desktop, self-hosted, and cloud deployments
- **[`apps/email/ARCHITECTURE.md`](https://github.com/oblien/openship/blob/main/apps/email/ARCHITECTURE.md)** – Blueprint of the self-hosted email subsystem and database topology
- **[`packages/db-email/src/schema/vmail.ts`](https://github.com/oblien/openship/blob/main/packages/db-email/src/schema/vmail.ts)** – Drizzle schema mirroring iRedMail's PostgreSQL tables
- **[`docker/docker-compose.yml`](https://github.com/oblien/openship/blob/main/docker/docker-compose.yml)** – Complete Docker stack definition for self-hosted environments
- **[`apps/cli/tsup.config.ts`](https://github.com/oblien/openship/blob/main/apps/cli/tsup.config.ts)** – Build configuration for the CLI binary
- **[`packages/ui/src/components/button.tsx`](https://github.com/oblien/openship/blob/main/packages/ui/src/components/button.tsx)** – Example from the shared UI component library

## Summary

- Openship uses a three-layer architecture: Control Plane, Edge Layer (OpenResty), and Service Modules
- Projects are managed via CLI commands that maintain local metadata in [`.openship/project.json`](https://github.com/oblien/openship/blob/main/.openship/project.json)
- Extensions follow modular patterns: add providers in `apps/api/src/modules/`, register in [`packages/core/src/providers.ts`](https://github.com/oblien/openship/blob/main/packages/core/src/providers.ts)
- The email service uses Drizzle ORM to manage iRedMail's `vmail` schema directly
- New API endpoints use tRPC controllers with policy-based authentication in `packages/core/src/auth`

## Frequently Asked Questions

### Where is the main developer documentation located?

The primary documentation is distributed across the repository's [`README.md`](https://github.com/oblien/openship/blob/main/README.md), [`docs/installation.md`](https://github.com/oblien/openship/blob/main/docs/installation.md), and architecture-specific files like [`apps/email/ARCHITECTURE.md`](https://github.com/oblien/openship/blob/main/apps/email/ARCHITECTURE.md). The [`README.md`](https://github.com/oblien/openship/blob/main/README.md) provides the high-level overview and quick-start instructions, while specialized documentation covers specific subsystems like the email service and deployment pipelines.

### How do I add support for a new programming language?

Create a new build provider module in `apps/api/src/modules/<provider>/` that implements the detect-build-run contract, then register it in [`packages/core/src/providers.ts`](https://github.com/oblien/openship/blob/main/packages/core/src/providers.ts). This allows the deployment pipeline to automatically detect projects using your language and execute the appropriate build steps.

### Can I modify the email service schema?

Yes, modify [`apps/email/engine/functions/postgresql.sh`](https://github.com/oblien/openship/blob/main/apps/email/engine/functions/postgresql.sh) to adapt database creation logic, then update [`packages/db-email/src/schema/vmail.ts`](https://github.com/oblien/openship/blob/main/packages/db-email/src/schema/vmail.ts) to reflect any schema changes. The platform uses Drizzle ORM to manage the iRedMail `vmail` database directly, so changes must be synchronized between the SQL initialization scripts and the TypeScript schema definitions.

### What is the best way to contribute new API endpoints?

Define tRPC controllers in `apps/api/src/modules/<module>/controllers` and implement permission checks using the policy framework located in `packages/core/src/auth`. This approach ensures type safety, consistent error handling, and proper authorization across all platform interfaces.