fix(deploy): health checks probed localhost regardless of the bind address

Docker publishes a container on exactly the address it is given, so an app
with a specific `bind:` is not reachable at localhost — but every health probe
dialled localhost anyway. The probe therefore never connected, retried to the
timeout, and failed the deploy while the container was perfectly healthy.

`ingress: host` deploys by recreate, stopping the old container first, so the
failure was not a no-op: the deploy tears down the new container and nothing
is left running. Setting a bind address turned every subsequent deploy into a
full outage. Found by doing it — dash went down moving from 0.0.0.0 to its
tailnet address, with "timeout after 30s" as the only clue.

The probe now resolves the address from the bind host (0.0.0.0/:: still mean
localhost, as does an empty value, which is caddy/external ingress publishing
on 127.0.0.1). Both the HTTP probe and the TCP fallback were affected.

The same bug sat on the rollback and start/restart paths, where it would have
been worse — a rollback that cannot health-check its target aborts and stops
what it started, so the escape hatch failed exactly when it was needed. Those
read the address back from the running container (docker.HostBindIP) since
they have no config in hand.

Verified live: the failing dash deploy now passes its health check, and dash
answers on the tailnet while the LAN gets nothing.

Author: im-tyler

internal/deploy/deploy.go

@@ -340,7 +340,7 @@ func (d *Deployer) Deploy(ctx context.Context, cfg Config) error {
 	fmt.Fprintln(d.out, "Running health check...")
 	healthCfg := cfg.Health.withDefaults()
 	for i, p := range ports {
-		if err := d.healthCheck(ctx, p, healthCfg); err != nil {
+		if err := d.healthCheck(ctx, p, healthCfg, webBindHost); err != nil {
 			fmt.Fprintf(d.out, "  Health check failed for replica %d (port %d): %v\n", i+1, p, err)
 			return fail(fmt.Errorf("health check failed for replica %d: %w", i+1, err))
 		}

internal/deploy/deploy_test.go

@@ -533,7 +533,7 @@ func TestHealthCheck_Pass(t *testing.T) {
 		Interval: 10 * time.Millisecond,
 	}
 
-	if err := d.healthCheck(context.Background(), 49152, cfg); err != nil {
+	if err := d.healthCheck(context.Background(), 49152, cfg, ""); err != nil {
 		t.Fatalf("healthCheck: %v", err)
 	}
 }
@@ -553,7 +553,7 @@ func TestHealthCheck_TCPFallback(t *testing.T) {
 		Interval: 10 * time.Millisecond,
 	}
 
-	if err := d.healthCheck(context.Background(), 49152, cfg); err != nil {
+	if err := d.healthCheck(context.Background(), 49152, cfg, ""); err != nil {
 		t.Fatalf("healthCheck with TCP fallback: %v", err)
 	}
 }
@@ -573,7 +573,7 @@ func TestHealthCheck_RedirectFallback(t *testing.T) {
 		Interval: 10 * time.Millisecond,
 	}
 
-	if err := d.healthCheck(context.Background(), 49152, cfg); err != nil {
+	if err := d.healthCheck(context.Background(), 49152, cfg, ""); err != nil {
 		t.Fatalf("healthCheck with redirect TCP fallback: %v", err)
 	}
 }
@@ -590,7 +590,7 @@ func TestHealthCheck_Timeout(t *testing.T) {
 		Interval: 10 * time.Millisecond,
 	}
 
-	err := d.healthCheck(context.Background(), 49152, cfg)
+	err := d.healthCheck(context.Background(), 49152, cfg, "")
 	if err == nil {
 		t.Fatal("expected timeout error")
 	}

internal/deploy/health.go

@@ -32,24 +32,45 @@ func (h HealthConfig) withDefaults() HealthConfig {
 	return h
 }
 
+// healthProbeHost is the address the server-side probe dials for a container
+// published on bindHost.
+//
+// Docker publishes on exactly the address it was given, so a container bound to
+// a specific IP is NOT reachable at localhost — probing there gets a connection
+// refused for the life of the timeout. Since `ingress: host` deploys by
+// recreate (the old container is stopped first), that turned every deploy of a
+// specifically-bound app into a full outage: the new container is healthy, the
+// probe cannot see it, the deploy fails, and nothing is left running.
+//
+// An empty bindHost is caddy/external ingress, which publishes on 127.0.0.1.
+func healthProbeHost(bindHost string) string {
+	switch bindHost {
+	case "", "0.0.0.0", "::", "[::]":
+		return "localhost"
+	default:
+		return bindHost
+	}
+}
+
 // healthCheck polls the container until it responds healthy or the timeout expires.
 //
 // Strategy:
-//  1. HTTP GET to localhost:{port}{path} — 200 means healthy.
+//  1. HTTP GET to {host}:{port}{path} — 200 means healthy.
 //  2. If the endpoint returns 404, fall back to a TCP port check.
 //  3. Connection refused means the app hasn't started yet — retry.
-func (d *Deployer) healthCheck(ctx context.Context, port int, cfg HealthConfig) error {
+func (d *Deployer) healthCheck(ctx context.Context, port int, cfg HealthConfig, bindHost string) error {
 	ctx, cancel := context.WithTimeout(ctx, cfg.Timeout)
 	defer cancel()
 
+	host := healthProbeHost(bindHost)
 	for {
-		if d.checkHealth(ctx, port, cfg.Path) {
+		if d.checkHealth(ctx, host, port, cfg.Path) {
 			return nil
 		}
 
 		select {
 		case <-ctx.Done():
-			return fmt.Errorf("timeout after %s waiting for health check on port %d", cfg.Timeout, port)
+			return fmt.Errorf("timeout after %s waiting for health check on %s:%d", cfg.Timeout, host, port)
 		case <-time.After(cfg.Interval):
 			// retry
 		}
@@ -59,14 +80,14 @@ func (d *Deployer) healthCheck(ctx context.Context, port int, cfg HealthConfig)
 // HealthCheckPublic runs a health check against the given port using default settings.
 // This is the public entry point for on-demand health checks.
 func (d *Deployer) HealthCheckPublic(ctx context.Context, port int) error {
-	return d.healthCheck(ctx, port, defaultHealthConfig())
+	return d.healthCheck(ctx, port, defaultHealthConfig(), "")
 }
 
 // checkHealth performs a single health check attempt.
-func (d *Deployer) checkHealth(ctx context.Context, port int, path string) bool {
+func (d *Deployer) checkHealth(ctx context.Context, host string, port int, path string) bool {
 	cmd := fmt.Sprintf(
-		"curl -s -o /dev/null -w '%%{http_code}' http://localhost:%d%s",
-		port, path,
+		"curl -s -o /dev/null -w '%%{http_code}' http://%s:%d%s",
+		host, port, path,
 	)
 	output, err := d.exec.Run(ctx, cmd)
 	if err == nil {
@@ -80,15 +101,15 @@ func (d *Deployer) checkHealth(ctx context.Context, port int, path string) bool
 		// check rather than failing the deploy. A 5xx or "000" (no response)
 		// falls through and is retried until the timeout.
 		if code == "404" || strings.HasPrefix(code, "3") {
-			return d.checkTCP(ctx, port)
+			return d.checkTCP(ctx, host, port)
 		}
 	}
 	return false
 }
 
 // checkTCP verifies that a TCP connection can be established to the port.
-func (d *Deployer) checkTCP(ctx context.Context, port int) bool {
-	cmd := fmt.Sprintf("bash -c '</dev/tcp/localhost/%d' 2>/dev/null", port)
+func (d *Deployer) checkTCP(ctx context.Context, host string, port int) bool {
+	cmd := fmt.Sprintf("bash -c '</dev/tcp/%s/%d' 2>/dev/null", host, port)
 	_, err := d.exec.Run(ctx, cmd)
 	return err == nil
 }

internal/deploy/health_bind_test.go

@@ -0,0 +1,80 @@
+package deploy
+
+import (
+	"context"
+	"strings"
+	"testing"
+
+	"github.com/useteploy/teploy/internal/ssh"
+)
+
+// A container published on a specific IP is NOT reachable at localhost, so a
+// health probe hardcoded to localhost can never succeed. Because `ingress:
+// host` deploys by recreate (old container stopped first), that turned every
+// deploy of a specifically-bound app into a full outage: app healthy, probe
+// blind, deploy failed, nothing left running. Observed live on 2026-08-08
+// when dash moved from bind 0.0.0.0 to its tailnet address.
+func TestHealthProbeHost(t *testing.T) {
+	cases := map[string]string{
+		"":               "localhost", // caddy/external ingress publishes on 127.0.0.1
+		"0.0.0.0":        "localhost",
+		"::":             "localhost",
+		"[::]":           "localhost",
+		"100.108.123.49": "100.108.123.49", // tailnet-bound: must be probed there
+		"192.168.1.84":   "192.168.1.84",
+		"127.0.0.1":      "127.0.0.1",
+	}
+	for bind, want := range cases {
+		if got := healthProbeHost(bind); got != want {
+			t.Errorf("healthProbeHost(%q) = %q, want %q", bind, got, want)
+		}
+	}
+}
+
+func TestHealthCheck_ProbesTheBoundAddressNotLocalhost(t *testing.T) {
+	mock := ssh.NewMockExecutor("h", ssh.MockCommand{Match: "curl", Output: "200"})
+	d := &Deployer{exec: mock, out: nopWriter{}}
+
+	if err := d.healthCheck(context.Background(), 3456, defaultHealthConfig(), "100.108.123.49"); err != nil {
+		t.Fatalf("healthCheck: %v", err)
+	}
+	var probed string
+	for _, c := range mock.Calls {
+		if strings.HasPrefix(c, "curl") {
+			probed = c
+		}
+	}
+	if !strings.Contains(probed, "http://100.108.123.49:3456") {
+		t.Errorf("probe should dial the bound address, got: %s", probed)
+	}
+	if strings.Contains(probed, "localhost") {
+		t.Errorf("probe must not fall back to localhost for a specifically-bound app: %s", probed)
+	}
+}
+
+// The TCP fallback (used when the health path 404s or redirects) has to dial
+// the same address, or a bound app with no /health endpoint still fails.
+func TestHealthCheck_TCPFallbackAlsoUsesTheBoundAddress(t *testing.T) {
+	mock := ssh.NewMockExecutor("h",
+		ssh.MockCommand{Match: "curl", Output: "404"},
+		ssh.MockCommand{Match: "bash -c", Output: ""},
+	)
+	d := &Deployer{exec: mock, out: nopWriter{}}
+
+	if err := d.healthCheck(context.Background(), 3456, defaultHealthConfig(), "100.108.123.49"); err != nil {
+		t.Fatalf("healthCheck with TCP fallback: %v", err)
+	}
+	var tcp string
+	for _, c := range mock.Calls {
+		if strings.HasPrefix(c, "bash -c") {
+			tcp = c
+		}
+	}
+	if !strings.Contains(tcp, "/dev/tcp/100.108.123.49/3456") {
+		t.Errorf("TCP fallback should dial the bound address, got: %s", tcp)
+	}
+}
+
+type nopWriter struct{}
+
+func (nopWriter) Write(p []byte) (int, error) { return len(p), nil }

internal/deploy/lifecycle.go

@@ -75,7 +75,9 @@ func (l *Lifecycle) Start(ctx context.Context, app string) error {
 	if current.CurrentPort > 0 {
 		fmt.Fprintln(l.out, "Running health check...")
 		deployer := &Deployer{exec: l.exec, out: l.out}
-		if err := deployer.healthCheck(ctx, current.CurrentPort, defaultHealthConfig()); err != nil {
+		// Probe the bound address, not localhost — see healthProbeHost.
+		bindHost := l.docker.HostBindIP(ctx, containers[0].Name)
+		if err := deployer.healthCheck(ctx, current.CurrentPort, defaultHealthConfig(), bindHost); err != nil {
 			return fmt.Errorf("health check failed after start: %w", err)
 		}
 		fmt.Fprintln(l.out, "  Health check passed")
@@ -121,7 +123,9 @@ func (l *Lifecycle) Restart(ctx context.Context, app string, timeout int) error
 	if current.CurrentPort > 0 {
 		fmt.Fprintln(l.out, "Running health check...")
 		deployer := &Deployer{exec: l.exec, out: l.out}
-		if err := deployer.healthCheck(ctx, current.CurrentPort, defaultHealthConfig()); err != nil {
+		// Probe the bound address, not localhost — see healthProbeHost.
+		bindHost := l.docker.HostBindIP(ctx, containers[0].Name)
+		if err := deployer.healthCheck(ctx, current.CurrentPort, defaultHealthConfig(), bindHost); err != nil {
 			return fmt.Errorf("health check failed after restart: %w", err)
 		}
 		fmt.Fprintln(l.out, "  Health check passed")

internal/deploy/rollback.go

@@ -210,15 +210,22 @@ func Rollback(ctx context.Context, exec ssh.Executor, out io.Writer, cfg Rollbac
 	fmt.Fprintln(out, "Running health check...")
 	deployer := &Deployer{exec: exec, out: out}
 	healthPorts := make([]int, 0, len(targetWeb))
+	// Probe the address docker actually bound, not localhost: a container
+	// published on a specific IP is unreachable there, which would fail every
+	// rollback of a host-ingress app with a bind address.
+	healthBindHost := ""
 	for _, c := range targetWeb {
 		p, err := dk.HostPort(ctx, c.Name)
 		if err != nil {
 			return fmt.Errorf("inspecting target container host port: %w", err)
 		}
 		healthPorts = append(healthPorts, p)
+		if healthBindHost == "" {
+			healthBindHost = dk.HostBindIP(ctx, c.Name)
+		}
 	}
 	for _, p := range healthPorts {
-		if err := deployer.healthCheck(ctx, p, healthCfg); err != nil {
+		if err := deployer.healthCheck(ctx, p, healthCfg, healthBindHost); err != nil {
 			// Stop what we started and bail.
 			for _, name := range started {
 				dk.Stop(ctx, name, 5)

internal/docker/docker.go

@@ -628,6 +628,29 @@ func (c *Client) HostPort(ctx context.Context, name string) (int, error) {
 	return port, nil
 }
 
+// HostBindIP returns the host IP a container's first published port is bound
+// to ("0.0.0.0" for all interfaces, or a specific address).
+//
+// Needed because a container published on a specific IP is not reachable at
+// localhost, so anything probing it — health checks on rollback and restart —
+// must dial the address docker actually bound. Returns "" when it cannot be
+// determined, which callers treat as "assume localhost", the historical
+// behavior.
+func (c *Client) HostBindIP(ctx context.Context, name string) string {
+	out, err := c.exec.Run(ctx, fmt.Sprintf(
+		"docker inspect -f '{{range $p, $b := .NetworkSettings.Ports}}{{range $b}}{{.HostIp}} {{end}}{{end}}' %s",
+		ssh.ShellQuote(name),
+	))
+	if err != nil {
+		return ""
+	}
+	fields := strings.Fields(out)
+	if len(fields) == 0 {
+		return ""
+	}
+	return fields[0]
+}
+
 // InternalPort returns the container's internal listening port — the port
 // the app speaks HTTP on inside the Docker network, not the host-mapped
 // port. Caddy dials this port when reverse-proxying over the teploy