fix: restore Docker HEALTHCHECK with built-in --health-check flag (#385)

## Summary
- Add `--health-check` flag to binary that performs HTTP GET to
`/health/live`
- Restore `HEALTHCHECK` instruction in Dockerfile (works with distroless
- no shell/curl needed)
- Remove `healthcheck: disable: true` from compose.yml
- Add integration test for Docker health check verification

## Background
The previous HEALTHCHECK was removed in #383 because the
`--health-check` flag didn't exist in the binary. This PR implements the
flag properly so the health check actually works.

## Test plan
- [x] Built Docker image and verified container becomes healthy
- [x] Tested `/health/live` endpoint returns `{"status":"alive"}`
- [x] Added integration test `TestDockerHealthCheck` that verifies the
full flow

Author: CybotTM

Dockerfile

@@ -150,5 +150,9 @@ COPY --from=backend-builder \
 # Set user to nonroot for security (UID 65532)
 USER nonroot:nonroot
 
+# Health check using built-in --health-check flag (works in distroless without shell)
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+  CMD ["/ldap-passwd", "--health-check"]
+
 # Use vector form for ENTRYPOINT as recommended by distroless docs
 ENTRYPOINT ["/ldap-passwd"]

cmd/ldap-manager/main.go

@@ -4,6 +4,7 @@ package main
 
 import (
 	"context"
+	"net/http"
 	"os"
 	"os/signal"
 	"syscall"
@@ -17,9 +18,18 @@ import (
 	"github.com/netresearch/ldap-manager/internal/web"
 )
 
-const shutdownTimeout = 30 * time.Second
+const (
+	shutdownTimeout     = 30 * time.Second
+	healthCheckTimeout  = 3 * time.Second
+	healthCheckEndpoint = "http://localhost:3000/health/live"
+)
 
 func main() {
+	// Handle --health-check flag early, before any other initialization
+	if len(os.Args) == 2 && os.Args[1] == "--health-check" {
+		os.Exit(runHealthCheck())
+	}
+
 	log.Logger = log.Output(zerolog.ConsoleWriter{Out: os.Stderr})
 
 	log.Info().Msgf("LDAP Manager %s starting...", version.FormatVersion())
@@ -74,3 +84,29 @@ func main() {
 
 	log.Info().Msg("Graceful shutdown complete")
 }
+
+// runHealthCheck performs an HTTP health check against the running application.
+// Returns 0 if healthy (HTTP 200), 1 otherwise.
+// Used by Docker HEALTHCHECK to verify the application is running correctly.
+func runHealthCheck() int {
+	ctx, cancel := context.WithTimeout(context.Background(), healthCheckTimeout)
+	defer cancel()
+
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, healthCheckEndpoint, nil)
+	if err != nil {
+		return 1
+	}
+
+	client := &http.Client{}
+	resp, err := client.Do(req)
+	if err != nil {
+		return 1
+	}
+	defer func() { _ = resp.Body.Close() }()
+
+	if resp.StatusCode == http.StatusOK {
+		return 0
+	}
+
+	return 1
+}

compose.yml

@@ -105,8 +105,6 @@ services:
       - /etc/ssl/certs:/etc/ssl/certs:ro
       - /usr/local/share/ca-certificates:/usr/local/share/ca-certificates:ro
     restart: unless-stopped
-    healthcheck:
-      disable: true
     profiles:
       - prod
     ports:

internal/integration/docker_healthcheck_test.go

@@ -0,0 +1,202 @@
+//go:build integration
+
+package integration
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"os"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"github.com/testcontainers/testcontainers-go"
+	"github.com/testcontainers/testcontainers-go/wait"
+)
+
+// TestDockerHealthCheck verifies the Docker HEALTHCHECK directive works correctly
+// by building and running the production container and checking its health status.
+//
+// Note: This test builds the Docker image from source, which requires Docker BuildKit
+// and may not work in all CI environments (e.g., GitHub Actions runners have platform
+// detection issues with testcontainers). Run locally with: make test-integration
+func TestDockerHealthCheck(t *testing.T) {
+	if testing.Short() {
+		t.Skip("Skipping Docker healthcheck test in short mode")
+	}
+
+	// Skip in CI environments where Docker-in-Docker building has platform issues
+	if os.Getenv("CI") == "true" || os.Getenv("GITHUB_ACTIONS") == "true" {
+		t.Skip("Skipping Docker build test in CI - run locally with: make test-integration")
+	}
+
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Minute)
+	defer cancel()
+
+	// Start OpenLDAP first
+	ldapContainer, err := StartOpenLDAP(ctx, DefaultOpenLDAPConfig())
+	require.NoError(t, err, "Failed to start OpenLDAP container")
+	defer func() { _ = ldapContainer.Stop(ctx) }()
+
+	// Wait for LDAP to be ready and seed test data
+	time.Sleep(2 * time.Second)
+	err = ldapContainer.SeedTestData(ctx)
+	require.NoError(t, err, "Failed to seed test data")
+
+	// Get LDAP container network info
+	ldapNetwork, err := ldapContainer.Container.ContainerIP(ctx)
+	require.NoError(t, err, "Failed to get LDAP container IP")
+
+	// Build and start the ldap-manager container
+	appContainer, appPort, err := startLDAPManagerContainer(ctx, t, ldapNetwork, ldapContainer)
+	require.NoError(t, err, "Failed to start ldap-manager container")
+	defer func() { _ = appContainer.Terminate(ctx) }()
+
+	t.Run("container becomes healthy", func(t *testing.T) {
+		// The container should become healthy via Docker HEALTHCHECK
+		// We wait for up to 60 seconds (start_period=5s, interval=30s, so first check at ~35s)
+		healthy := waitForContainerHealth(ctx, t, appContainer, 60*time.Second)
+		assert.True(t, healthy, "Container should become healthy")
+	})
+
+	t.Run("liveness endpoint returns 200", func(t *testing.T) {
+		resp, err := doHTTPGet(ctx, fmt.Sprintf("http://localhost:%s/health/live", appPort))
+		require.NoError(t, err, "Failed to call liveness endpoint")
+		defer func() { _ = resp.Body.Close() }()
+
+		assert.Equal(t, http.StatusOK, resp.StatusCode, "Liveness endpoint should return 200")
+
+		var result map[string]interface{}
+		err = json.NewDecoder(resp.Body).Decode(&result)
+		require.NoError(t, err, "Failed to decode response")
+		assert.Equal(t, "alive", result["status"], "Status should be 'alive'")
+	})
+
+	t.Run("health endpoint returns details", func(t *testing.T) {
+		resp, err := doHTTPGet(ctx, fmt.Sprintf("http://localhost:%s/health", appPort))
+		require.NoError(t, err, "Failed to call health endpoint")
+		defer func() { _ = resp.Body.Close() }()
+
+		assert.Equal(t, http.StatusOK, resp.StatusCode, "Health endpoint should return 200")
+
+		var result map[string]interface{}
+		err = json.NewDecoder(resp.Body).Decode(&result)
+		require.NoError(t, err, "Failed to decode response")
+		assert.Contains(t, result, "cache", "Response should contain cache info")
+		assert.Contains(t, result, "connection_pool", "Response should contain connection pool info")
+		assert.Contains(t, result, "overall_healthy", "Response should contain overall health status")
+	})
+
+	t.Run("readiness endpoint returns ready", func(t *testing.T) {
+		// Wait a bit for cache warmup
+		time.Sleep(5 * time.Second)
+
+		resp, err := doHTTPGet(ctx, fmt.Sprintf("http://localhost:%s/health/ready", appPort))
+		require.NoError(t, err, "Failed to call readiness endpoint")
+		defer func() { _ = resp.Body.Close() }()
+
+		// Readiness might be 200 (ready) or 503 (warming up) - both are valid
+		assert.Contains(t, []int{http.StatusOK, http.StatusServiceUnavailable}, resp.StatusCode,
+			"Readiness endpoint should return 200 or 503")
+	})
+}
+
+// startLDAPManagerContainer builds and starts the ldap-manager production container.
+func startLDAPManagerContainer(
+	ctx context.Context,
+	t *testing.T,
+	ldapIP string,
+	ldap *OpenLDAPContainer,
+) (testcontainers.Container, string, error) {
+	t.Helper()
+
+	req := testcontainers.ContainerRequest{
+		FromDockerfile: testcontainers.FromDockerfile{
+			Context:    "../..",
+			Dockerfile: "Dockerfile",
+			BuildArgs: map[string]*string{
+				"BUILD_DATE": strPtr(time.Now().UTC().Format(time.RFC3339)),
+				"VCS_REF":    strPtr("test"),
+			},
+			KeepImage: true,
+		},
+		ExposedPorts: []string{"3000/tcp"},
+		Env: map[string]string{
+			"LDAP_SERVER":            fmt.Sprintf("ldap://%s:389", ldapIP),
+			"LDAP_BASE_DN":           ldap.BaseDN,
+			"LDAP_READONLY_USER":     ldap.AdminDN,
+			"LDAP_READONLY_PASSWORD": ldap.AdminPass,
+			"SESSION_SECRET":         "test-session-secret-for-integration-tests",
+			"LOG_LEVEL":              "debug",
+		},
+		WaitingFor: wait.ForHTTP("/health/live").
+			WithPort("3000/tcp").
+			WithStartupTimeout(90 * time.Second),
+	}
+
+	container, err := testcontainers.GenericContainer(ctx, testcontainers.GenericContainerRequest{
+		ContainerRequest: req,
+		Started:          true,
+	})
+	if err != nil {
+		return nil, "", fmt.Errorf("failed to start ldap-manager container: %w", err)
+	}
+
+	port, err := container.MappedPort(ctx, "3000")
+	if err != nil {
+		_ = container.Terminate(ctx)
+
+		return nil, "", fmt.Errorf("failed to get mapped port: %w", err)
+	}
+
+	return container, port.Port(), nil
+}
+
+// waitForContainerHealth polls the container health status until healthy or timeout.
+func waitForContainerHealth(
+	ctx context.Context,
+	t *testing.T,
+	container testcontainers.Container,
+	timeout time.Duration,
+) bool {
+	t.Helper()
+
+	deadline := time.Now().Add(timeout)
+	for time.Now().Before(deadline) {
+		state, err := container.State(ctx)
+		if err != nil {
+			t.Logf("Error getting container state: %v", err)
+			time.Sleep(2 * time.Second)
+
+			continue
+		}
+
+		if state.Health != nil && state.Health.Status == "healthy" {
+			t.Logf("Container is healthy after %v", timeout-time.Until(deadline))
+
+			return true
+		}
+
+		t.Logf("Container health status: %v", state.Health)
+		time.Sleep(2 * time.Second)
+	}
+
+	return false
+}
+
+// doHTTPGet performs an HTTP GET request with context.
+func doHTTPGet(ctx context.Context, url string) (*http.Response, error) {
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
+	if err != nil {
+		return nil, err
+	}
+
+	return http.DefaultClient.Do(req)
+}
+
+func strPtr(s string) *string {
+	return &s
+}