Skip to content
ChatGPT & LLMs

Deploy AI Short Film Stack [Docker Main Guide]

Install the AI short film production system from GitHub main: Docker Compose, COS keys, Ark/OpenRouter env, health check, and worker rebuild traps.

7 min readIntermediate

Most first boots of wushaojun321/ai-short-film die before a single frame renders. Not bad prompts – missing COS/Ark/OpenRouter secrets, a compose file still glued to V2Ray, or workers you restarted instead of rebuilt.

This is a deploy guide for that open-source stack from GitHub main. No release tags as of the 17 Jul 2026 tree; pin 3dc93a62bf472e46cb5edf2999971769a4989cab (3dc93a6) if you need a frozen commit. Browser UI walks screenplay → episode split → reviewed assets/storyboards → Seedance shots → merge.

What you’re actually installing

Not a local diffusion box. Generation rides OpenRouter for LLM planning and Volcano Engine Ark for Seedream stills plus Seedance video (README tech stack). Objects go to Tencent Cloud COS; the frontend uploads with STS temp credentials, not long-lived keys in the browser.

Four Celery queues: llm, image, video, merge. Shot continuity chains on each clip’s last_frame_url. Humans still gate assets and boards before video spend.

Think of compose as a small shipping yard: Mongo and Redis are the docks, workers are cranes with very different lift limits, and Ark is the freighter you never board. If one crane still points at a missing tugboat named v2ray, the whole quay looks “up” while nothing moves.

System requirements for AI short film Docker

Facts the repo actually states: Docker Engine + Compose, a Tencent COS bucket, OpenRouter API key, Volcano Ark API key; optional V2Ray when OpenRouter is blocked. Services on the graph – frontend (80/443), api, worker-llm (-c 2), worker-image (-c 20), worker-video (-c 10), worker-merge (-c 1), mongo:7 (host 27018), redis:7-alpine (host 6380), optional v2ray – come straight from docker-compose.yml / CODEBUDDY notes on main.

GPU on the host? Unused. Video is Ark-side. Give the box enough CPU/RAM headroom that twenty image workers and ten video workers are not thrashing the API process, outbound HTTPS to OpenRouter/Ark/COS, and disk for images plus the Mongo volume. Exact vCPU shopping lists change by provider; size from those concurrency knobs, not from a generic blog table.

If the host cannot reach OpenRouter, budget the proxy path. Ark image/video calls are written to skip the proxy inside the Python services; LLM traffic is what needs the tunnel.

Download the source (main, not a fantasy version tag)

git clone https://github.com/wushaojun321/ai-short-film.git
cd ai-short-film
# optional freeze (commit dated 2026-07-17):
git checkout 3dc93a62bf472e46cb5edf2999971769a4989cab

Official path is that repo only – skip random mirrors with the same name.

Install step by step

  1. cp backend/.env.example backend/.env and fill real secrets (next section).
  2. Proxy fork: cp v2ray/config.json.example v2ray/config.json and finish VMess or delete the v2ray service from docker-compose.yml and strip HTTP_PROXY/HTTPS_PROXY plus depends_on: v2ray from api, worker-llm, worker-image, and worker-video. Shipped YAML hard-wires http://v2ray:10801; README says remove that path when unused.
  3. COS console: CORS Allow-Origin for http://localhost or your public URL, methods GET/PUT/POST/HEAD, Allow-Headers *, Expose-Headers including ETag. Browser PUTs with STS fail without it – see Tencent COS CORS docs.
  4. docker compose up -d --build
  5. docker compose ps and docker compose logs -f api worker-llm

Pro tip: First boot with a half-empty v2ray/config.json is the quiet failure. API/workers inherit a dead proxy; OpenRouter times out; Mongo still looks healthy.

Expect frontend, api, four workers, mongodb, redis, and v2ray only if you kept it.

First-time configuration (.env that actually runs)

Smallest working shape from backend/.env.example on main (Ark model IDs drift – confirm in your Volcano console; strings below are the example file as of that 2026-07-17 main pin):

MONGODB_URL=mongodb://mongodb:27017/ai_short_film
REDIS_URL=redis://redis:6379/0

