# Openship TraefikProvider Self-Hosted Routing and SSL: Complete Import Guide

> Effortlessly migrate self-hosted workloads with Openship TraefikProvider. Import container routing and SSL from Traefik labels automatically. No manual reconfiguration needed.

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

---

**Openship automatically imports Docker container routing configurations from Traefik labels, resolves upstream targets, and extracts existing TLS certificates to migrate self-hosted workloads without manual reconfiguration.**

This guide explains how Openship parses Traefik's label-based routing system to generate **ImportedSites** for OpenShip-Edge, enabling seamless migration of self-hosted containerized applications while preserving SSL termination settings.

## How Openship Imports Traefik Routes

The import process runs entirely through Docker CLI commands, parsing container labels without requiring access to Traefik's static configuration files. The parser resides in [`packages/adapters/src/system/proxy/import/traefik.ts`](https://github.com/oblien/openship/blob/main/packages/adapters/src/system/proxy/import/traefik.ts) and implements an eight-stage pipeline to reconstruct routable sites from Docker metadata.

### Gathering Container Metadata

The `scanTraefik` function executes Docker inspection commands to collect raw container data. It retrieves container names, network IP mappings, exposed ports, command-line arguments, and all Docker labels from running containers.

```typescript
import { scanTraefik } from "packages/adapters/src/system/proxy/import/traefik";

async function importTraefikRoutes() {
  const result = await scanTraefik(execCommand);
  console.log("Imported sites:", result.sites);
  console.log("Warnings:", result.warnings);
}

```

This function returns an array of `TraefikContainer` objects that feed into the pure parser.

### Parsing Label Definitions

The `collectDefinitions` helper walks every container's labels (normalized to lowercase via `lowerKeys`) to extract global settings. It identifies service definitions specifying `loadbalancer.server.port` and `loadbalancer.server.scheme`, redirect middleware names, TCP/UDP router declarations, and static configuration flags like `--providers.file` or `--providers.docker.exposedbydefault`.

### Extracting Router Hosts and TLS Settings

For each `traefik.http.routers.<name>` label set, the parser extracts routing criteria using `extractHosts` to parse **Host()** matchers. It captures the target service name, TLS enablement flags, middleware chains, and additional matchers (PathPrefix, Headers, etc.). The `resolveIp` function determines which container IP Traefik would dial for the upstream connection.

### Building Import Candidates

Each router becomes a `Candidate` object containing:
- Resolved hostnames
- SSL/TLS flag status
- Target URL constructed as `scheme://ip:port`
- Source container name
- Middleware list
- Redirect-only flag (indicating if all middlewares perform HTTP→HTTPS redirects)

### Collapsing Host Collisions

Because OpenShip-Edge creates a single virtual host per hostname, the `collapseByHost` function (located in [`packages/adapters/src/system/proxy/import/parse-utils.ts`](https://github.com/oblien/openship/blob/main/packages/adapters/src/system/proxy/import/parse-utils.ts)) handles the common Traefik pattern of dual routers. When both a `web` (HTTP) and `websecure` (HTTPS) router target the same host, the parser retains only the TLS-enabled variant, discarding the HTTP redirect router since OpenShip-Edge handles redirects automatically.

### Certificate Extraction from ACME Storage

When a site has TLS enabled, Openship can retrieve the actual certificate from Traefik's ACME store. The `traefikAcmeCert` helper in [`packages/adapters/src/system/proxy/import/traefik-certs.ts`](https://github.com/oblien/openship/blob/main/packages/adapters/src/system/proxy/import/traefik-certs.ts) reads the container's [`acme.json`](https://github.com/oblien/openship/blob/main/acme.json) file, locates the certificate entry for the specific hostname (matching case-insensitively), and decodes the PEM certificate and key pair.

```typescript
import { traefikAcmeCert } from "packages/adapters/src/system/proxy/import/traefik-certs";

async function getCert(host: string) {
  const cert = await traefikAcmeCert(execCommand, host, "traefik");
  if (cert) {
    console.log(`Cert for ${host} from ${cert.source}`);
    console.log(cert.certPem);
    console.log(cert.keyPem);
  }
}

```

### Warning Generation

The import process generates human-readable warnings for configurations requiring manual review. These include routers using non-Host matchers (PathPrefix, Headers, HostRegexp), unused middleware definitions, guessed ports, and TCP/UDP stream routers that OpenShip-Edge does not support.

## Key Implementation Details

Understanding how Openship interprets Traefik labels ensures successful migration of complex routing rules.

### Case-Insensitive Label Parsing

Traefik lower-cases all label keys before processing. Openship's parser mirrors this behavior through the `lowerKeys` normalization, ensuring `loadBalancer.server.port` and `loadbalancer.server.port` resolve identically.

### Label-Driven Architecture

Openship does not require Traefik's static configuration file or API access. It relies exclusively on Docker container labels, making it compatible with any standard Traefik deployment using Docker provider discovery.

### Network Resolution Strategy

The `resolveIp` function examines the container's network settings to determine the IP address Traefik would use for upstream communication. This ensures that Openship routes traffic to the correct internal Docker network address rather than published ports.

## Integrating with OpenShip-Edge

After parsing, the `ProxyScanResult` containing normalized `ImportedSite` objects integrates directly into the edge router.

```typescript
import { importProxySites } from "packages/edge/importer";

async function migrate() {
  const { sites } = await scanTraefik(execCommand);
  await importProxySites(sites); // Registers sites in the edge router
}

```

The result includes the proxy kind (`"traefik"`), the array of sites with hostnames and SSL flags, and the collection of migration warnings.

## Core Source Files

The Traefik import functionality spans these locations in the oblien/openship repository:

- **[`packages/adapters/src/system/proxy/import/traefik.ts`](https://github.com/oblien/openship/blob/main/packages/adapters/src/system/proxy/import/traefik.ts)** – Core parser (`parseTraefikLabels`) and Docker inspection wrapper (`scanTraefik`)
- **[`packages/adapters/src/system/proxy/import/traefik-certs.ts`](https://github.com/oblien/openship/blob/main/packages/adapters/src/system/proxy/import/traefik-certs.ts)** – ACME storage parsing and PEM extraction (`traefikAcmeCert`)
- **[`packages/adapters/src/system/proxy/import/parse-utils.ts`](https://github.com/oblien/openship/blob/main/packages/adapters/src/system/proxy/import/parse-utils.ts)** – Shared utilities including `collapseByHost` and comment stripping
- **[`packages/adapters/src/system/proxy/index.ts`](https://github.com/oblien/openship/blob/main/packages/adapters/src/system/proxy/index.ts)** – Public entry point delegating to proxy scanners
- **[`packages/adapters/src/system/types.ts`](https://github.com/oblien/openship/blob/main/packages/adapters/src/system/types.ts)** – TypeScript definitions for `ProxyKind` and related interfaces

## Summary

- **Openship parses Traefik Docker labels** to automatically import routing configurations without requiring Traefik's static config files.
- **The eight-stage pipeline** resolves container IPs, extracts Host() matchers, handles TLS flags, and collapses duplicate host entries.
- **ACME certificate migration** reads [`acme.json`](https://github.com/oblien/openship/blob/main/acme.json) directly from Traefik containers to preserve existing SSL certificates.
- **Case-insensitive parsing** ensures compatibility with Traefik's label normalization.
- **Warning generation** identifies unsupported features like TCP/UDP routers and complex matchers requiring manual intervention.

## Frequently Asked Questions

### How does Openship handle the HTTP to HTTPS redirect pattern common in Traefik?

Openship detects when two routers share the same hostname—typically a `web` router with redirect middleware and a `websecure` router with TLS enabled. The `collapseByHost` function automatically drops the HTTP redirect router and retains only the TLS variant, as OpenShip-Edge handles HTTPS redirection internally.

### Can Openship import certificates from Traefik's Let's Encrypt ACME storage?

Yes. The `traefikAcmeCert` function locates Traefik's [`acme.json`](https://github.com/oblien/openship/blob/main/acme.json) file (either from explicit container paths or default locations), parses the JSON structure case-insensitively, and extracts the certificate and private key PEM blocks for each hostname. This allows zero-downtime migration of existing SSL certificates.

### What happens to Traefik routers using PathPrefix or Header matchers?

Routers utilizing matchers beyond simple `Host()` rules—such as `PathPrefix()`, `Headers()`, or `HostRegexp()`—generate warnings during import. OpenShip-Edge creates virtual hosts based on hostnames only, so these complex routing rules require manual configuration after the basic site import completes.

### Does the import process require stopping the Traefik container?

No. The `scanTraefik` function uses read-only Docker CLI commands (`docker ps` and `docker inspect`) to gather container metadata and labels. The process is non-invasive and does not modify or interrupt running Traefik instances during the discovery phase.