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

# Check bootstrap readiness

> Inspect the installed console's bootstrap configuration and dependencies without starting or changing the deployment.

Run `tuneplane-server preflight` before starting a newly installed console or investigating a
startup failure. It checks the installed server and its bootstrap environment without starting
the application, applying migrations, creating application data or probe files, pulling images, or changing database
records or Redis keys.

The command ships with `tuneplane-server`. An installed server environment or the console image
is enough; you do not need a source checkout, Node.js, or additional diagnostic tools.

## Run in the server's environment

Use the same environment variables, `.env`, working directory, mounted storage, user and groups
as the server process. Running it as root on the host can give a different answer from running
it as the console's service user inside its container.

For an installed server environment:

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
tuneplane-server preflight
tuneplane-server preflight --connect --timeout 5
tuneplane-server preflight --connect --json
```

For an existing [Docker Compose deployment](/en/ops/install-compose), run the installed
executable inside the `app` container:

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
docker compose exec -T app tuneplane-server preflight
docker compose exec -T app tuneplane-server preflight --connect --json
```

If the application is stopped, you can override its normal command with preflight using your
deployment's existing Compose configuration:

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
docker compose run --rm --no-deps --pull never app tuneplane-server preflight --connect --json
```

This starts a temporary diagnostic container, not the application or its dependencies. The image,
network and mounts must already be provisioned; PostgreSQL and any configured Redis service must
already be reachable for `--connect`. The shipped image has a `uvicorn` command and no entrypoint
that starts the application before this command. Preserve the deployment's environment, mounts
and service user when adapting the invocation to another container platform.

## Choose the check scope

| Option              | Behavior                                                                                                         |
| ------------------- | ---------------------------------------------------------------------------------------------------------------- |
| No options          | Check bootstrap configuration and local installed resources; make no network connections                         |
| `--connect`         | Also connect to PostgreSQL for read-only version and schema inspection, and send `PING` to Redis when configured |
| `--json`            | Write a structured report for an operator or automation                                                          |
| `--timeout SECONDS` | Set each network probe's deadline to an integer from 1 to 60 seconds; the default is 5                           |

The timeout applies separately to each network probe. It is not a deadline for the whole command
and cannot bound a filesystem call blocked on an unresponsive NFS mount. PostgreSQL and Redis
are probed separately, so their combined wait can be approximately twice the configured timeout.

Preflight checks **environment variables and dotenv bootstrap settings only**. It does not load
settings saved in the database or inspect registered Fleet configuration. Read
[configuration](/en/ops/configuration) when comparing this report with the console's effective
runtime settings.

## What the report checks

| Area                         | Evidence                                                                                      |
| ---------------------------- | --------------------------------------------------------------------------------------------- |
| Bootstrap configuration      | Whether the supplied settings can be loaded and validated                                     |
| Release compatibility        | Installed client, node and contract compatibility with the console's bundled release manifest |
| Authentication and secrets   | Configured authentication, durable JWT signing secret and credential encryption configuration |
| Installed assets             | Presence of the frontend index and bundled job runner                                         |
| Local storage                | Mount and permission metadata and reported free capacity, without creating a probe file       |
| PostgreSQL, with `--connect` | Connectivity, server version and schema revision relative to this installed release           |
| Redis, with `--connect`      | A `PING` response when Redis is configured                                                    |

Disabled authentication or an absent durable JWT secret fails preflight. Missing credential
encryption configuration produces a warning, or a failure when Hugging Face integration is
enabled. Runner presence does not verify its integrity or prove that it executes successfully.

A local storage check does not prove that an application can write successfully. It does not test
remote storage, credentials stored in the database, quotas enforced by a remote filesystem, or
restore behavior.

For PostgreSQL, detecting neither TunePlane core tables (`users` or `jobs`) nor a schema revision
produces a warning; preflight does not initialize the database. This does not establish that the
database contains no other tables. A recognized older schema revision produces a migration-pending
warning. An unknown revision, existing TunePlane core tables without a schema revision, or a schema
revision without those core tables fails the check. Preflight does not migrate these cases.
Revision inspection does not validate columns, indexes or data integrity; the report marks database
structure as `not_checked`. A successful revision inspection does not prove that an upgrade or
rollback is safe; follow your change procedure and verify a [backup and restore](/en/ops/backup).

## Interpret the result

The JSON report has `schema_version: 1`, `scope: "bootstrap"`, a top-level `status`, and a
`checks` array. Each check contains `id`, `status`, `message` and `remediation`. Check status is
one of `pass`, `fail`, `warning` or `not_checked`. Use the status fields for automation rather
than matching the English messages.

| Overall status         | Meaning                                                                                 |
| ---------------------- | --------------------------------------------------------------------------------------- |
| `blocked`              | At least one check failed; address its remediation before relying on this configuration |
| `incomplete`           | The report includes checks that were not performed                                      |
| `passed_with_warnings` | The performed checks passed, with conditions that need attention                        |
| `passed`               | Every check in the report passed                                                        |

Statuses take precedence in the order shown: a failure makes the report `blocked`; otherwise any
`not_checked` item makes it `incomplete`, even when warnings are also present. This version always
includes the runtime settings, storage acceptance and workload exclusions, so a report without
failures is `incomplete` with exit code 0.

| Exit code | Meaning                                                                  |
| --------- | ------------------------------------------------------------------------ |
| `0`       | No check failed; warnings and `not_checked` results may still be present |
| `1`       | At least one check failed                                                |
| `2`       | Invalid command usage, such as an out-of-range timeout                   |

**Exit code 0 is not a go-live approval.** Inspect each result and retain the report with your
deployment records. The report does not include raw exceptions, URLs, hostnames, filesystem paths
or secret values; its remediation names the setting or operator action to review.

## Complete deployment acceptance separately

The report marks these areas `not_checked`: registered Fleet health, worker-to-ingest reachability,
object storage, actual storage writes and restores, GPU execution, and offline readiness. Those
checks need the target infrastructure and a workload or operational drill.

After resolving bootstrap failures, validate the intended Fleet and data path with a representative
job. The [smoke test](/en/ops/smoke-test) describes the source-based CPU execution harness; it is a
separate end-to-end check. Verify GPU execution on the target hardware, exercise restoration from
backup, and follow the [air-gapped deployment](/en/ops/airgapped) procedure when outbound access is
unavailable.