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

> Explore oblien/openship examples. Discover ready-to-run sample code for CLI, Docker-Compose, configuration, and edge-proxy in this comprehensive guide.

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

---

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

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

```

According to the oblien/openship source code at [`README.md`](https://github.com/oblien/openship/blob/main/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`](https://github.com/oblien/openship/blob/main/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:

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

```typescript
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`](https://github.com/oblien/openship/blob/main/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`](https://github.com/oblien/openship/blob/main/packages/adapters/test/vercel-routing.test.ts) (lines 35-39). These samples demonstrate the rewrite rule syntax that the proxy consumes.

Example proxy configuration:

```typescript
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`](https://github.com/oblien/openship/blob/main/packages/adapters/src/system/proxy/import/traefik.test.ts) (lines 16-23) demonstrates converting Docker labels into Openship routing definitions.

Traefik label import example:

```typescript
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`](https://github.com/oblien/openship/blob/main/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`](https://github.com/oblien/openship/blob/main/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`](https://github.com/oblien/openship/blob/main/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`](https://github.com/oblien/openship/blob/main/README.md), test files, and configuration templates rather than a dedicated `/examples` directory.
- **CLI examples** in [`README.md`](https://github.com/oblien/openship/blob/main/README.md) (lines 78-84) provide the fastest path from installation to deployment.
- **Docker-Compose samples** in [`docker/docker-compose.yml`](https://github.com/oblien/openship/blob/main/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`](https://github.com/oblien/openship/blob/main/packages/core/src/openship-config/parse.test.ts) define the exact schema for [`openship.json`](https://github.com/oblien/openship/blob/main/openship.json) files.
- **Proxy routing examples** in [`packages/adapters/test/vercel-routing.test.ts`](https://github.com/oblien/openship/blob/main/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`](https://github.com/oblien/openship/blob/main/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`](https://github.com/oblien/openship/blob/main/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`](https://github.com/oblien/openship/blob/main/packages/core/src/openship-config/parse.test.ts) and [`packages/adapters/test/vercel-routing.test.ts`](https://github.com/oblien/openship/blob/main/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`](https://github.com/oblien/openship/blob/main/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`](https://github.com/oblien/openship/blob/main/packages/adapters/src/system/proxy/import/proxy-import.test.ts) demonstrates Caddyfile parsing. These samples enable zero-downtime migration from existing reverse-proxy setups.