Hosting behind another proxy
Run Yard hosting on a machine where another proxy already holds ports 80 and 443, check it with the hosting doctor, and find the setup page for your proxy.
Some machines already run a reverse proxy (nginx, Caddy, Traefik, Coolify). It holds ports 80 and 443, so the proxy Yard starts for hosting cannot have them. Yard then runs behind the other proxy: that proxy keeps the ports and the certificates and sends your domain on to the runner.
This page holds the concepts. The steps for your proxy are on its own page:
| Your setup | Page |
|---|---|
Coolify (coolify-proxy) |
Run a runner on Coolify |
| nginx | Behind nginx |
| Caddy | Behind Caddy |
| Traefik, not from Coolify | Behind Traefik |
| By hand or systemd, no container | Behind a proxy, by hand |
Ask the hosting doctor
If something does not work, start with the doctor. It answers "why, and what do I change":
- the deployment mode it found (runner on the host, in a container, Coolify, another proxy on the host, or nothing else on 80/443), with the holder named;
- a checklist, each line ok, warn, fail or skipped with a one-line reason;
- a proposed change as a diff.
Run it in the Hosting settings (Hosting doctor) or on the machine:
yard hosting doctor (--json for the report as data).
It is read-only. It reads ports, containers and files, and asks the proxy
container to fetch the runner's own address. It writes nothing, saves nothing
and restarts nothing. A change is made only when you click Apply (or run
yard hosting doctor --apply) on the proposal it showed, and the route is
tested again after. If the situation changed since the report, Apply is
refused and you run the check again. Checks it cannot make (no Docker socket,
no permission to read the firewall) are listed as skipped with the reason.
It never changes firewall rules, networks or the proxy's own configuration.
Modes
| Mode | What it means | Typical fix |
|---|---|---|
| Runner on the host, directly | Started by hand or by systemd. | Listen on 127.0.0.1:8443; a proxy on the host reaches it there. |
| Runner in a container | Plain docker run or compose. |
The proxy shares a network with it, or reaches the published port. |
| Coolify | coolify-proxy holds 80/443. |
The proxy is in a container: use its network's gateway. |
| Proxy on the host | nginx, Caddy or Traefik as a host process. | Loopback is enough. |
| Standalone | Nothing else on 80/443. | Not behind a proxy; Yard's own proxy takes the ports. |
The listen address
A proxy on the host reaches 127.0.0.1:8443. A proxy in a container cannot:
127.0.0.1 there is the container. It needs an address of the host that its
network can reach, and that is the gateway of a network the proxy is on.
It differs from machine to machine (172.17.0.1 on the default bridge, another
one on Coolify's coolify network), so there is no default: the doctor reads
the proxy container's networks and proposes the right one.
What happens by itself
When you turn hosting on and nobody chose a listen address, the runner checks
who holds the port it wants (443, and 80 with HTTP-01). It looks at Docker
(docker ps) first and then at the host (ss). If another container or
process holds it, the runner:
- listens on the first free port from
127.0.0.1:8443, never on0.0.0.0, and writes the choice down in its data directory, so the address is the same after every restart (see Several runners on one server); - turns TLS off on its side and binds no port 80, so there is no HTTP-01;
- refuses any
Hostoutside your verified domains before it routes; - says so in the Hosting settings: Found coolify-proxy on the port, so this runner went behind it.
A listen address or TLS mode that you chose (in Yard, in
RUNNER_HOSTING_LISTEN, or on the machine) is kept as it is. Detection never
picks 0.0.0.0 on its own.
If the port was taken and you set the address yourself, the settings name the
owner (Port 443 is held by coolify-proxy) and offer Run behind another
proxy: one click sets the address the runner suggests (never 0.0.0.0)
and TLS off.
Several runners on one server
Each runner behind the proxy needs its own listen port, and the route in your proxy points at exactly that port.
- How the port is chosen. With no listen address set, a runner takes the
first free port from
127.0.0.1:8443(the second runner gets 8444, and so on) and stores it in its data directory (behind-listen.json). Keep that directory on a persistent volume. - It does not move. At a later start the runner keeps its port. If another process holds it now, hosting stops with an error that names the holder and the next free port. It does not pick another one by itself, because your proxy's file would then point at the wrong port. The Hosting settings offer the suggested address with one click (Use 127.0.0.1:8444); save, then copy the updated file.
- A saved address that is taken gets the same error and suggestion.
- One file per runner. The generated file is named after the runner:
yard-<runner>.yaml(Coolify:/data/coolify/proxy/dynamic/), oryard-<runner>.conffor nginx. Two runners never overwrite each other's routes. - One wildcard domain, one runner.
*.apps.example.comgoes to exactly one runner. A second runner needs its own domain or subdomain zone, such as*.b.apps.example.com, with its own wildcard certificate. - Stale file. When the listen port changes, the settings show a banner that the file in your proxy is stale, with the updated YAML to copy.
Keep the address on loopback or a firewalled interface. The settings never
suggest 0.0.0.0.
Put the config into the other proxy
With TLS: Behind another proxy, the Hosting settings show a ready config
for each verified domain (Traefik, nginx, Caddy tabs, nothing secret in it).
It sends *.apps.example.com and apps.example.com to the runner's listen
address at the lowest priority and passes the Host header on.
Behind an existing proxy
Where the runner listens depends on what holds port 443 on the machine. The runner detects it and proposes the address; the "Run behind it" button in the runner's Hosting settings applies it.
| What holds 443 | Runner listens on | Why |
|---|---|---|
| A container (Coolify's Traefik, a Caddy or nginx container) | <bridge gateway>:8443, for example 172.17.0.1:8443 |
The proxy container reaches the host through the Docker bridge gateway, not through its own loopback. Falls back to 127.0.0.1:8443 when no gateway is found. |
| A process on the host (nginx, Caddy as a service) | 127.0.0.1:8443 |
The proxy and the runner share the host's loopback. |
| Nothing | 0.0.0.0:443 |
No other proxy: the runner serves visitors itself. |
Which 502 is it?
- Cloudflare's own 502 page (a Cloudflare-branded error): Cloudflare could not reach your origin, which is the other proxy. Check that it is running and that its router for the host exists.
- Plain text from Yard, with one of these messages, means the other proxy
did reach the runner:
- The app did not answer. / The app refused the connection.: the app's container is stopped or not listening on its port.
- This app's runner is not connected right now. / …not reachable right now.: the edge (tunnel mode) has no live connection to the runner.
Check the hop from the proxy
From inside the other proxy's container, send a request to the listen address with the app's host:
docker exec <proxy-container> curl -sS -H 'Host: app.example.com' http://172.17.0.1:8443/
A response from the app, or Yard's own sign-in redirect, means the runner is reachable. A connection error means the address is wrong or a firewall blocks the bridge subnet (Security).
Several apps on one port
Two apps that both listen on 5173 do not conflict. Each app runs in its own
container and the runner routes by Host(), so
one.example.com and two.example.com each reach their own app.
After you open an app from Yard, the runner redirects to the app's own
https:// address, whatever address the other proxy used to reach the runner.
Wildcard certificates need DNS-01
Every app gets its own name under the domain. One certificate for
*.apps.example.com covers them all, and Let's Encrypt only issues a
wildcard through the DNS-01 challenge, so the proxy in front needs DNS-01
for your DNS provider (see your proxy's page). DNS records stay as on the
Runner page: the _yard-verify TXT record, and
apps.example.com and *.apps.example.com pointing at the server.
Test route
When the runner's TLS mode is HTTP-01, the settings remind you of this.
HTTP-01 also needs port 80, which the other proxy holds, so it cannot be the
runner's own mode here.
Yard's own dns01 mode (Cloudflare) is unchanged: it is for a runner that
holds the ports itself.
DNS records stay as on the Runner page: the _yard-verify TXT
record, and apps.example.com and *.apps.example.com pointing at the
server.
Check it
The Hosting doctor (see Ask the hosting doctor) is the first thing to run: it is read-only and names the cause and the fix.
Test route, in the Hosting settings, makes a request to a sample host
(doctor-xxxxxx.apps.example.com) the way a visitor would, and says what is
missing. On the machine, yard runner hosting doctor does the same and adds
the upstream test: it asks the other proxy's container to open the runner's
address.
| What it says | What it means | What to do |
|---|---|---|
*.apps.example.com does not resolve |
DNS has no wildcard record. | Create it, pointing at the server. |
Nothing answered on https |
Port 443 is closed, or the record points elsewhere. | Open 443 to the proxy; check the record. |
certificate that does not cover *.apps.example.com |
No wildcard certificate. | Issue it with DNS-01. |
no router … |
The proxy has no route for the host. | Load the route file; check the entrypoint name. |
could not reach the runner (HTTP 502/503/504) |
The route matched, but the proxy cannot reach the listen address. | Run the hosting doctor: it names the proxy's network and the address to use. |
answered … but not as this runner |
Another route or site takes the name. | Give Yard's route a rule that matches, or remove the other. |
"No available server"
Traefik answers no available server (or 404 page not found) when no
router matched the host. The runner never saw the request. Check, in this
order:
- The file is loaded: it is in Traefik's dynamic directory (Coolify: Proxy → Dynamic Configurations), and the proxy's log shows no error for it. Choose Restart Proxy if Traefik did not pick it up.
- The router's
entryPointsnames an entrypoint that exists (httpson Coolify). - The rule matches the host you opened: the domain is the verified one.
- No router with a higher priority claims the name. Yard's router has priority 1 on purpose.
Test route and yard runner hosting doctor run these checks for a sample
host. The provider-specific steps for Coolify are on Run a runner on
Coolify.
Names
Browsers warn about "lookalike" addresses, and api-useyard-app.apps.example.com
reads like the domain useyard.app. Hosted names never end in a TLD-like
word:
- a name with a dot (
useyard.app) loses its dots and TLD tail, and gets a short stable id (useyard-3k9x2p), souseyard.appanduseyard.iostay apart; - a name that is already dashed (
useyard-app) loses a trailingapp,io,com,dev… and gets the same id; - every other name keeps its label.
The workspace and project name fields warn when a name looks like a domain.
Chrome's Did you mean …? warning appears because app hostnames are
<app>-<workspace>.<domain>. A workspace named like a domain, such as
useyard.app, gives api-useyard-app, which reads like it. To avoid it,
rename the workspace slug or the app so it carries no domain-like ending.
An app that already runs under a lookalike address keeps it: changing it would silently break the old link. The Apps page marks such an app and offers Rename. The new address is shown first, and the app restarts under it; the old address stops working.
Security
- The runner listens on
127.0.0.1by default, and only loopback or private addresses are accepted for the generated config. The doctor warns when the upstream is0.0.0.0or a public address. - The runner's proxy accepts only hosts under your verified domains in this
mode; any other
Hostgets a 404 from the proxy before any routing. - The config contains no token and no secret. Yard never writes one into it.
- Traefik's file provider is trusted: whoever can write a file in the dynamic directory can route any host to any service. Keep that directory writable by root only.
- Firewall. Only the other proxy should reach the upstream port. When the
runner listens on a gateway address, allow that network's subnet and deny
the rest (
ufw deny 8443, thenufw allow from <subnet> to any port 8443). Docker bypassesufwfor published ports: put the rule in theDOCKER-USERchain. A listener on127.0.0.1needs no rule. The doctor only reads these rules; it never changes them.