oblien/openship Examples: A Complete Guide to Sample Code and Usage

The oblien/openship repository provides extensive ready-to-run examples covering CLI usage, Docker-Compose deployment, configuration parsing, and edge-proxy definitions scattered across documentation, test suites, and dedicated example files.

The oblien/openship codebase ships with practical, copy-paste-ready samples that demonstrate how to deploy applications, configure custom domains, and migrate from existing proxy solutions. These examples live in the main README, test files, and package-specific directories, offering authoritative reference implementations for both beginners and advanced users.

Getting Started with oblien/openship Examples

CLI Quick-Start Samples

The fastest way to understand the Openship workflow is through the CLI examples documented in README.md. These samples demonstrate the standard installation pattern and deployment commands used across the platform.

To install the CLI and deploy your first project:

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

According to the oblien/openship source code at README.md (lines 78-84), this three-step process installs the binary, links your current folder to an Openship project, and triggers a build-and-deploy cycle.

Docker-Compose Self-Hosting Setup

For users preferring self-hosted infrastructure, the repository includes a complete Docker-Compose stack definition. The example in README.md (lines 21-28) shows how to bootstrap the full architecture including Postgres, Redis, API, Dashboard, and Edge components.

Clone the repository and launch the stack:

git clone https://github.com/oblien/openship.git && cd openship
cp .env.example .env
docker compose --env-file .env -f docker/docker-compose.yml up -d

The docker/docker-compose.yml file referenced here orchestrates the entire platform without requiring the CLI tool, making it ideal for production environments or CI/CD pipelines.

Configuration and Domain Examples

Parsing openship.json Configurations

Deep in the core package, packages/core/src/openship-config/parse.test.ts (lines 17-33) contains executable examples showing how Openship validates and normalizes configuration objects. These tests serve as living documentation for the expected schema.

Example configuration structure:

const config = {
  domains: [
    "app.example.com",
    { domain: "api.example.com", port: 8080, type: "custom" }
  ]
};

The parser handles both string domains and complex objects with custom ports, validating entries before they reach the deployment stage.

Environment Variable Templates

The repository ships an .env.example file referenced at line 125 of README.md, providing a complete template for environment configuration. This sample includes all required variables for database connections, Redis URLs, and API keys needed by the Docker-Compose stack.

Edge Proxy and Routing Samples

Rewrite Rules and Proxy Definitions

The edge router implementation includes concrete routing examples in packages/adapters/test/vercel-routing.test.ts (lines 35-39). These samples demonstrate the rewrite rule syntax that the proxy consumes.

Example proxy configuration:

const routing = {
  rewrites: [{ source: "/proxy/(.*)", destination: "https://api.example.com/$1" }],
  pathPrefix: "/proxy/",
  targetUrl: "https://api.example.com/$1"
};

This pattern captures path segments and forwards them to upstream services, supporting dynamic routing without manual reverse-proxy configuration.

Traefik and Caddy Import Examples

For users migrating existing infrastructure, oblien/openship provides import utilities with working samples. The Traefik adapter in packages/adapters/src/system/proxy/import/traefik.test.ts (lines 16-23) demonstrates converting Docker labels into Openship routing definitions.

Traefik label import example:

const labels = {
  "traefik.http.routers.web.rule": "Host(`app.example.com`)"
};

After import, the system generates route objects with serverNames: ["app.example.com"], preserving your existing routing logic while migrating to the Openship platform.

Similarly, packages/adapters/src/system/proxy/import/proxy-import.test.ts (lines 218-225) shows Caddyfile conversion into internal route structures, enabling seamless transitions from Caddy-based deployments.

Utility and Validation Examples

Email Validation Logic

The core package includes test-driven examples of built-in validators at packages/core/src/email.test.ts (lines 27-33). These samples illustrate how the platform validates email addresses for the mail server component, providing patterns you can reference when configuring notification settings or user authentication.

Domain Normalization

Hostname handling examples reside in packages/core/test/normalize-custom-hostname.test.ts (lines 9-17). These tests demonstrate how Openship strips protocols, handles ports, and standardizes custom hostnames before processing, ensuring consistent behavior across different input formats.

Summary

• The oblien/openship repository maintains examples in README.md, test files, and configuration templates rather than a dedicated /examples directory.
• CLI examples in README.md (lines 78-84) provide the fastest path from installation to deployment.
• Docker-Compose samples in docker/docker-compose.yml demonstrate production-ready self-hosting with full stack orchestration.
• Configuration parsing tests in packages/core/src/openship-config/parse.test.ts define the exact schema for openship.json files.
• Proxy routing examples in packages/adapters/test/vercel-routing.test.ts show how to define rewrite rules and edge routing logic.
• Import utilities for Traefik and Caddy include working code samples for migrating existing reverse-proxy configurations.

Frequently Asked Questions

Where are the main oblien/openship examples located?

The primary examples reside in three locations: the README.md file contains CLI and Docker-Compose quick-starts, the packages/ directory hosts test files that serve as executable documentation, and the docker/ folder contains infrastructure templates. Unlike repositories with a top-level /examples folder, oblien/openship embeds samples within the code they test.

Can I run the oblien/openship examples without installing the CLI?

Yes. The docker/docker-compose.yml file provides a complete self-hosted stack that runs independently of the CLI tool. Copy the .env.example file to .env, configure your variables, and run docker compose up to launch the full platform including the dashboard, API, and edge proxy.

How do the test files serve as examples in oblien/openship?

Files like packages/core/src/openship-config/parse.test.ts and packages/adapters/test/vercel-routing.test.ts contain runnable code that demonstrates valid input formats and expected behaviors. Because these tests must compile and pass, they represent guaranteed-accurate examples of how to structure configurations, define routing rules, and import existing proxy definitions.

Does oblien/openship provide examples for migrating from Traefik or Caddy?

Yes. The adapter package includes specific import examples: packages/adapters/src/system/proxy/import/traefik.test.ts shows converting Traefik Docker labels into Openship routes, while packages/adapters/src/system/proxy/import/proxy-import.test.ts demonstrates Caddyfile parsing. These samples enable zero-downtime migration from existing reverse-proxy setups.

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