How to Deploy ReClip Using Docker: Complete Setup Guide

Deploy ReClip using Docker by building the official image from the repository's Dockerfile and exposing port 8899, which isolates all Python dependencies, ffmpeg, and yt-dlp in a secure containerized environment.

ReClip is a lightweight Flask-based video and audio downloader that bundles a Python backend with a static HTML/JS frontend. According to the averygan/reclip source code, deploying ReClip using Docker encapsulates all runtime dependencies—including Python 3.12, ffmpeg, and yt-dlp—into a lightweight container that runs under a non-root user for enhanced security.

Docker Architecture Overview

Core Components

The containerization strategy relies on three primary files in the repository root:

• Dockerfile: Defines the build process using python:3.12-slim, installs system dependencies like ffmpeg, creates a dedicated reclip user, and configures gunicorn to serve the Flask application on port 8899.
• docker-entrypoint.sh: A shell script executed at container startup that ensures the downloads directory exists and handles initialization tasks before launching the main process.
• docker-compose.yml: Provides a declarative configuration for local development, handling port mapping and volume persistence automatically.

Security and User Model

The Dockerfile implements security best practices by creating a non-root user (useradd -m -u 1000 reclip) and switching to it via the USER reclip instruction. This prevents the Flask application from running with elevated privileges. Additionally, the container prepends /home/reclip/.local/bin to the PATH environment variable, ensuring that any user-local Python package updates—such as yt-dlp—take precedence.

Step-by-Step Deployment Methods

Method 1: Build and Run Manually

For users who prefer direct Docker commands, the repository supports manual image building:

# Clone the repository

git clone https://github.com/averygan/reclip.git
cd reclip

# Build the Docker image

docker build -t reclip .

# Run the container in detached mode

docker run -d -p 8899:8899 --name reclip_instance reclip

Once the container starts, access the web interface at http://localhost:8899. The app.py Flask application handles all download requests and communicates with yt-dlp to fetch media.

Method 2: Deploy with Docker Compose (Recommended)

Docker Compose simplifies the deployment by automating build steps and persisting downloaded files to the host filesystem:

# Start the service with Compose

docker compose up -d

The docker-compose.yml configuration performs three critical functions:

1. Builds the image from the local Dockerfile if not already cached
2. Maps host port 8899 to container port 8899
3. Mounts ./downloads to /app/downloads inside the container, ensuring files survive container restarts

# docker-compose.yml structure

services:
  reclip:
    build: .
    ports:
      - "8899:8899"
    volumes:
      - ./downloads:/app/downloads

Maintaining and Updating the Container

Updating yt-dlp Without Rebuilding

Because the docker-entrypoint.sh script adds the user's local bin directory to PATH, you can update the downloader without rebuilding the image:

docker exec -it reclip_instance pip install -U yt-dlp

The updated binary becomes available immediately at /home/reclip/.local/bin/yt-dlp, and subsequent downloads use the latest version.

Managing the Downloads Volume

The bind mount specified in docker-compose.yml (./downloads:/app/downloads) ensures that all video and audio files are stored on the host filesystem at ./downloads. This persists data even if you remove the container with docker compose down.

Summary

• Deploy ReClip using Docker to isolate Python 3.12, ffmpeg, and yt-dlp dependencies from your host system.
• The Dockerfile uses python:3.12-slim as a minimal base and enforces security through a non-root reclip user (UID 1000).
• Use docker-entrypoint.sh to handle container initialization and ensure the downloads directory exists before starting gunicorn.
• Choose Docker Compose for development environments to automatically handle port mapping and persistent storage volumes.
• Update yt-dlp dynamically using docker exec commands without requiring image rebuilds.

Frequently Asked Questions

What port does ReClip use in Docker?

ReClip exposes port 8899 by default, as defined in the Dockerfile's EXPOSE 8899 instruction and mapped in docker-compose.yml. Access the web interface at http://localhost:8899 after starting the container.

How do I persist downloaded files when using Docker?

The docker-compose.yml file includes a volume mount that binds ./downloads on your host to /app/downloads in the container. This ensures all media files remain accessible on your host filesystem even after stopping or removing the container.

Can I update yt-dlp without rebuilding the Docker image?

Yes. Because the container's PATH includes /home/reclip/.local/bin, you can run docker exec -it <container_name> pip install -U yt-dlp to update the downloader dynamically. The docker-entrypoint.sh script ensures this path is prioritized for executable lookups.

Why does the ReClip Docker image use a non-root user?

The Dockerfile creates a dedicated reclip user with UID 1000 through useradd -m -u 1000 reclip and switches to it via USER reclip. This security best practice minimizes the attack surface by preventing the Flask application from running with root privileges inside the container.

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