rolling_deployment

package module
v0.9.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 25, 2026 License: MIT Imports: 13 Imported by: 0

README

rolling_deployment

Caddy HTTP handler that performs rolling Docker container deployments via a webhook.

Module ID: http.handlers.rolling_deployment
Caddyfile directive: rolling_deployment
Go module: github.com/multionlabs/caddy-plugins/rolling_deployment
Current release: v0.9.0

What it does

When a deploy webhook is received, the plugin:

  1. Finds configured Docker hosts where a container with the given name is already running.
  2. On each of those hosts (in order), pulls the new image, snapshots the running container’s spec, renames the old container aside, starts a replacement with the same name/spec and the new image, then removes the backup on success.
  3. Stops on the first host failure (fail-fast). Hosts already updated stay on the new image (HTTP 207); a failed host is rolled back when possible.

Preserved from the previous container (when present): command/entrypoint, env, labels, mounts (bind + named volumes), published ports, networks, restart policy, and related create options.

Install

xcaddy build \
  --with github.com/multionlabs/caddy-plugins/rolling_deployment@v0.9.0

Local checkout (from the monorepo root):

xcaddy build \
  --with github.com/multionlabs/caddy-plugins/rolling_deployment=./rolling_deployment

sample Caddyfile

:8080 {
	rolling_deployment {
		secret {$ROLLING_DEPLOY_SECRET}
		docker_hosts unix:///var/run/docker.sock
		# docker_hosts tcp://host-a:2375 tcp://host-b:2375
	}

	respond "ok" 200
}
Option Required Description
secret yes Shared secret; must match the webhook path segment.
docker_hosts no One or more Docker Engine API endpoints. Defaults to unix:///var/run/docker.sock.

Directive order is registered in code (before respond).

Webhook

POST|GET /webhooks/rolling-deployment/{secret}/{service_container}/{service_image}
  • service_container — exact Docker container name (must already be running on at least one configured host).
  • service_image — image reference; may contain / (e.g. ghcr.io/org/app:1.2.3).

Example:

curl -si \
  "http://127.0.0.1:8080/webhooks/rolling-deployment/${ROLLING_DEPLOY_SECRET}/my-app/ghcr.io/acme/my-app:1.2.3"
Response

JSON body (success / partial):

{
  "partial": false,
  "hosts": [
    { "host_index": 0, "ok": true }
  ]
}

Raw Docker host URLs, daemon error text, and the request’s container/image strings are not echoed in the response (details stay in Caddy logs).

Status Meaning
200 All selected hosts updated.
207 Partial: at least one host updated, then the roll stopped.
400 Bad path/image, or container not running on any configured host.
401 Secret mismatch.
409 A deploy for the same container name is already in progress.
422 Image/spec incompatible; previous container restored when possible.
502 Docker/infrastructure failure.

Behavior notes

  • Selection: only hosts where the named container is currently running are updated; others are skipped.
  • Concurrency: overlapping deploys of the same container name return 409; different names can run in parallel.
  • Rollback: on a failed recreate/start, the plugin attempts to restore the previous container (backup name pattern: {name}_rollback_YYYYMMDDHHMMSS).
  • Secrets: treat the webhook secret like a deploy credential; prefer HTTPS in production.

Development

cd rolling_deployment
go test ./...
golangci-lint run ./...

Integration scenarios (requires Docker + a test Caddy from tests/with-caddy/run.sh):

./tests/with-caddy/scenario-basic.sh
./tests/with-caddy/scenario-spec-preservation.sh
./tests/with-caddy/scenario-rollback.sh
./tests/with-caddy/scenario-concurrency.sh

Release (this plugin)

Tags are subdirectory-prefixed in the monorepo:

git tag rolling_deployment/v0.9.0
git push origin rolling_deployment/v0.9.0

Consumers then pin @v0.9.0 as shown under Install.

License

MIT — see the repository LICENSE.

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Middleware

type Middleware struct {
	// Secret is the shared webhook credential. It must match the {secret}
	// path segment. Required.
	Secret string `json:"secret,omitempty"`

	// DockerHosts is the list of Docker Engine API endpoints to consider
	// (for example unix:///var/run/docker.sock or tcp://host:2375).
	// Defaults to the local Docker socket when omitted.
	DockerHosts []string `json:"docker_hosts,omitempty"`
	// contains filtered or unexported fields
}

Middleware is an HTTP handler that triggers rolling Docker deployments via a webhook at /webhooks/rolling-deployment/{secret}/{container}/{image}.

Only Docker hosts where the named container is already running are updated. The previous container's configuration (env, labels, mounts, ports, networks, restart policy, and related create options) is preserved. Concurrent deploys of the same container name are rejected.

func (Middleware) CaddyModule

func (Middleware) CaddyModule() caddy.ModuleInfo

CaddyModule returns the Caddy module information.

func (*Middleware) Cleanup

func (m *Middleware) Cleanup() error

Cleanup implements caddy.CleanerUpper, closing all Docker clients.

func (*Middleware) Provision

func (m *Middleware) Provision(ctx caddy.Context) error

Provision implements caddy.Provisioner.

func (Middleware) ServeHTTP

func (m Middleware) ServeHTTP(w http.ResponseWriter, r *http.Request, next caddyhttp.Handler) error

ServeHTTP implements caddyhttp.MiddlewareHandler.

Only /webhooks/rolling-deployment/{secret}/{service_container}/{service_image} is handled here (terminal). All other requests are passed to the next handler.

func (*Middleware) UnmarshalCaddyfile

func (m *Middleware) UnmarshalCaddyfile(d *caddyfile.Dispenser) error

UnmarshalCaddyfile implements caddyfile.Unmarshaler.

func (*Middleware) Validate

func (m *Middleware) Validate() error

Validate implements caddy.Validator.

Directories

Path Synopsis
Package deploy performs rolling container deployments across one or more Docker hosts, using docker.Client instances for the underlying operations.
Package deploy performs rolling container deployments across one or more Docker hosts, using docker.Client instances for the underlying operations.
Package docker provides Docker Engine operations used by rolling deployments.
Package docker provides Docker Engine operations used by rolling deployments.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL