feat(dev): add lite mode for control-plane-only local stack

[daryllimyt]

Summary

Adds a development-only lite profile that runs Tracecat's control plane only — Postgres, API, UI, Caddy — with no Temporal, Redis, MinIO, or worker/executor containers.

just cluster -p lite up -d

The full dev stack runs 16 services and takes ~27s to become healthy. Most control-plane work (auth, workspaces, secrets, settings, tables, RBAC, workflow CRUD and the graph editor, registry action listing, cases) needs none of the data plane. This makes that iteration loop cheap.

What actually blocked a data-plane-free boot

Exactly one thing: the five awaited ensure_bucket_exists calls plus configure_bucket_lifecycle in the API lifespan. Without MinIO they raise and the app never finishes startup. Everything else was already fire-and-forget or wrapped.

So the change is deliberately narrow: TRACECAT__LITE_MODE only skips startup work. It does not touch a single request-time code path.

Skipped at startup when the flag is on	Why
ensure_bucket_exists x5 + configure_bucket_lifecycle	Blob storage — the only hard boot blocker
add_temporal_search_attributes task	Temporal
start_case_trigger_consumer	Redis streams
start_case_duration_sync_consumer	Redis streams

Still runs, since all are Postgres-only: ensure_default_organization, setup_rbac_defaults, load_platform_catalog_on_startup, and the platform registry sync.

Explicitly not done

An earlier draft added a typed DataPlaneUnavailable exception, a 503 handler, fast-fail guards inside get_temporal_client / get_redis_client / _get_storage_client, and router-level dependencies. That was reverted: those are hot paths, and a dev-only convenience has no business reaching into them. config.py documents this so it does not creep back:

This flag is deliberately confined to startup. Request-time code paths are left untouched: calls that need a missing dependency simply fail as they already do when a service is down. Do not add guards to the client singletons or to request handlers on the strength of this flag.

The one property worth keeping from that draft is preserved with config instead of code. The Temporal client retries connects 10 times with exponential backoff capped at 120s — roughly six minutes of stalling per request against a Temporal that is not deployed. docker-compose.lite.yml sets TEMPORAL__CONNECT_RETRIES: 1 so it errors promptly.

Why a standalone compose file rather than an overlay or profiles

Neither alternative can cut the api -> temporal/minio/redis dependency edges:

• Overlay (-f a.yml -f b.yml): depends_on merges by union across files, so an overlay can add edges but never remove them.
• Native Compose profiles:: Compose auto-enables a profiled service when an active service depends_on it, which is the opposite of what is needed.

lite is wired in as a fourth profile in get_compose_file(), so logs, ps, db, attach, restart, and down all work unchanged. The sandbox overlay is skipped for this profile — it only patches executor/agent-executor, and layering it here declares services with neither an image nor a build context, which Compose rejects outright.

The stack reuses the core-db volume name, so a cluster slot's data carries over between -p dev and -p lite.

Verification

Booted for real (just cluster -p lite up -d):

• 4 containers; API startup complete 0.43s after the lite-mode log line
• /api/health 200 in 12ms; org, workspace, dev users, and default tier all seeded normally
• On a fresh database: 684 platform_registry_index rows with the version promoted, so action listing and the graph editor work
• ruff check / ruff format --check clean; basedpyright --warnings 0 errors, 0 warnings
• Unit suite green on the affected files (1039 passed)

Limitations

• Workflows cannot execute. Anything needing Temporal, Redis, or blob storage errors the same way it does when that service is down — ordinary 5xx, not a friendly response.
• Bumping the registry version against an existing lite database will not promote the new version, because promotion happens inside the artifact-build task which needs blob storage. The action listing keeps serving the previous version until the full stack is run once. Fresh installs are unaffected.
• TRACECAT__LITE_MODE is intentionally absent from .env.example and the other compose files. If it were present-and-false in a generated .env, ${TRACECAT__LITE_MODE:-true} in the lite compose would resolve to false and silently disable the profile.
• No deployments/fargate/ changes: this is a local development flag, not a deployment knob.

Review guide

