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

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

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, and architectural details are documented in 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.

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

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

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
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:

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 – High-level overview, quick-start guide, and architecture summary
• docs/installation.md – Detailed installation instructions for desktop, self-hosted, and cloud deployments
• apps/email/ARCHITECTURE.md – Blueprint of the self-hosted email subsystem and database topology
• packages/db-email/src/schema/vmail.ts – Drizzle schema mirroring iRedMail's PostgreSQL tables
• docker/docker-compose.yml – Complete Docker stack definition for self-hosted environments
• apps/cli/tsup.config.ts – Build configuration for the CLI binary
• 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
• Extensions follow modular patterns: add providers in apps/api/src/modules/, register in 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, docs/installation.md, and architecture-specific files like apps/email/ARCHITECTURE.md. The 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. 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 to adapt database creation logic, then update 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.

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