Self-hosting

One docker compose up. Postgres for state, a local folder for everything the pipeline produces.

Requirements

Docker + Docker Compose (any machine that runs them — a Mac, a home server, a small VPS).
An OpenRouter API key (AI stages) and a free Pexels API key (slide photography).
For the TikTok integration: your own TikTok developer app — see the TikTok setup guide. Everything else works without it.

Quickstart

git clone https://github.com/ChrisLydic/montage-engine
cd montage-engine
cp .env.example .env        # add your OpenRouter + Pexels keys
docker compose up -d --build
# open http://localhost:8080 — migrations and theme seeding run on first boot

Create a project, write two lines of context, hit Generate ideas, and you're in the pipeline.

Environment reference

Variable	What it does
`OPENROUTER_API_KEY`	Required — all AI stages run through your OpenRouter account.
`PEXELS_API_KEY`	Required — photo search for slide imagery.
`MODEL_IDEAS` / `MODEL_SCRIPT` / `MODEL_DECK` / `MODEL_THEME` / `MODEL_VISION`	Optional per-stage model overrides (any OpenRouter slug).
`POSTGRES_PASSWORD`, `APP_PORT`	Infra basics.
`TIKTOK_CLIENT_KEY` / `TIKTOK_CLIENT_SECRET`	Your TikTok developer app credentials (sandbox credentials work for testing).
`TIKTOK_REDIRECT_URI`	Your registered OAuth callback — must be public HTTPS (TikTok rejects localhost for web apps).
`TIKTOK_PUBLIC_BASE_URL`	Public HTTPS base of your instance — TikTok fetches draft images from `/pub/…` here.
`TIKTOK_SCOPES`, `TIKTOK_POLL_HOURS`	Scope list override; metrics snapshot cadence (default 4h, with catch-up on boot).
`TUNNEL_TOKEN`	Cloudflare named-tunnel token for the optional `tunnel` compose profile.

Data & backups

Two things hold all state: the pgdata Docker volume (workflow, jobs, metrics) and the ./data folder (themes, deck JSON, rendered slides, image cache). Back both up and you can rebuild the stack anywhere.

Exposing your instance (for TikTok drafts)

Metrics and the whole creative pipeline run entirely locally. Sending drafts needs your instance reachable over public HTTPS, because TikTok's servers pull the slide images from it. The supported path is a Cloudflare named tunnel:

# .env: TUNNEL_TOKEN=…   (tunnel routes app.yourdomain.com → app:8080)
docker compose --profile tunnel up -d

Montage Engine has no login of its own — it assumes a trusted network. If you expose it through a tunnel, put an access layer in front (Cloudflare Access works well: allow your email, and add Bypass policies for /pub/* and /legal/*, which TikTok must reach unauthenticated).

Then work through the TikTok setup guide — developer app, domain verification, and what TikTok's review process expects.

Updating

git pull
docker compose up -d --build   # migrations run automatically on boot