• tracecat/api/app.py — the lifespan guard; the diff is mostly re-indentation of the existing block into an else:
• tracecat/config.py — the flag and the note on scope
• docker-compose.lite.yml — the five services
• scripts/cluster — lite profile, TRACECAT__LITE_MODE export ordering (must land after .env is sourced), seeding, ports output, sandbox-overlay skip

---

Summary by cubic

Adds a dev-only lite mode that runs the control plane only for faster local iteration. It skips data‑plane startup work, removes orphaned data‑plane containers on up, and keeps registry version promotion by skipping artifact build in lite.

• New Features

  • Added docker-compose.lite.yml with Postgres, API, UI, Caddy; no Temporal/Redis/MinIO/workers. Sets TEMPORAL__CONNECT_RETRIES=1 to fail fast.
  • Updated scripts/cluster with -p lite; exports TRACECAT__LITE_MODE=true, seeds by default, skips the sandbox overlay, updates port output, and adds --remove-orphans on up.
  • API lifespan checks config.TRACECAT__LITE_MODE and skips bucket provisioning/lifecycle, Temporal search attributes, and Redis consumers.
  • Registry sync skips artifact build in lite mode but still promotes the target version using a deterministic artifact_uri.

• Migration

  • Start with: just cluster -p lite up -d
  • Limitations: workflows do not run; anything needing Temporal, Redis, or blob storage will error as usual.

^{Written for commit 4bb0620. Summary will update on new commits.}

[zeropath-ai]

✅ No security or compliance issues detected. Reviewed everything up to 4bb0620.

Security Overview

• 🔎 Scanned files: 7 changed file(s)
• 🔗 Scan Link: https://zeropath.com/app/repositories/00dffd6c-8834-4dc9-b6d8-b44cd1622986?scanId=d487341a-9bc5-4758-8d03-f9bfd0a7fb86&codeScanTypes=PrScan&tab=issues

Detected Code Changes

Change Type

Relevant files

Enhancement

► docker-compose.lite.yml     Add Lite mode docker-compose for control plane only ► scripts/cluster     Support lite profile selection and behavior in cluster scripts ► tests/unit/test_config.py     Include docker-compose.lite.yml in expected files ► tracecat/api/app.py     Skip data-plane startup in lite mode; log and bypass Temporal/blob storage setup ► tracecat/config.py     Add TRACECAT__LITE_MODE config with documentation ► tracecat/registry/sync/jobs.py     Condition artifact build on lite mode; skip actual build in lite mode with URI generation

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: d0693eb602

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[daryllimyt]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

tracecat/tracecat/api/app.py

Lines 222 to 225 in fa88164

	registry_sync_task = asyncio.create_task(
	sync_platform_registry_on_startup(),
	name="platform_registry_sync",
	)

Skip registry artifact uploads in lite mode

When lite mode starts with a fresh registry or the current platform version, this unconditional startup sync schedules _build_platform_registry_artifact(), which calls blob.ensure_bucket_exists() and uploads to blob storage. Because docker-compose.lite.yml deliberately supplies neither MinIO nor a blob endpoint, the storage client falls back to AWS S3's default credential chain, so the supposedly control-plane-only stack still attempts external storage and may stall or fail in the background. Preserve the database/index portion of platform registry sync for action listing, but suppress its artifact build/upload while lite mode is enabled.

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[daryllimyt]

Re the second Codex finding (registry artifact upload attempted in lite mode, review body on fa88164): valid — every lite boot logged Platform registry artifact build failed | {'error': 'Unable to locate credentials'}, and on the upgrade path the swallowed failure would have left the promoted registry version stale.

Fixed in 4bb0620 with a startup-scoped guard in _build_platform_registry_artifact: lite mode skips the blob upload but still runs promotion, using the deterministic artifact URI (computed without I/O; nothing resolves it until workflow execution, which lite mode does not support).

Verified on a live lite cluster — the warning is gone, replaced by:

INFO  Skipping platform registry artifact build in lite mode | {'target_version': '1.0.0-beta.50'}
INFO  Promoted platform registry version after artifact build | {...}

Registry sync unit tests pass (42 passed).

@codex review

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. What shall we delve into next?

Reviewed commit: 4bb06207fd

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".