How to Run ReClip with Docker: Complete Setup Guide

ReClip runs as a lightweight Docker container exposing a Flask-based web interface on port 8899, with automatic yt-dlp updates and persistent download storage via Docker volumes.

ReClip is an open-source media extraction tool packaged as a Docker container for easy deployment. This guide walks you through running ReClip with Docker using either direct docker run commands or Docker Compose, based on the official averygan/reclip repository structure.

What the ReClip Docker Image Contains

The ReClip container is built from python:3.12-slim and includes three core runtime dependencies:

• ffmpeg – handles audio/video processing (installed via apt-get in the Dockerfile)
• yt-dlp – the media extraction engine that auto-updates on container start via docker-entrypoint.sh
• Flask – powers the HTTP API and single-page UI (installed from requirements.txt)

The image configures a non-privileged reclip user and prioritizes the user-local yt-dlp binary in PATH (Dockerfile lines 22-24). Port 8899 is exposed for web access.

Quick Start with Docker Compose (Recommended)

Docker Compose handles building, port mapping, and volume persistence automatically. The docker-compose.yml defines:

• Image build from local Dockerfile
• Port 8899:8899 mapping
• Named volume reclip-downloads mounted at /app/downloads

Run with a single command:

docker compose up -d

Access the UI at http://localhost:8899.

Running ReClip with Docker Run

For one-off deployments or custom configurations, build and run manually:

docker build -t reclip .
docker run -d -p 8899:8899 --name reclip \
  -v reclip-downloads:/app/downloads \
  reclip

This creates the reclip-downloads volume automatically on first run, ensuring downloaded files persist across container restarts.

Configuration Options

Disable Automatic yt-dlp Updates

Set RECLIP_NO_UPDATE=1 to skip the update check on startup:

docker run -d -p 8899:8899 -e RECLIP_NO_UPDATE=1 reclip

By default, docker-entrypoint.sh updates yt-dlp before handing off to Gunicorn.

Customize the Gunicorn Command

The entrypoint executes any command passed to the container. Override Gunicorn workers or binding:

docker run -d -p 8899:8899 \
  -v reclip-downloads:/app/downloads \
  reclip gunicorn --workers 4 --bind 0.0.0.0:8899 app:app

The default command runs app:app from app.py with standard Gunicorn settings.

Key Files Reference

File	Purpose
Dockerfile	Container definition: base image, ffmpeg, Python deps, user setup
docker-entrypoint.sh	Startup script: yt-dlp update, then exec command
docker-compose.yml	Convenience orchestration with volume persistence
requirements.txt	Python dependencies (Flask, yt-dlp)
app.py	Flask WSGI application serving UI and API

Troubleshooting

Container exits immediately: Check logs with docker logs reclip. Common causes include port conflicts or missing volume permissions.

Downloads disappear on restart: Verify the volume mount with docker volume ls and docker inspect reclip.

yt-dlp outdated: Remove RECLIP_NO_UPDATE=1 or manually restart the container to trigger an update.

Summary

• Docker Compose (docker compose up -d) is the fastest way to run ReClip with proper volume persistence
• Port 8899 serves the Flask UI; map it explicitly with -p 8899:8899
• Persistent storage requires mounting reclip-downloads:/app/downloads
• Auto-updates run on every start unless you set RECLIP_NO_UPDATE=1
• The non-root reclip user and Gunicorn WSGI server provide production-ready security

Frequently Asked Questions

What base image does ReClip use?

ReClip builds from the official python:3.12-slim image. This provides a minimal Python runtime while keeping the image size small. The Dockerfile layers on ffmpeg via apt-get and installs Python dependencies from requirements.txt.

How do I keep downloaded files after removing the container?

Mount the named volume reclip-downloads at /app/downloads as shown in the docker-compose.yml. Docker manages this volume independently of container lifecycle, so files persist even when you run docker rm reclip.

Can I run ReClip without automatic yt-dlp updates?

Yes. Set the environment variable RECLIP_NO_UPDATE=1 when starting the container. The docker-entrypoint.sh script checks this variable and skips the yt-dlp -U update command when present.

Why does ReClip use Gunicorn instead of Flask's development server?

Gunicorn provides a production-grade WSGI HTTP server with worker processes, request handling, and proper signal management. The Flask development server in app.py is only used for direct Python execution; Docker deployments use Gunicorn via the entrypoint script for reliability and performance.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}