# How OpenShip's Traefik Integration Handles Routing and SSL Certificates in Self‑Hosted Mode

> Discover how OpenShip's Traefik integration in self-hosted mode manages routing and SSL certificates. Learn about its four-phase setup wizard for file-based and Docker deployments.

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

---

**TLDR:** OpenShip treats Traefik as a mandatory infrastructure component that supplies both HTTP routing and automatic SSL termination via Let’s Encrypt, configuring it through a four-phase setup wizard that supports both file-based and Docker-based deployment modes while using strict feature gates to ensure safe operations.

In self-hosted deployments of the `oblien/openship` platform, Traefik integration handles routing and SSL certificates by acting as the mandatory edge proxy responsible for all traffic management and encryption. The system abstracts infrastructure complexity through a unified executor pattern, allowing identical configuration logic to function whether Traefik runs on the local machine or a remote server accessed via SSH.

## The Four-Phase Setup Flow

The `SystemManager.setup` method orchestrates Traefik provisioning through four discrete phases defined in [`packages/adapters/docs/SYSTEM.md`](https://github.com/oblien/openship/blob/main/packages/adapters/docs/SYSTEM.md). This wizard collects three critical inputs during initialization: the **primary domain** (public hostname for Traefik exposure)【SYSTEM.md L48‑L50】, the **ACME e‑mail** (for Let’s Encrypt registration)【SYSTEM.md L27‑L28】, and the **Traefik mode** (either `file` for static YAML configurations or `docker` for containerized deployment)【SYSTEM.md L29】.

### CHECK Phase: Verifying Traefik Availability

The setup begins by invoking `checkTraefik(executor)`, which executes `traefik version` and inspects the systemd service status to verify an existing installation【SYSTEM.md L38】. If Traefik is detected and healthy, the flow proceeds; otherwise, the system transitions to the installation phase.

### INSTALL Phase: Automated Provisioning

When Traefik is missing, `installTraefik(executor, onLog)` automatically installs the binary via the OS package manager and seeds the required configuration files【SYSTEM.md L42】. The executor abstraction streams real-time logs back to the dashboard while writing the necessary YAML files or Docker Compose snippets to the target system.

### VALIDATE and CACHE Phases

After installation, the system re-runs validation checks to confirm a healthy Traefik state. Finally, the **CACHE** phase persists the system state via [`packages/adapters/src/system/state.ts`](https://github.com/oblien/openship/blob/main/packages/adapters/src/system/state.ts), ensuring that subsequent requests skip redundant installation checks.

## Routing Implementation: File vs Docker Mode

OpenShip supports two operational modes for Traefik routing, each managed through the executor abstraction in [`packages/adapters/src/system/traefikProvider.ts`](https://github.com/oblien/openship/blob/main/packages/adapters/src/system/traefikProvider.ts).

**File Mode** configures Traefik to watch a designated configuration directory for static YAML files. The executor writes router and service definitions to paths like [`/etc/traefik/dynamic.yml`](https://github.com/oblien/openship/blob/main//etc/traefik/dynamic.yml), enabling Traefik to automatically create the necessary ingress rules for each deployed application.

**Docker Mode** deploys Traefik as a container and configures it to monitor the Docker API for service labels. This approach requires mounting the Docker socket and writing Compose fragments that define entrypoints and certificate resolvers.

## SSL Certificate Automation with ACME

SSL termination relies on Traefik’s built-in ACME resolver configured with the user-supplied primary domain and ACME e-mail address. During runtime, Traefik obtains Let’s Encrypt certificates on-the-fly and stores them persistently—either in a JSON file for Docker mode or the designated storage path for file mode.

The configuration explicitly sets up the HTTP challenge entrypoint and certificate resolver parameters, as documented in [`packages/adapters/docs/SYSTEM.md`](https://github.com/oblien/openship/blob/main/packages/adapters/docs/SYSTEM.md)【L27‑L28】. Clients receive transparent HTTPS encryption without application-level configuration.

## Safety Through Feature Gating

OpenShip prevents unsafe operations by gating routing and SSL functionality behind explicit feature checks. Before executing network-related tasks, the platform invokes:

```typescript
// Guard routing-related operations
await system.requireFeature('routing');   // throws if Traefik missing

// Guard SSL-related operations
await system.requireFeature('ssl');       // throws if Traefik or ACME not configured

```

These feature definitions in [`packages/adapters/docs/SYSTEM.md`](https://github.com/oblien/openship/blob/main/packages/adapters/docs/SYSTEM.md)【L14‑L16】enforce strict dependencies, ensuring that code attempting to configure routes or certificates cannot execute until the Traefik integration confirms the infrastructure is ready.

## Configuration Examples

### Checking System Capabilities

Before manipulating infrastructure, verify Traefik readiness using the platform API:

```typescript
import { platform } from '@openship/core';

const { system } = platform();

// Ensure Traefik is ready for routing
await system?.requireFeature('routing');

// Ensure SSL (ACME) is ready
await system?.requireFeature('ssl');

```

### Writing File-Provider Configurations

For file mode deployments, write Traefik dynamic configurations directly:

```typescript
import { executor } from '@openship/executor';

// Example snippet written to /etc/traefik/dynamic.yml
const config = `
http:
  routers:
    my-app:
      rule: Host(\`myapp.example.com\`)
      service: my-app
      tls:
        certResolver: letsencrypt
  services:
    my-app:
      loadBalancer:
        servers:
          - url: http://localhost:3000
`;
await executor.writeFile('/etc/traefik/dynamic.yml', config);

```

### Deploying Docker Mode with SSL

Enable automatic certificate issuance in Docker mode by writing a Compose file with ACME environment variables:

```typescript
// Docker‑compose fragment added by the installer
const traefikCompose = `
services:
  traefik:
    image: traefik:v2.10
    command:
      - "--providers.docker"
      - "--entrypoints.websecure.address=:443"
      - "--certificatesresolvers.letsencrypt.acme.email=${process.env.ACME_EMAIL}"
      - "--certificatesresolvers.letsencrypt.acme.storage=/letsencrypt/acme.json"
      - "--certificatesresolvers.letsencrypt.acme.httpChallenge.entryPoint=web"
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - "/var/run/docker.sock:/var/run/docker.sock"
      - "letsencrypt:/letsencrypt"
`;
await executor.writeFile('docker-compose.yml', traefikCompose);

```

## Key Implementation Files

The Traefik integration spans several critical source files in the `oblien/openship` repository:

- **[`packages/adapters/docs/SYSTEM.md`](https://github.com/oblien/openship/blob/main/packages/adapters/docs/SYSTEM.md)** – Documents the self-hosted system layer, Traefik requirements, and the four-phase setup flow.
- **[`packages/adapters/src/system/traefikProvider.ts`](https://github.com/oblien/openship/blob/main/packages/adapters/src/system/traefikProvider.ts)** – Concrete provider implementation that writes Traefik YAML files or Docker definitions via the executor.
- **[`packages/adapters/src/system/installer.ts`](https://github.com/oblien/openship/blob/main/packages/adapters/src/system/installer.ts)** – Contains `installTraefik()` and `checkTraefik()` helper functions used during the setup wizard.
- **[`packages/adapters/src/system/state.ts`](https://github.com/oblien/openship/blob/main/packages/adapters/src/system/state.ts)** – Persists `SetupState` records tracking Traefik installation status and configuration.

## Summary

- OpenShip mandates Traefik for all self-hosted routing and SSL termination.
- The setup wizard runs four phases: **CHECK**, **INSTALL**, **VALIDATE**, and **CACHE**, orchestrated by `SystemManager.setup`.
- **Feature gates** (`requireFeature('routing')` and `requireFeature('ssl')`) prevent operations against unready infrastructure.
- Traefik supports **file mode** (static YAML) and **Docker mode** (containerized with API access) for service discovery.
- **ACME integration** automatically provisions Let’s Encrypt certificates using the user-supplied domain and email address.
- The **executor abstraction** unifies local and remote server management through the same TypeScript interface.

## Frequently Asked Questions

### Is Traefik mandatory for self-hosted OpenShip?

Yes. According to the source code in [`packages/adapters/docs/SYSTEM.md`](https://github.com/oblien/openship/blob/main/packages/adapters/docs/SYSTEM.md), Traefik is treated as a mandatory component for self-hosted deployments. The system explicitly checks for Traefik availability during the CHECK phase and will error if routing or SSL features are requested while Traefik is missing or misconfigured.

### How does OpenShip obtain SSL certificates automatically?

The integration leverages Traefik’s built-in ACME resolver configured with a user-supplied email address and primary domain. During the setup process, the installer seeds configuration that enables Let’s Encrypt’s HTTP challenge mechanism. Traefik then automatically requests, stores, and renews certificates without manual intervention, persisting them in [`/letsencrypt/acme.json`](https://github.com/oblien/openship/blob/main//letsencrypt/acme.json) for Docker mode or the designated file path for file mode.

### What is the difference between file mode and Docker mode?

**File mode** writes static YAML configuration files to a directory that Traefik monitors, suitable for traditional server deployments where Traefik runs as a system service. **Docker mode** deploys Traefik as a container and configures it to discover services via the Docker API, ideal for container-centric environments. Both modes support automatic SSL and routing, but Docker mode requires mounting the Docker socket and uses Compose files rather than static YAML.

### Can I use my own existing Traefik instance?

The setup flow in [`packages/adapters/src/system/installer.ts`](https://github.com/oblien/openship/blob/main/packages/adapters/src/system/installer.ts) includes a CHECK phase that detects existing Traefik installations by running `traefik version` and checking systemd status. If your instance passes these validation checks and is properly configured with the required ACME settings, the system will use it; however, the platform expects full control over the Traefik configuration to ensure consistent routing and SSL behavior.