Stage 3 · Build

Long-Running Daemons & Services

Supervisor Integration

systemd NotifyAccess, Docker healthchecks, PID 1 behavior, and exit code contracts.

6 min readGo for SREBuild

PID 1 Behavior

When running as PID 1 in a container, Go processes have special behavior. PID 1 does not have a default signal handler — signals are ignored unless explicitly handled.

Gopid-1-signal-handling.go

32 linesLn 1, Col 1Go

PID 1 in Linux containers does not have default signal handling. SIGTERM is ignored unless the process explicitly handles it. Always use signal.Notify or signal.NotifyContext. This is the most common container bug in Go.

Exit Code Contracts

Goexit-code-conventions.go

36 linesLn 1, Col 1Go

Exit codes communicate failure reasons. 0 is success. 1-125 are application errors. 126-127 are command errors. 128+N means killed by signal N. Use specific exit codes for different failure modes — they help operators diagnose issues.

systemd Integration

Gosystemd-notification.go

42 linesLn 1, Col 1Go

Type=notify tells systemd the service will send READY=1 when initialized. NotifyAccess=all allows any user to send notifications. Restart=on-failure restarts on non-zero exit. StartLimit prevents infinite restart loops.

Docker Healthchecks

Docker healthcheck


# Dockerfile
FROM golang:1.22 AS build
WORKDIR /app
COPY . .
RUN CGO_ENABLED=0 go build -o /app/server ./cmd/server

FROM gcr.io/distroless/static:nonroot
COPY --from=build /app/server /server
EXPOSE 8080

# Healthcheck
HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
  CMD ["/server", "--healthcheck"]

# Or use wget (distroless doesn't have curl)
HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
  CMD wget -qO- http://localhost:8080/healthz || exit 1

HEALTHCHECK tells Docker how to check container health. interval: time between checks. timeout: max time per check. start-period: grace period for startup. retries: consecutive failures before unhealthy. Distroless images don't have curl — use wget or a built-in healthcheck flag.

Signal Forwarding

Gosignal-forwarding-for-child-processes.go

29 linesLn 1, Col 1Go

When running child processes, forward signals to them. This ensures the child can shut down gracefully. Without forwarding, the child ignores signals and is killed by SIGKILL after the grace period.

Process Replacement

Gograceful-process-replacement.go

39 linesLn 1, Col 1Go

Process replacement enables zero-downtime upgrades. Start the new process, pass the listening socket, wait for readiness, then exit the old process. ExtraFiles passes open file descriptors to child processes.

Always handle PID 1 signals

Every container process must handle SIGTERM. Without explicit handling, SIGTERM is ignored and Docker must use SIGKILL after the grace period. This prevents graceful shutdown and causes data loss.

Mark this lesson complete to store local progress and unlock a cleaner resume path the next time you visit.