Traefik Routing & Domains

Workspace URLs section — The workspace detail page showing the URLs section, with a subdomain, domain, target container port, and TLS toggle for a running workspace.

Trailer publishes the HTTP services running inside a workspace container through Traefik, an HTTP reverse proxy. Each workspace URL maps a public host name to a port inside the container. Traefik terminates the incoming request and forwards it to that port.

How a URL maps to a container port

A workspace URL has four parts that matter for routing:

Subdomain and Domain: together they form the host name Traefik matches on, for example app.example.com. The host is always subdomain.domain.
Port: the port the service listens on inside the container. This is the Traefik load balancer target port, not a published host port.
TLS enabled: whether the public URL is served over https.

When a request arrives for subdomain.domain, Traefik matches a router rule on that host and forwards the request to the container on the configured port. No host port binding is required for a URL to work. Traefik reaches the container over a Docker network, not over the host’s published ports.

Domains

A URL can only use a domain that is already registered on the workspace’s host. Domains are managed per host (see the Domains page). Each domain belongs to exactly one host, and domain host names are immutable once created.

When a workspace is created or updated, the server validates every URL against the registered domains:

The referenced domain must exist on the host.
The requesting user must have view access to that domain.
The full host (subdomain.domain) must not already be in use by another workspace.

Reverse proxy modes

Traefik integration is configured per host. The reverse proxy type controls how the agent tells Traefik about each workspace. There are three modes:

Type	Value	How routing is published
None	`none`	No Traefik routing.
Docker labels	`traefikDockerProvider`	The agent adds Traefik labels to the workspace container; Traefik’s Docker provider watches them.
Config files	`traefikFileProvider`	The agent writes a TOML config file per workspace; Traefik’s file provider watches the directory.

The host’s reverse proxy config also carries the entry point (the Traefik entry point routers attach to) and an optional cert resolver (the name of a Traefik ACME certificate resolver). Both are set on the host details page.

Docker labels mode

In traefikDockerProvider mode the agent attaches labels to the workspace container itself. When the workspace has at least one URL, the agent sets:

traefik.enable=true
traefik.docker.network pointing at the per-workspace reverse-proxy network.

Then, per URL, it emits the router, service, and (if configured) middleware labels, including:

traefik.http.routers.<name>.rule, a Host(...) match on subdomain.domain
traefik.http.routers.<name>.entrypoints, set to the host entry point
traefik.http.services.<name>.loadbalancer.server.port, set to the container port
traefik.http.routers.<name>.tls.certresolver, set when a cert resolver is configured on the host.

Config files mode

In traefikFileProvider mode the agent writes one TOML file per workspace into the configured config directory (named trailer-<workspaceID>.toml). The file declares the routers, services, and middlewares for that workspace’s URLs. The service load balancer points at scheme://<workspaceID>:<port>, where <workspaceID> resolves to the container over the shared reverse-proxy network. If a workspace ends up with no Traefik-routed URLs, its config file is removed.

Networking between Traefik and the container

So Traefik can reach the workspace without exposing host ports, the agent attaches both Traefik and the workspace to a dedicated per-workspace reverse-proxy network. The container is reachable on that network by its workspace ID, which is what the router service target uses as the host name.

Authentication middlewares

A URL can be protected. The agent renders a Traefik middleware based on the URL’s authentication type:

Basic authentication: a basicAuth middleware with the username and a bcrypt hash. The plaintext password is hashed server-side and never stored.
Internal authentication: a forwardAuth middleware pointed at the Trailer server’s auth endpoint, which returns the authenticated user in the X-Forwarded-User header.

URLs served through the agent instead of Traefik

Not every workspace URL goes through Traefik. If a URL’s host falls under the Trailer server’s own host, it is served by the agent proxy instead: the server relays the request to the agent, which forwards it into the container. Those URLs are skipped when the agent generates Traefik labels or config files. See Workspace URLs and routing for how the two modes compare and how the choice is made.

TLS

TLS is driven by Traefik, not by Trailer directly. A URL marked TLS-enabled is served over https, and routers attach the host’s configured cert resolver so Traefik can obtain a certificate. Certificate issuance (for example ACME / Let’s Encrypt) is configured in the Traefik instance’s own static configuration.

Managed Traefik container

A host can optionally let Trailer deploy and manage the Traefik container itself. When this is enabled the agent runs a Traefik container, binds the Docker socket so the Docker provider can watch labels, mounts a volume for the file-provider config directory, and mounts a volume for ACME certificate storage. The container image, name, published ports, and static configuration are all set on the host details page. The static config is supplied as TOML.

If managed deployment is left off, you are expected to run and configure Traefik yourself; Trailer still emits labels or config files for it to consume.