> ## Documentation Index
> Fetch the complete documentation index at: https://sitectl.libops.io/llms.txt
> Use this file to discover all available pages before exploring further.

# healthcheck

> Check whether the active site is online and healthy.

export const Compose = () => <Tooltip headline="Compose" tip={<>
        Docker Compose is Docker's tool for defining and running multi-container applications.{" "}
        <a href="https://docs.docker.com/compose/">https://docs.docker.com/compose/</a>.
      </>}>
    <>
      <Icon icon="docker" />
      {" "}
      Compose
    </>
  </Tooltip>;

Use `healthcheck` for a basic status check of the running application. Core checks
confirm the <Compose /> 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

```bash theme={null}
sitectl healthcheck
```

## Common workflows

```bash theme={null}
# Check the active context
sitectl healthcheck

# Wait longer for a slow stack to come up
sitectl healthcheck --timeout 10m --interval 15s

# Render the report as a table
sitectl healthcheck --format table
```

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.