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

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

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, 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【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:

// 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【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:

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:

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:

// 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 – Documents the self-hosted system layer, Traefik requirements, and the four-phase setup flow.
• 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 – Contains installTraefik() and checkTraefik() helper functions used during the setup wizard.
• 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, 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 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 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.

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