Skip to main content
Use healthcheck for a basic status check of the running application. Core checks confirm the service containers are running and healthy. If the context’s plugin registers a healthcheck handler, its runtime checks run too and are merged into the report. The command exits non-zero if any check still fails after the timeout, so it is safe to use in scripts and CI. Application plugins use shared helpers for common web stacks: route checks, MariaDB ping checks, optional HTTP service checks, and the expected depends_on: condition: service_healthy relationship between the app container and MariaDB. For route checks, plugins resolve the public URL from Traefik’s Compose command, file-provider mount, dynamic router config, TLS settings, and locally published ports. That keeps healthchecks aligned with ingress changes such as switching between http, https, https-letsencrypt, https-custom, and https-mkcert, publishing a new domain, or using a local override like 8080:80. Localhost-style URLs are tested from the host at the resolved public URL, so a failed route check points at the same URL an operator would open in a browser.

​
One-shot Services

A service does not have to remain running when its Compose contract is to finish once. Core treats an exited (0) container as healthy only when all of these facts are present in the effective docker compose config --format json output:
  • another defined service depends on it with condition: service_completed_successfully
  • that dependency is required (the default, or required: true)
  • the container state is exactly exited with exit code 0
This is how the application templates model database-init: the root credential exists only in the one-shot initializer, while the long-running app gets its scoped credential. Optional dependencies, ordinary jobs, missing containers, nonzero exits, and dead containers fail healthcheck. If core cannot read the effective Compose model, it fails closed instead of assuming an exited job was successful. Containers created by an ad hoc docker compose run are Compose one-offs rather than project services and are not included in the full project health report.

​
Reference

Check whether the active site is online. Core checks verify Docker Compose service containers are running and healthy. If the active context’s plugin registers a healthcheck handler, plugin-specific runtime checks are also run and merged into the report. All flags not consumed by sitectl itself are forwarded to the plugin’s healthcheck handler, allowing plugin-specific flags such as --codebase-rootfs. By default, healthcheck waits for Docker services that are still starting, then prints one status report and exits non-zero if any check fails. Use --persist to keep retrying all failures until every check passes or --timeout is reached. Examples: sitectl healthcheck sitectl healthcheck --persist --timeout 10m --interval 15s sitectl healthcheck --format table

​
Common workflows

Flags that core does not consume are forwarded to the plugin’s healthcheck handler, so plugin-specific flags such as --codebase-rootfs work here too.