COS_SECRET_ID=AKIDxxxxxxxx
COS_SECRET_KEY=xxxxxxxx
COS_REGION=ap-guangzhou
COS_BUCKET=your-bucket-name-appid

OPENROUTER_API_KEY=sk-or-v1-...
OPENROUTER_BASE_URL=https://openrouter.ai/api/v1
OPENROUTER_MODEL=openai/gpt-5.5

ARK_API_KEY=ark-...
ARK_BASE_URL=https://ark.cn-beijing.volces.com/api/v3
ARK_IMAGE_MODEL=doubao-seedream-5-0-260128
ARK_VIDEO_MODEL=doubao-seedance-2-0-260128

Turns out README prose still mentions GPT-4o in places while the example file points at openai/gpt-5.5. Trust the file you copied, then point the model string at the OpenRouter route you actually pay for.

Env edit on a live stack: docker compose up -d --force-recreate api worker-llm worker-image worker-video worker-merge so processes reread secrets.

Verify the install works

Open http://localhost, register, create a project, paste a short screenplay.

docker compose exec -T api python - <<'PY'
import json, urllib.request
opener = urllib.request.build_opener(urllib.request.ProxyHandler({}))
with opener.open("http://127.0.0.1:8000/health", timeout=5) as r:
 print(json.loads(r.read().decode()))
PY
# expect status ok - same check scripts/update-server.sh uses

Or ./scripts/update-server.sh --health-only. docker compose logs worker-llm --tail 30 should show Celery ready on queue llm, not broker reconnect spam. Remember the dead-proxy trap above if health is fine but parse tasks never finish.

Before you hit approve on a full episode: do you really want image concurrency 20 and video concurrency 10 on day one, or are you about to learn Ark rate limits the expensive way?

Common install errors and fixes

  • API up, script parse stuck pending – worker-llm logs first. Missing OPENROUTER_API_KEY or proxy blackhole shows as task failure, not a red container.
  • Compose won’t start v2ray / workers crash-loop on proxy – finish VMess from the example or remove the proxy path in the install fork above.
  • Browser COS/CORS errors on upload – origin mismatch (including https vs http, or file://). Fix bucket CORS; STS is the design, not permanent browser keys.
  • Pulled new code, restarted, behavior unchanged – CODEBUDDY deploy note: code is baked into images; docker compose restart keeps old layers. docker compose build api worker-llm worker-image worker-video worker-merge && docker compose up -d.
  • Image/video jobs stampede the Ark bill – compose defaults worker-image -c 20, worker-video -c 10. Lower -c before approving a whole episode batch on a first test weekend.

Upgrade and uninstall

Upgrade the boring way when backend/.env already exists:

cd /path/to/ai-short-film
chmod +x scripts/update-server.sh
./scripts/update-server.sh
# partial: SERVICES='api worker-llm worker-video' ./scripts/update-server.sh
# env-only bounce: docker compose restart

Script blocks dirty trees unless ALLOW_DIRTY=1, fast-forward pull only, build, up, then /health.

docker compose down
docker compose down -v # drops mongo_data volume too
docker image prune -f # optional
rm -rf /path/to/ai-short-film

Rotate COS/OpenRouter/Ark keys on a shared host. Volume data survives until -v.

FAQ

Do I need a GPU to deploy this AI short film system?

No. Seedance/Seedream run on Ark. Your box is API, workers, Mongo, Redis, frontend.

Why does compose list V2Ray if the README calls it optional?

Optional in product language; default-on in the shipped YAML. On a clean path to OpenRouter, deleting the service and proxy env vars beats a dummy config. Keep V2Ray when the LLM endpoint is geo-blocked.

I only restarted api after a prompt change – why is behavior identical?

Prompt constants and Celery tasks live in the worker images, not only in api. Restarting api/frontend leaves the four workers on yesterday’s layers. Rebuild workers or run update-server.sh – same fix called out in the errors list, not a second architecture.

Next: fill backend/.env, settle the V2Ray fork for your network, docker compose up -d --build, confirm /health ok, then paste the first screenplay.

Related AI Tools