# The preflight check

GoRunner tests everything it depends on before it starts, and says in plain sentences what to fix.

It changes nothing it finds: a test table is rolled back, a test file is written and deleted, and the mail server is signed in to without sending.

- **The setup**: Before GoRunner starts. A problem stops the setup; a re-run puts `.env` back.
- **Every update**: The new version’s check, before anything changes.
- **Every container start**: A quick part: the settings, the key, and whether the stores answer.
- **Kubernetes**: In the migrations Job, before it applies anything.

## Run it yourself

**Docker**

```bash
docker compose run --rm check
```

**Kubernetes**

```bash
kubectl --namespace gorunner logs job/<its name> -c check
```

```text
✗ Database: 4 GoRunner processes with DB_MAX_CONNS=50 may open 202 connections; the server allows 197.
  Set DB_MAX_CONNS=47 in .env (or raise max_connections).
✓ Redis: 7.4.11, never deletes keys, saved to disk, wake-ups and sessions only. Runs, Storage and Queue data are in Postgres (Redis keeps a copy for rollback)
✓ Storage: none: step data stays in the database
✓ Mail: none. People sign in with a password
✓ Settings: role all, ENCRYPTION_KEY opens the stored keys
✓ Workflow steps: private networks blocked

1 problem to fix (45 ms). GoRunner will not work until it is fixed.
```

- **✓**: Fine: one line per part, listing what it found.
- **!**: Worth fixing, but GoRunner works.
- **✗**: GoRunner won’t work until it is fixed. The line under it says what to change.

The parts come in order: Database, Redis, Storage, Mail, then Company proxy and Workers when they apply, Settings, and Workflow steps.

## Options

- `--json`: One JSON object, each test with its status, message, fix, and the pool size it recommends.
- `--quick`: Only what a container checks as it starts.
- `--role api`: Check for another role than `GORUNNER_ROLE`: `all`, `api` or `worker`.
- `--timeout 60s`: The most the whole check may take. 60 seconds by default.
- `--context helm`: Name each fix as a Helm value, not a line of `.env`.

## What it tests

- **Settings**: Only known words in the mode lines, every line each choice needs, and an `ENCRYPTION_KEY` of the right shape that is this installation’s own.
- **Database**: PostgreSQL 15 or newer; can create tables and owns GoRunner’s; the extensions; enough connections, keeping 5 free; no pooler in transaction mode; the same version as this one, neither ahead nor behind (a worker server never applies migrations). Before an update, its line names the move, such as `schema 086 → 089`. Warns about tables that aren’t GoRunner’s, an `sslmode` that may fall back to no encryption, and `POSTGRES_HOST` set beside a whole address.
- **Redis**: 6.2 or newer; `noeviction`; not in cluster mode. Warns when it isn’t saved to disk, holds other keys, allows too few clients (`maxclients`), or the server doesn’t allow memory overcommit: run `sudo sysctl -w vm.overcommit_memory=1` and add it to `/etc/sysctl.d`.
- **Workers**: On an api server, warns until a worker has checked in.
- **Storage**: The bucket exists or can be made; a test file is written, read and deleted. Warns when a versioned bucket’s key may not delete versions (`s3:DeleteObjectVersion`).
- **Mail**: The server answers, its encryption works, the sign-in is accepted. Nothing is sent.
- **Company proxy**: Readable settings, and the proxy answers. Warns when it is asked for sites by name.
- **Workflow steps**: The [private networks](https://docs.gorunner.io/self-host/outbound-access) steps may reach.

## Exit statuses

- **0**: Nothing wrong. Warnings may be there.
- **1**: At least one problem.
- **2**: The command was wrong, such as an unknown option.
- **4**: A problem that protects data GoRunner already holds.

## Going past a problem

Sure it doesn’t matter? The setup and the update take `--skip-check`. The check still runs, and says how many problems it went past. On Kubernetes, `check.enabled: false` leaves them in the log.

```bash
./deploy.sh --skip-check v2026.10.24
```

Status 4 is never skipped. It means one of two things: file storage is switched off while step data still lives there, or `ENCRYPTION_KEY` isn’t this installation’s key. Switch storage back on, or put the right key back.

Related: [Install with Docker](https://docs.gorunner.io/self-host/install-docker) · [Update](https://docs.gorunner.io/self-host/update) · [Your own database, Redis and storage](https://docs.gorunner.io/self-host/own-stores) · [Troubleshooting](https://docs.gorunner.io/self-host/troubleshooting)

Source: https://docs.gorunner.io/self-host/preflight-check