Startup requirements

Some settings are not optional. If the environment does not supply them, TT-NN Visualizer refuses to start rather than serving with the property they guarantee missing. This page lists those conditions, and shows how to check an environment against a release before deploying it.

Everything here concerns values an operator provides. Requirements marked Hosted apply only when SERVER_MODE is enabled; a local install runs on the development defaults and is unaffected.

Check an environment before you deploy

ttnn-visualizer --check-config

For a hosted deployment, check the posture it will actually run in:

SERVER_MODE=true ttnn-visualizer --check-config

It reads the same environment the server would, evaluates every requirement, prints each one’s status, and exits without starting anything:

Exit code	Meaning
0	This release’s startup requirements are satisfied. It will start here.
non-zero	It will not start here. The output names each unmet requirement and what to set.

Run this against the target environment as a deploy step, before the running service is replaced. That is the difference between a failed preflight and a restart loop with no service behind it.

ttnn-visualizer 0.102.0 startup requirements
Posture: hosted (SERVER_MODE enabled)

  ❌ hosted-secret-key: SERVER_MODE requires SECRET_KEY to contain at least 8 bytes excluding surrounding whitespace, and not use the development default
      Set: SECRET_KEY
      Set SECRET_KEY to a stable random value, the same one on every worker: python3 -c 'import secrets; print(secrets.token_urlsafe(48))'

❌ 1 unmet requirement(s). This release will NOT start in this environment.

Satisfied requirements are printed too, so the output is evidence of what was checked rather than only of what broke.

Current requirements

Requirement	Environment variables	Condition	Introduced in	Enforced from	Posture
hosted-secret-key	SECRET_KEY	Under SERVER_MODE, SECRET_KEY must be non-default and at least 8 bytes excluding surrounding whitespace.	0.102.0	0.102.0	Hosted

The byte floor is a floor against an obviously-short key, not a strength check — it counts UTF-8 bytes rather than entropy. Supply a long random value regardless of the number. What makes the signed session cookie an integrity boundary across workers and restarts is that the key is stable and non-default.

Surrounding whitespace does not count toward the floor, and is not removed either. The value as configured is what signs the cookie, so a key accepted with padding keeps that padding in its signature — tidying it out later rotates the key and drops every session.

How a new requirement is introduced

A requirement’s Enforced from release is the one it becomes fatal in. Before that release, an environment that does not satisfy it still starts and logs a warning on every boot:

Startup requirement 'example' is not satisfied: ... This becomes a startup failure in
0.105.0. Set EXAMPLE to ...

That gap is deliberate. A value like SECRET_KEY is provisioned outside this repository, often by a different team, so a requirement that is fatal the moment it ships is not satisfiable at upgrade time — the operator finds out when the service stops. --check-config reports staged requirements as warnings and still exits 0, so you can find them on the release before they matter.

Maintainers: the rollout convention, and why the repository’s test suite cannot catch this class of change on its own, are in CONVENTIONS.md.

If startup already failed

A refused start prints every unmet requirement and exits; under gunicorn each worker raises at import and the arbiter reports Worker failed to boot. Run ttnn-visualizer --check-config in the same environment to see which condition is unmet without waiting on a restart loop.

Settings that cannot be parsed — a SERVER_MODE that is not a recognised boolean, a MAX_CONTENT_LENGTH that is not a byte count — fail earlier than these checks, with their own message on stderr. --check-config still exits non-zero for them, so a deploy gate reading the exit code needs no special case.