Install guide
Install OpenShorts with Docker, step by step
Four commands bring the stack up; the steps below cover what to change before the first real video — the env file, the GPU flags, and how to run the moment picker without a Google key.
Before you start
You need four things:
- Docker Engine with the Compose plugin (
docker compose versionshould answer). Docker Desktop on macOS and Windows is fine. - 8 GB of RAM or more, which is the project's own recommendation. Less will build and then die during transcription.
- Disk space for the images, the models and the clips. The Python side alone pulls a full torch build; the model downloads and
./outputsit on top of that. - A Google Gemini key, or a local model to point the pipeline at instead. Neither is needed to boot the stack — the dashboard comes up without either — but no clip gets selected without one. The API keys page covers the local-model route.
The four commands
git clone https://github.com/mutonby/openshorts.git
cd openshorts
cp .env.example .env
docker compose up --build
Then open http://localhost:5175. The build is the slow part and it only happens once per rebuild; after that docker compose up starts in seconds.
.env is optional in the sense that every key in .env.example has a working default except your own API keys and the S3 backup. Copy it anyway — it is the file every setting on this page goes into, and finding it empty later is more annoying than copying it now.
What the three containers are
docker compose up starts three services, and knowing which one is which is most of the debugging. The ports and volumes below are what docker-compose.yml actually declares:
| Container | Port on your machine → in the container | What it is |
|---|---|---|
openshorts-backend |
8000 → 8000 | The FastAPI app: job queue, the dashboard's API, and the /mcp endpoint |
openshorts-frontend |
5175 → 5173 | A Vite dev server serving the dashboard you look at |
openshorts-renderer |
3100 → 3100 | The Remotion render service that turns an edit into an MP4 |
The backend mounts the whole repository at /app, plus ./output at /app/output. The renderer mounts the same ./output at /output and is told to write there. Both restart unless you stop them. The frontend starts after the backend, because it has nothing to talk to until then.
That mapping explains the most common "it works for other people but not for me" report: the dashboard is on 5175 and the API is on 8000, and 5173 is only the port the frontend uses inside its container. If you put a reverse proxy in front, it points at 5175 for the UI and 8000 for anything programmatic.
What a healthy start looks like
docker compose ps— three containersUp, none flapping through restarts.docker compose logs -f backend— once Python is installed and the app boots, you get the uvicorn listening line for0.0.0.0:8000, and then a request line every time the dashboard polls. These are the logs to read when a job fails; the same tail is what/api/status/{job_id}returns.docker compose logs -f renderer— a short listening line on 3100, then silence. It stays idle until a job actually renders, so silence is health, not a crash.- The dashboard loading but hanging on every action means the backend is not up yet, not that the frontend is broken. Check 8000 first.
What the first run downloads
The image build installs the pinned Python stack into a venv — that is the several-gigabyte step, and it is the reason the first up --build takes minutes while later starts take seconds. By default it builds a CPU image: the Dockerfile takes torch from PyTorch's CPU index unless you pass GPU=1, which is what keeps a CPU-only machine from downloading a pile of CUDA wheels it will never use.
The transcription models are not in the image. They download the first time a job reaches the transcribe stage, into the container's /app/.cache/huggingface, so the first video is noticeably slower than the second. Mount that path as a named volume or a host directory if you plan to rebuild often — otherwise a rebuild throws the models away and the next job downloads them again. Which model you get is your choice:
| Setting | Effect |
|---|---|
WHISPER_MODEL |
base unless you set it — the fastest option; small is the file's own advice for non-English audio, large-v3-turbo for a GPU build |
WHISPER_DEVICE / WHISPER_COMPUTE |
cpu / int8 without a GPU; cuda / float16 with one |
TRANSCRIBE_BACKEND |
whisper or parakeet — Parakeet is GPU-image only and about twice as fast; it falls back to Whisper on errors or on languages outside its 25 European ones |
ASR_GPU_CONCURRENCY |
How many transcriptions run at once on the GPU; the file's own note says keep it at 1 unless there is VRAM to spare |
Turning the GPU on
The compose file does not request a GPU by default. To use one you build with GPU=1 so the CUDA build of the dependencies goes in, and you give the backend container the NVIDIA runtime (the deploy.resources.reservations.devices block, or --gpus all). Until both are done, the stack runs happily on CPU and every stage quietly stays there — an imported torch is not evidence that CUDA is in use, so check the transcription log rather than assuming.
Where the files land
Clips are written to ./output in the repository directory, and the renderer writes to the same folder from inside its container. That folder is a bind mount, not a volume, so the files are yours to move, back up or delete. It is also the folder that grows without being tidied: finished jobs leave the queue an hour after they finish, but nothing prunes the MP4s.
Upgrading and rolling back
Updating is a pull plus a rebuild:
git pull
docker compose up --build
Compose rebuilds the images that changed and recreates the containers that depend on them. What survives that: .env (a file on your host), ./output (a bind mount), and anything the backend writes into the repository directory, because .:/app maps that directory onto your disk rather than keeping it inside the container layer.
What does not survive: a job that is running when the containers are recreated. The worker process is killed and the job does not resume, so let the queue drain before you pull. Jobs that already finished are cleaned out of the queue an hour after completion, which is why an old job id can look "missing" without anything having gone wrong.
Rolling back is the same command with the code pointed at the older commit:
git checkout <previous-commit>
docker compose up --build
Back up .env and ./output first — a rollback is the one operation where losing the wrong file actually hurts. And if a change to docker-compose.yml (a port, a bind mount, an environment variable) seems to have no effect, add --force-recreate: compose is conservative about recreating containers whose config it thinks is unchanged.
Next steps
With the stack running, the API keys page gets a real clip out of it, the YouTube to Shorts walkthrough covers what a pasted link goes through stage by stage, and troubleshooting maps the nine failures that account for most of a first install. If you have not decided whether to self-host at all, self-hosted vs cloud runs the numbers instead.