Repository navigation
NAS hub
The NAS can run everything that has to stay up: clippa serve (the war room and
its jobs), the Discord bot and the worker, beside the recorder, with
transcription on Modal. The laptop can then sleep; it is only for
working on Clippa. This has been the setup here since 2026-11-05.
Container (deploy/hub) |
Runs | Notes |
|---|---|---|
serve |
clippa serve |
war room on 127.0.0.1:8765, hourly replan and upload, retakes, daily jobs |
bot |
clippa bot |
Discord; reaches serve on 127.0.0.1 |
worker |
clippa worker |
every stage of each finished recording; cuts locally (CLIPPA_CUT_BACKEND=local) |
tailscale |
tailscaled, userspace | serves the war room on the tailnet from tailscale-serve.json (Phone access) |
All four use host networking and their own compose project (clippa-hub, in ~/clippa-hub on the
NAS; clipper-hub before the rename's pass 3), so a deploy never restarts the recorder. The image is Debian 13 (ffmpeg 7.1) with Intel's media driver:
/dev/dri is passed in and h264_qsv encodes on the NAS iGPU, as on the laptop.
Claude Code can run beside them too, in its own container, so Clippa can be driven and changed from the Claude app on the phone: Claude on the NAS.
The NAS folder /volume1/docker/clipper (/data in the containers, the docker/clipper share
from the laptop) holds the one clipper.toml and everything [paths] points at, all relative
to it: streams/, schedule.json, secrets/, logs/, faces/, voices/, news/,
weekly/, photos/, archive/, layouts/, rumble/, people.json. Edit clipper.toml there
(back it up to backups/ first). Neither deploy script copies a config over it any more.
On the laptop, the user environment variable CLIPPER_CONFIG points at it
(//192.168.0.155/docker/clipper/clipper.toml); clipper also reads it from the registry when a
shell didn't inherit it, and ./clipper.toml still wins if there is one. Prompts come with the
code (clippa/prompts/, inside the package), the same on every machine.
schedule.json stores each video as <stream>/<folder>/<name>.mp4, relative to [paths] streams, so it means the same file on every machine. Older entries with a full path are mapped by
the part from the stream's folder on.
Covers, the weekly issue and Shorts captions want Impact, Bahnschrift, Georgia and Arial. Put
the .ttf files in the NAS folder's fonts/ (copied from C:\Windows\Fonts): the containers
mount it as /usr/local/share/fonts/clippa, where libass finds them by family and clipper
by file name (a font list's C:/Windows/Fonts/impact.ttf finds impact.ttf there).
clippa doctor names the font each check found.
bash deploy/hub/deploy.sh from the repo root (Git Bash on Windows; ssh alias nas) builds
the image from the checkout (code and prompts) and starts or updates all four. Deploy after
code changes: this replaces restarting serve or the bot. A stage or upload running at that
moment stops; the worker resumes the stream at its first unfinished stage, and an upload that
didn't finish goes again on the next hourly run. bash deploy/hub/deploy.sh bot updates one.
The compose project was clipper-hub (in ~/clipper-hub) until the rename's pass 3 (#286). The
first deploy after it builds the new image, then stops the old project (docker compose down:
its named volumes stay) and renames its compose.yaml to compose.yaml.retired-<date>, so
nothing can start it again beside the new one, and then starts all four in ~/clippa-hub.
deploy/record/deploy.sh and deploy/claude/deploy.sh do the same for clipper-record and
clipper-claude (deploy/retire.sh). The tailscale container keeps the old project's state
volume (clipper-hub_tailscale-state), so its sign-in and the war room's tailnet address stay.
Then set [serve] hub = "clippa-hub" in clipper.toml; until you do, clippa services finds
the live folder anyway (the old one until the deploy retires it) and clippa doctor warns.
The first run copies deploy/hub/env.template to deploy/hub/env.local (gitignored) and
stops: fill in the keys (ANTHROPIC_API_KEY, KITSU_TOKEN, MODAL_TOKEN_ID /
MODAL_TOKEN_SECRET from ~/.modal.toml, the alert webhook). The other keys are files in
secrets/. env.local is a copy: before each deploy, deploy/keys.sh compares its keys
(*_KEY, *_TOKEN, *_SECRET, *_WEBHOOK) with this machine's own of the same name (Windows
user variables, else the shell's environment), by name only, and stops on one that differs.
At a terminal it asks whether to copy this machine's values in; elsewhere set
DEPLOY_KEYS=sync to copy them or DEPLOY_KEYS=keep to deploy as is. A key rotated on the
laptop and not here would otherwise ship the old one, and every model call on the hub fails. There is no browser in the containers, so pre-shows use
a private copy of secrets/youtube_cookies.txt (CLIPPA_YOUTUBE_COOKIES_FROM_BROWSER is empty
there), which the laptop's clipper-cookies task copies from its Firefox profile every 4 hours
(clippa doctor warns when it's a day old)
(Archives). That one job ties the NAS to the
laptop: with the laptop off for days, signed-in pre-show grabs stop once the cookies rotate.
With [serve] hub = "clippa-hub", clippa services status|stop|restart serve|bot|worker
on the laptop runs docker compose on the NAS over ssh. Logs: logs/serve.log and
logs/bot.log in the NAS folder as before, plus ssh nas 'cd clippa-hub && docker compose logs -f serve'. Check a container with ssh nas 'cd clippa-hub && docker compose exec serve clippa doctor --role serve'.
Which code a container runs: clippa services status prints each service's version from its
heartbeat (0.2.0+3.g570bb87: the release, three commits past it, at 570bb87; .dirty when
the deploy came from a checkout with uncommitted changes) and this checkout's below it. A
service that shows a different commit than main's runs older code than the last merged PR
(Developing).
Warning
Only one serve and one bot may run. A laptop task and a NAS container don't see each
other's lock (Windows over SMB vs. the NAS's own disk), so keep the laptop's tasks disabled
(clipper-serve, clipper-bot, clipper-worker in Task Scheduler).
Stop the containers (ssh nas 'cd clippa-hub && docker compose stop serve bot worker'), set
[serve] hub = "", and enable the three scheduled tasks again (Roles and
services). The config and state stay on the NAS; the laptop reads them over
the share.
Home · Getting started · clippa doctor · These pages are built from docs/wiki/ in the repo, so edits made here are overwritten: how to edit them
Run it
- Overview
- Getting started
- Roles and services
- Configuration
- Pipeline
- Review
- Reviewing
- War room
- Clippa messenger
- Scheduling and uploads
- Costs
- Checkup
- Audit
- Backups
Install
- Install
- Install checklist
- Kitsu
- Discord app
- YouTube sign-in
- Windows
- macOS
- Transcribe on Modal
- NAS recorder
- NAS hub
- Claude on the NAS
- Phone access
- Model providers
- Adding a show
- YouTube channel
Features
- Pre-shows
- Fetching VODs
- Speakers
- Faces
- Covers
- Cast library
- B-roll
- Clip art
- Weekly issue
- X posts
- TikTok
- News watcher
- Character pieces
- Documentaries
Research
Working on Clippa