Tetherd

Tetherd is the lightweight agent that runs on your worker servers. It watches your Docker containers and tells the central Tether server where they are so Traefik can find them.

How it Works

1. You run Tetherd on every server where you have Docker containers.
2. Tetherd looks at your containers' labels (like traefik.http.routers.myapp.rule).
3. It automatically detects the server's IP address.
4. It sends this information to your central Tether server.

This allows a single Traefik instance on a different machine to route traffic to these containers seamlessly.

Quick Start

Run Tetherd on your worker server:

services:
  tetherd:
    image: ghcr.io/mizuchilabs/tetherd:latest
    network_mode: host # Highly recommended for IP detection
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    environment:
      - TETHERD_SERVER=http://<TETHER_SERVER_IP>:3000
      - TETHERD_TOKEN=your-secret-password
    restart: unless-stopped

Deploying an App

When you deploy an app on this worker server, just add standard Traefik labels. Tetherd handles the rest:

services:
  my-app:
    image: nginx
    ports:
      - "8080:80"
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.my-app.rule=Host(`my-app.com`)"

Tetherd will tell the central server: "Send traffic for my-app.com to http://<THIS_SERVER_IP>:8080".

Configuration

Env Var	Flag	Default	Description
TETHERD_SERVER	--server	http://127.0.0.1:3000	URL of the central Tether server.
TETHERD_TOKEN	--token		Required: Token matching the Tether server.
TETHERD_HOST_IP	--host-ip	(auto)	Manual override for this server's IP.
TETHERD_ENVIRONMENT	--env	default	Group servers into isolated environments.
TETHERD_NAME	--name	(hostname)	Unique agent name shown in Tether.
TETHERD_INSECURE	--insecure	false	Skip TLS verification when connecting to Tether.
TETHERD_DEBUG	--debug	false	Enable detailed logging.

Healthcheck

The image has no shell, so use the built-in health command. It exits 0 while the agent is connected to Tether.

healthcheck:
  test: ["CMD", "tetherd", "health"]
  interval: 30s
  timeout: 5s
  start_period: 10s

The agent keeps a heartbeat file in /tmp. With read_only: true, add tmpfs: [/tmp].

Notes

• Containers with a healthcheck only get routes once they are healthy, same as Traefik's Docker provider.
• References to other providers like api@internal or auth@file are passed through untouched.
• name@docker middleware references are rewritten to name when the middleware is defined by labels on this host, because Tether serves it through Traefik's HTTP provider. Middlewares that only exist in the gateway's own Docker provider keep the @docker suffix.
• Any middleware defined in Tether's local file or by another agent in the same environment can be used by its plain name, e.g. traefik.http.routers.my-app.middlewares=auth.

---

Requirement: You need a Tether server running to collect these updates.

License

Apache 2.0 License - see LICENSE for details