Ordyn

Appearance

Traefik ​

Traefik is the reverse proxy used by the provided Ordyn compose deployments.

It receives public HTTP and HTTPS traffic, provides TLS certificates, and routes requests to the Ordyn API, frontend, Edge, cache, and webhook containers through Docker labels.

What Traefik Does ​

The provided Traefik deployment:

  • listens on ports 80 and 443
  • redirects HTTP traffic to HTTPS
  • supports Let's Encrypt HTTP-01, Let's Encrypt DNS-01, and user-provided certificates
  • watches Docker labels for Ordyn services
  • creates the shared frontend Docker network used by public Ordyn services

Requirements ​

Before installing Traefik, prepare:

  • a Debian host with Docker Engine and Docker Compose
  • DNS names for the services that Traefik should expose
  • inbound access to port 443
  • inbound access to port 80 when using public Let's Encrypt HTTP-01 validation
  • an email address for Let's Encrypt certificate notices when Traefik should request certificates

Choose one certificate mode before starting Traefik.

Installation ​

Checkout the Traefik deployment folder from the Ordyn compose repository:

bash
if [ ! -d /opt/ordyn-compose/.git ]; then
  git clone --filter=blob:none --sparse https://github.com/ordyn-project/compose.git /opt/ordyn-compose
fi
cd /opt/ordyn-compose
git sparse-checkout add traefik

Create the Traefik environment file:

bash
cd /opt/ordyn-compose/traefik
cp .env.example .env

Set the email address used for Let's Encrypt certificate notices when using Let's Encrypt:

dotenv
TRAEFIK_ACME_EMAIL=admin@example.com

Certificate Mode 1: Let's Encrypt Webroot / HTTP-01 For Public Hosts ​

Use this mode when the Traefik host is publicly reachable on ports 80 and 443.

This is the default configuration in compose.yml. Traefik answers the public HTTP validation request and stores issued certificates in the letsencrypt Docker volume. No separate Certbot webroot directory is required for the provided Traefik setup.

Start Traefik from the Traefik deployment folder:

bash
docker compose pull
docker compose up -d

Use this mode for ordinary public installations where DNS records point directly to the Traefik host and inbound port 80 is allowed.

Certificate Mode 2: Let's Encrypt DNS-01 ​

Use DNS-01 when the service hostnames should receive Let's Encrypt certificates but the Traefik host is not publicly reachable on port 80.

The provided DNS-01 compose file is prepared for Route53. Add the DNS credentials to .env:

dotenv
TRAEFIK_ACME_EMAIL=admin@example.com
TRAEFIK_DNS_PROVIDER=route53
AWS_ACCESS_KEY_ID=<route53-access-key>
AWS_SECRET_ACCESS_KEY=<route53-secret-key>
AWS_REGION=eu-central-1
AWS_HOSTED_ZONE_ID=<optional-hosted-zone-id>

The AWS credentials need permission to create and remove _acme-challenge TXT records for the hosted zone.

Start Traefik with the DNS-01 compose file:

bash
docker compose -f compose.yml -f compose.dns-01.yml pull
docker compose -f compose.yml -f compose.dns-01.yml up -d

Traefik still receives normal HTTPS traffic on port 443. Port 80 can remain open for HTTP-to-HTTPS redirects, but DNS-01 certificate issuance does not require public access to port 80.

Certificate Mode 3: User-Provided Certificate ​

Use this mode when certificates are issued outside of Traefik, for example by an internal certificate authority, a corporate certificate process, or another ACME client.

Place the certificate and private key in the Traefik deployment folder:

text
/opt/ordyn-compose/traefik/certificates/fullchain.pem
/opt/ordyn-compose/traefik/certificates/privkey.pem

The certificate must cover every hostname routed through this Traefik instance, such as the Ordyn frontend, API, Edge, cache, and webhook hostnames.

Start Traefik with the external-certificate compose file:

bash
docker compose -f compose.yml -f compose.external-certificate.yml pull
docker compose -f compose.yml -f compose.external-certificate.yml up -d

To use a different filename or multiple certificates, edit dynamic/certificates.yml in the Traefik deployment folder and add the certificate entries there.

Using With Ordyn Services ​

Install Traefik before starting services that expose public HTTP routes through Traefik:

  • Ordyn API
  • Ordyn frontend
  • Edge
  • Cache nodes
  • Net
  • Webhooks

Service-specific hostnames are configured in each service folder's .env file:

dotenv
# api/.env
ORDYN_API_HOST=api.ordyn.example.com

# frontend/.env
ORDYN_FRONTEND_HOST=ordyn.example.com

# edge/.env
SERVICE_DOMAIN=ordyn-edge.example.com

# cache/.env
SERVICE_DOMAIN=ordyn-cache.example.com

# net/.env
SERVICE_DOMAIN=ordyn-net.example.com

# webhooks/.env
SERVICE_DOMAIN=ordyn-webhooks.example.com

Services that only connect outbound through Edge do not need a Traefik route. This includes Package Discovery, SNMP, and Telematik.

Troubleshooting ​

If certificates are not issued:

  • confirm DNS records point to the Docker host
  • for HTTP-01, confirm ports 80 and 443 are reachable from the internet
  • for DNS-01, confirm the DNS credentials can create _acme-challenge TXT records
  • confirm TRAEFIK_ACME_EMAIL is set for Let's Encrypt modes
  • check the Traefik container logs

If a user-provided certificate is not served:

  • confirm certificates/fullchain.pem and certificates/privkey.pem exist in the Traefik deployment folder
  • confirm the certificate includes the hostname being opened
  • confirm Traefik was started with compose.external-certificate.yml

If a service is not reachable:

  • confirm the service container is running
  • confirm the DNS record points to the Docker host
  • confirm the service hostname is set correctly in that service's .env file
  • check the Traefik logs and the service logs

For Net, also confirm ORDYN_NET_HTTP_BIND is set to 172.17.0.1:8080 so Traefik can reach the Net HTTP listener on the Docker host bridge address.