Skip to content

Add maintenance page support during deployment #25

Description

@dannywillems

Motivation

During deployment, catapulta runs docker compose down which stops all
containers including Caddy. Users visiting the site during this window
see a browser-level ERR_CONNECTION_REFUSED error, which is a poor
experience.

Problems

  1. Caddy is part of the docker-compose stack, so it goes down with app
    containers.
  2. There is no mechanism to show a user-friendly page during deployment
    downtime.
  3. The depends_on: service_healthy on Caddy prevents it from running
    independently of app containers.

Suggested solution

Add a maintenance_page(html_path) method to Caddy that:

  1. Reads a user-provided HTML file and embeds it into the Caddyfile as
    a handle_errors block responding to 502/503/504 errors.
  2. Removes depends_on from the Caddy service in docker-compose so
    Caddy can stay running while app containers restart.
  3. During cmd_deploy, only stops app containers (docker compose rm -sf <apps>) instead of docker compose down, keeping Caddy alive
    to serve the maintenance page.
  4. Before stopping apps, updates the Caddyfile on the remote host and
    reloads Caddy config so the maintenance page is active.

The HTML content is fully user-controlled, not hardcoded in catapulta.

Usage:

let caddy = Caddy::new()
    .route("/api/*", api.upstream())
    .route("", web.upstream())
    .maintenance_page("deploy/maintenance.html")
    .gzip()
    .security_headers();

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions