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

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

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) 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 reads the container's acme.json file, locates the certificate entry for the specific hostname (matching case-insensitively), and decodes the PEM certificate and key pair.

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.

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 – Core parser (parseTraefikLabels) and Docker inspection wrapper (scanTraefik)
• 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 – Shared utilities including collapseByHost and comment stripping
• packages/adapters/src/system/proxy/index.ts – Public entry point delegating to proxy scanners
• 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 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 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.

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