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
- Caddy is part of the docker-compose stack, so it goes down with app
containers.
- There is no mechanism to show a user-friendly page during deployment
downtime.
- 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:
- Reads a user-provided HTML file and embeds it into the Caddyfile as
a handle_errors block responding to 502/503/504 errors.
- Removes
depends_on from the Caddy service in docker-compose so
Caddy can stay running while app containers restart.
- 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.
- 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();
Motivation
During deployment, catapulta runs
docker compose downwhich stops allcontainers including Caddy. Users visiting the site during this window
see a browser-level
ERR_CONNECTION_REFUSEDerror, which is a poorexperience.
Problems
containers.
downtime.
depends_on: service_healthyon Caddy prevents it from runningindependently of app containers.
Suggested solution
Add a
maintenance_page(html_path)method toCaddythat:a
handle_errorsblock responding to 502/503/504 errors.depends_onfrom the Caddy service in docker-compose soCaddy can stay running while app containers restart.
cmd_deploy, only stops app containers (docker compose rm -sf <apps>) instead ofdocker compose down, keeping Caddy aliveto serve the maintenance page.
reloads Caddy config so the maintenance page is active.
The HTML content is fully user-controlled, not hardcoded in catapulta.
Usage: