feat: strict zero-downtime deploy with readiness probes and rollback

docs/config/index.md

@@ -106,7 +106,6 @@ preserve = true                          # Keep volumes on container removal
 [network_isolation]
 enabled = true                           # Per-app isolated networks
 network_prefix = "gordon"                # Network name prefix
-dns_suffix = ".internal"                 # DNS suffix for services
 
 # Auto-route
 [auto_route]

docs/config/network-isolation.md

@@ -8,7 +8,6 @@ Isolate applications in separate Docker networks for enhanced security.
 [network_isolation]
 enabled = true
 network_prefix = "gordon"
-dns_suffix = ".internal"
 ```
 
 ## Options
@@ -17,7 +16,6 @@ dns_suffix = ".internal"
 |--------|------|---------|-------------|
 | `enabled` | bool | `false` | Enable per-app network isolation |
 | `network_prefix` | string | `"gordon"` | Prefix for created networks |
-| `dns_suffix` | string | `".internal"` | DNS suffix for service discovery |
 
 ## How It Works
 
@@ -99,19 +97,6 @@ db = connect("postgresql://postgres:5432/mydb")
 cache = connect("redis://redis:6379")
 ```
 
-## DNS Resolution
-
-The `dns_suffix` option adds a suffix for internal DNS resolution:
-
-```toml
-[network_isolation]
-dns_suffix = ".internal"
-```
-
-Services can be accessed as:
-- `postgres` (short form)
-- `postgres.internal` (with suffix)
-
 ## Examples
 
 ### Basic Isolation
@@ -137,7 +122,6 @@ Each app gets its own network with its own database.
 [network_isolation]
 enabled = true
 network_prefix = "prod"
-dns_suffix = ".internal"
 
 [routes]
 "app.company.com" = "company-app:v2.1.0"

docs/config/reference.md

@@ -105,7 +105,6 @@ enabled = false                              # Create routes from image labels a
 [network_isolation]
 enabled = false                              # Enable per-app Docker networks
 network_prefix = "gordon"                    # Prefix for created networks
-dns_suffix = ".internal"                     # DNS suffix for internal resolution
 
 # =============================================================================
 # VOLUMES
@@ -215,7 +214,6 @@ keep_last = 3                                # Keep N newest tags per repository
 | `auto_route.enabled` | `false` | Auto-route disabled |
 | `network_isolation.enabled` | `false` | Isolation disabled |
 | `network_isolation.network_prefix` | `"gordon"` | Network prefix |
-| `network_isolation.dns_suffix` | `".internal"` | DNS suffix |
 | `volumes.auto_create` | `true` | Auto-create volumes |
 | `volumes.prefix` | `"gordon"` | Volume prefix |
 | `volumes.preserve` | `true` | Keep volumes |

docs/reference/docker-labels.md

@@ -41,7 +41,27 @@ Labels you can set in your Dockerfile:
 
 | Label | Example | Description |
 |-------|---------|-------------|
-| `gordon.proxy.port` | `"3000"` | Port to proxy HTTP traffic to |
+| `gordon.domains` | `"app.example.com,www.app.example.com"` | Comma-separated domains for auto-route |
+| `gordon.port` | `"3000"` | Port to proxy HTTP traffic to |
+| `gordon.proxy.port` | `"3000"` | Port to proxy HTTP traffic to (legacy alias for `gordon.port`) |
+| `gordon.health` | `"/healthz"` | HTTP health check endpoint path for readiness probing |
+| `gordon.env-file` | `"/app/.env.example"` | Path to env template file inside the image |
+
+### Health Check Label
+
+When `gordon.health` is set, Gordon performs HTTP GET requests to the specified
+path during deployment and waits for a 2xx or 3xx response before routing traffic
+to the new container:
+
+```dockerfile
+FROM node:20-alpine
+LABEL gordon.health="/api/health"
+EXPOSE 3000
+CMD ["node", "server.js"]
+```
+
+Gordon probes `http://<container-ip>:3000/api/health` until it gets a successful
+response or the `deploy.http_probe_timeout` is reached.
 
 ### Proxy Port Label
 

