Self-hosted setup

Documentation

From zero to running in three commands. Deploy on Google Cloud, any Docker host, or locally.

Quick start

git clone https://github.com/captjay98/clearcut.git
cd clearcut
./clearcut start

Then open http://localhost:8000. The first user creates the organization and becomes Owner.

This starts a local PostgreSQL database, runs the one-shot migration service, and then starts the single clearcut runtime, which serves the public site, the /app workspace, and the /api endpoints from one process.

Requirements

DockerREQUIRED

Docker Compose v2+ for local development and single-server deployments.

PostgreSQL 15+REQUIRED

Stores users, organizations, scripts, evidence, decisions, and audit records. Included in docker compose.

Gemini API keyOPTIONAL

Enables detection, search planning, and evaluation. Disabled by default; the UI and API run without it and unresearched items stay unresolved.

Parallel API keyOPTIONAL

Enables live source retrieval with provenance. Disabled by default; enabling it requires an explicit cost acknowledgement.

Cloud StorageOPTIONAL

For script uploads and report exports. Local filesystem works for development and single-host installs.

FirebaseOPTIONAL

Validated as an optional identity boundary. Built-in server sessions are the default and the only wired mode.

Email providerOPTIONAL

SMTP or an API provider for invitations and notifications. In-app delivery works without email.

Configuration

Set environment variables for the clearcut runtime. Use a local .env file for development; never commit API keys to source control.

# Required
DATABASE_URL=postgresql+asyncpg://clearcut:change-me@postgres:5432/clearcut

# Deployment profile: local | portable | gcp
CLEARCUT_DEPLOYMENT_PROFILE=local

# Paid providers are disabled until acknowledged
CLEARCUT_PAID_PROVIDER_COST_ACKNOWLEDGED=false
GEMINI_API_KEY=
PARALLEL_API_KEY=

Enabling Gemini or Parallel requires both a credential and CLEARCUT_PAID_PROVIDER_COST_ACKNOWLEDGED=true, plus a positive per-provider concurrency limit. A missing or failing provider always becomes visible review work rather than invented evidence.

Architecture

One immutable image and its dependencies:

clearcut       → one image: Astro site + TanStack workspace + FastAPI

/            → public marketing site
/app/*       → authenticated workspace
/api/*       → application API
/api/internal→ protected service delivery

PostgreSQL     → evidence, decisions, audit trail
Object storage → scripts, snapshots, exports
Gemini         → detection, evaluation, judge (opt-in)
Parallel       → live source retrieval with provenance (opt-in)

The API is one modular monolith with bounded modules — not backend microservices. The migration job reuses the exact application image digest; application startup never migrates.

Roles

Five fixed roles, backend-enforced.

Role capabilities
Role	Capabilities
Owner	Organization lifecycle, protected settings, all governed review and report actions
Admin	Members, projects, providers, operational settings, governed review and report actions
Editor	Script import, research, assignments, comments, rewrite proposals
Reviewer	Evidence decisions, referrals, dispositions, rewrite approval, report generation and release
Viewer	Read-only access to authorized projects and released reports

Script formats

Accepted import formats
Format	Parser	Notes
Fountain	Deterministic	Plain-text screenplay syntax
FDX	Deterministic	Final Draft XML. DTDs and entities disabled.
Paste	Deterministic	Paste screenplay text directly.
PDF	Deterministic	Layout-aware extraction. Elements recovered from screenplay indentation. Encrypted files and pages without extractable text are reported, never inferred.

Deploy to Google Cloud

The GCP Starter profile uses:

Cloud Run One public `clearcut` service serving the site, workspace, and API from a single image.

Cloud SQL Managed PostgreSQL 15+ for evidence and audit, enabled with an explicit acknowledgement.

Cloud Storage Script artifacts, snapshots, and exports.

Secret Manager API keys and credentials.

Cloud Tasks Durable async work: detection, research, selective rescan, export.

Cloud Scheduler Scheduled reconciliation and recurring runs.

Infrastructure definitions live under infra/gcp/. They are unapplied controls: publishing them does not prove that cloud resources, hosted URLs, backups, or image digests exist. Cloud usage can incur charges.

Deploy to any Docker host

Run the clearcut image and PostgreSQL with persistent volumes.
Put a TLS-terminating reverse proxy in front of the service.
Leave storage on the local filesystem for a single host, or set an S3-compatible or GCS bucket for durability.
Provide a durable worker or queue so async jobs progress on their own.
Back up PostgreSQL and object storage regularly.

Updating

cd clearcut
git pull
docker compose build
docker compose up -d

Migrations run as an explicit one-shot service against the same image digest, never on application startup. Back up PostgreSQL before upgrading.