internal/adapters/in/cli/controlplane.go

@@ -34,6 +34,7 @@ type ControlPlane interface {
 
 	GetStatus(ctx context.Context) (*remote.Status, error)
 	Reload(ctx context.Context) error
+	DeployIntent(ctx context.Context, imageName string) error
 	Deploy(ctx context.Context, deployDomain string) (*remote.DeployResult, error)
 	Restart(ctx context.Context, restartDomain string, withAttachments bool) (*remote.RestartResult, error)
 	ListTags(ctx context.Context, repository string) ([]string, error)

internal/adapters/in/cli/controlplane_local.go

@@ -18,6 +18,7 @@ type localControlPlane struct {
 	containerSvc in.ContainerService
 	backupSvc    in.BackupService
 	registrySvc  in.RegistryService
+	deployCoord  in.DeployCoordinator
 	healthSvc    in.HealthService
 	logSvc       in.LogService
 }
@@ -27,12 +28,21 @@ func NewLocalControlPlane(kernel *app.Kernel) ControlPlane {
 		return &localControlPlane{}
 	}
 
+	registrySvc := kernel.Registry()
+	var deployCoord in.DeployCoordinator
+	if registrySvc != nil {
+		if coordinator, ok := any(registrySvc).(in.DeployCoordinator); ok {
+			deployCoord = coordinator
+		}
+	}
+
 	return &localControlPlane{
 		configSvc:    kernel.Config(),
 		secretSvc:    kernel.Secrets(),
 		containerSvc: kernel.Container(),
 		backupSvc:    kernel.Backup(),
-		registrySvc:  kernel.Registry(),
+		registrySvc:  registrySvc,
+		deployCoord:  deployCoord,
 		healthSvc:    kernel.Health(),
 		logSvc:       kernel.Logs(),
 	}
@@ -223,6 +233,13 @@ func (l *localControlPlane) Reload(_ context.Context) error {
 	return app.SendReloadSignal()
 }
 
+func (l *localControlPlane) DeployIntent(_ context.Context, imageName string) error {
+	if l.deployCoord != nil {
+		l.deployCoord.SuppressDeployEvent(imageName)
+	}
+	return nil
+}
+
 func (l *localControlPlane) Deploy(ctx context.Context, deployDomain string) (*remote.DeployResult, error) {
 	if l.containerSvc != nil && l.configSvc != nil {
 		route, err := l.configSvc.GetRoute(ctx, deployDomain)

internal/adapters/in/cli/controlplane_remote.go

@@ -88,6 +88,10 @@ func (r *remoteControlPlane) Reload(ctx context.Context) error {
 	return r.client.Reload(ctx)
 }
 
+func (r *remoteControlPlane) DeployIntent(ctx context.Context, imageName string) error {
+	return r.client.DeployIntent(ctx, imageName)
+}
+
 func (r *remoteControlPlane) Deploy(ctx context.Context, deployDomain string) (*remote.DeployResult, error) {
 	return r.client.Deploy(ctx, deployDomain)
 }

internal/adapters/in/cli/push.go

@@ -154,6 +154,15 @@ func runPush(ctx context.Context, imageArg, domainFlag, tag string, build bool,
 	}
 	fmt.Printf("Domain: %s\n", styles.Theme.Bold.Render(pushDomain))
 
+	// Signal the server to suppress event-based deploys for this image.
+	// The CLI will trigger an explicit deploy after push completes.
+	if !noDeploy {
+		if err := handle.plane.DeployIntent(ctx, imageName); err != nil {
+			// Non-fatal: worst case we get a redundant deploy via event
+			fmt.Fprintf(os.Stderr, "warning: failed to register deploy intent: %v\n", err)
+		}
+	}
+
 	if build {
 		if err := buildAndPush(ctx, version, platform, dockerfile, buildArgs, versionRef, latestRef); err != nil {
 			return err

internal/adapters/in/cli/remote/client.go

@@ -724,6 +724,20 @@ func (c *Client) Deploy(ctx context.Context, deployDomain string) (*DeployResult
 	return &result, nil
 }
 
+// DeployIntent tells the server that a CLI-managed push is about to happen,
+// suppressing event-based deploys for this image.
+func (c *Client) DeployIntent(ctx context.Context, imageName string) error {
+	imageName = strings.TrimSpace(imageName)
+	if imageName == "" {
+		return fmt.Errorf("image name cannot be empty")
+	}
+	resp, err := c.requestWithRetry(ctx, http.MethodPost, "/deploy-intent/"+url.PathEscape(imageName), nil)
+	if err != nil {
+		return err
+	}
+	return parseResponse(resp, nil)
+}
+
 // Restart API
 
 // RestartResult contains the result of a restart.

internal/adapters/in/http/admin/handler.go

@@ -7,6 +7,7 @@ import (
 	"fmt"
 	"io"
 	"net/http"
+	"net/url"
 	"strconv"
 	"strings"
 	"time"
@@ -27,6 +28,11 @@ const maxAdminRequestSize = 1 << 20 // 1MB
 // maxLogLines is the maximum allowed number of log lines that can be requested.
 const maxLogLines = 10000
 
+type registryDeployService interface {
+	in.RegistryService
+	in.DeployCoordinator
+}
+
 // Handler implements the HTTP handler for the admin API.
 type Handler struct {
 	configSvc    in.ConfigService
@@ -37,7 +43,7 @@ type Handler struct {
 	healthSvc    in.HealthService
 	secretSvc    in.SecretService
 	logSvc       in.LogService
-	registrySvc  in.RegistryService
+	registrySvc  registryDeployService
 	eventBus     out.EventPublisher
 	log          zerowrap.Logger
 }
@@ -129,7 +135,7 @@ func NewHandler(
 	healthSvc in.HealthService,
 	secretSvc in.SecretService,
 	logSvc in.LogService,
-	registrySvc in.RegistryService,
+	registrySvc registryDeployService,
 	eventBus out.EventPublisher,
 	log zerowrap.Logger,
 	backupSvc in.BackupService,
@@ -213,6 +219,7 @@ func (h *Handler) matchRoute(path string) (routeHandler, bool) {
 		{"/routes/by-image", h.handleRoutesByImage},
 		{"/routes", h.handleRoutes},
 		{"/secrets", h.handleSecrets},
+		{"/deploy-intent", h.handleDeployIntent},
 		{"/deploy", h.handleDeploy},
 		{"/restart", h.handleRestart},
 		{"/tags", h.handleTags},
@@ -228,6 +235,48 @@ func (h *Handler) matchRoute(path string) (routeHandler, bool) {
 	return nil, false
 }
 
+// handleDeployIntent handles /admin/deploy-intent/:image endpoint.
+// It registers a deploy intent, suppressing event-based deploys for the image.
+func (h *Handler) handleDeployIntent(w http.ResponseWriter, r *http.Request, path string) {
+	if r.Method != http.MethodPost {
+		h.sendError(w, http.StatusMethodNotAllowed, "method not allowed")
+		return
+	}
+
+	ctx := r.Context()
+	if !HasAccess(ctx, domain.AdminResourceConfig, domain.AdminActionWrite) {
+		h.sendError(w, http.StatusForbidden, "insufficient permissions for config:write")
+		return
+	}
+
+	if h.registrySvc == nil {
+		h.sendError(w, http.StatusServiceUnavailable, "registry service unavailable")
+		return
+	}
+
+	rawName := strings.TrimPrefix(path, "/deploy-intent/")
+	if rawName == "" || rawName == "/deploy-intent" {
+		h.sendError(w, http.StatusBadRequest, "image name required")
+		return
+	}
+
+	imageName, err := url.PathUnescape(rawName)
+	if err != nil {
+		h.sendError(w, http.StatusBadRequest, "invalid image name encoding")
+		return
+	}
+
+	log := zerowrap.FromCtx(ctx)
+	log.Info().Str("image", imageName).Msg("deploy intent registered, suppressing image.pushed events")
+
+	h.registrySvc.SuppressDeployEvent(imageName)
+
+	h.sendJSON(w, http.StatusOK, map[string]string{
+		"status": "ok",
+		"image":  imageName,
+	})
+}
+
 // sendJSON sends a JSON response.
 func (h *Handler) sendJSON(w http.ResponseWriter, status int, data any) {
 	w.Header().Set("Content-Type", "application/json")
@@ -1078,6 +1127,15 @@ func (h *Handler) handleDeploy(w http.ResponseWriter, r *http.Request, path stri
 		return
 	}
 
+	// Clear deploy event suppression now that the explicit deploy has completed.
+	// This re-enables event-based deploys for future direct docker pushes.
+	if route.Image != "" && h.registrySvc != nil {
+		// Use the registry package's image name normaliser so digest-form refs
+		// and multi-segment paths are handled correctly.
+		imageName := registry.ExtractImageName(route.Image)
+		h.registrySvc.ClearDeployEventSuppression(imageName)
+	}
+
 	log.Info().Str("domain", deployDomain).Str("container_id", container.ID).Msg("container deployed via admin API")
 	h.sendJSON(w, http.StatusOK, dto.DeployResponse{
 		Status:      "deployed",

internal/app/run.go

@@ -1187,12 +1187,14 @@ func createContainerService(ctx context.Context, v *viper.Viper, cfg Config, svc
 		VolumePreserve:           v.GetBool("volumes.preserve"),
 		NetworkIsolation:         v.GetBool("network_isolation.enabled"),
 		NetworkPrefix:            v.GetString("network_isolation.network_prefix"),
-		DNSSuffix:                v.GetString("network_isolation.dns_suffix"),
 		NetworkGroups:            svc.configSvc.GetNetworkGroups(),
 		Attachments:              svc.configSvc.GetAttachments(),
 		ReadinessDelay:           v.GetDuration("deploy.readiness_delay"),
 		ReadinessMode:            v.GetString("deploy.readiness_mode"),
 		HealthTimeout:            v.GetDuration("deploy.health_timeout"),
+		StabilizationDelay:       v.GetDuration("deploy.stabilization_delay"),
+		TCPProbeTimeout:          v.GetDuration("deploy.tcp_probe_timeout"),
+		HTTPProbeTimeout:         v.GetDuration("deploy.http_probe_timeout"),
 		DrainDelay:               v.GetDuration("deploy.drain_delay"),
 		DrainMode:                v.GetString("deploy.drain_mode"),
 		DrainTimeout:             v.GetDuration("deploy.drain_timeout"),
@@ -2346,7 +2348,6 @@ func loadConfig(v *viper.Viper, configPath string) error {
 	v.SetDefault("auto_route.enabled", false)
 	v.SetDefault("network_isolation.enabled", false)
 	v.SetDefault("network_isolation.network_prefix", "gordon")
-	v.SetDefault("network_isolation.dns_suffix", ".internal")
 	v.SetDefault("volumes.auto_create", true)
 	v.SetDefault("volumes.prefix", "gordon")
 	v.SetDefault("volumes.preserve", true)
@@ -2374,6 +2375,9 @@ func loadConfig(v *viper.Viper, configPath string) error {
 	v.SetDefault("deploy.readiness_delay", "5s")
 	v.SetDefault("deploy.readiness_mode", "auto")
 	v.SetDefault("deploy.health_timeout", "90s")
+	v.SetDefault("deploy.stabilization_delay", "2s")
+	v.SetDefault("deploy.tcp_probe_timeout", "30s")
+	v.SetDefault("deploy.http_probe_timeout", "60s")
 	v.SetDefault("deploy.drain_mode", "auto")
 	v.SetDefault("deploy.drain_timeout", "30s")
 

internal/boundaries/in/deploy.go

@@ -0,0 +1,10 @@
+package in
+
+// DeployCoordinator defines deploy coordination operations.
+//
+// These methods let the CLI/admin API suppress image-pushed deploy events
+// while an explicit deploy flow is in progress.
+type DeployCoordinator interface {
+	SuppressDeployEvent(imageName string)
+	ClearDeployEventSuppression(imageName string)
+}