# How to Deploy ReClip Using Docker: Complete Setup Guide

> Deploy ReClip using Docker with this complete setup guide. Build the official image, expose port 8899, and containerize dependencies for a secure, isolated environment.

- Repository: [Avery Gan/reclip](https://github.com/averygan/reclip)
- Tags: how-to-guide
- Published: 2026-09-05

---

**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`](https://github.com/averygan/reclip/blob/main/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`](https://github.com/averygan/reclip/blob/main/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:

```bash

# 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`](https://github.com/averygan/reclip/blob/main/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:

```bash

# Start the service with Compose

docker compose up -d

```

The [`docker-compose.yml`](https://github.com/averygan/reclip/blob/main/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

```yaml

# 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`](https://github.com/averygan/reclip/blob/main/docker-entrypoint.sh) script adds the user's local bin directory to `PATH`, you can update the downloader without rebuilding the image:

```bash
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`](https://github.com/averygan/reclip/blob/main/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`](https://github.com/averygan/reclip/blob/main/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`](https://github.com/averygan/reclip/blob/main/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`](https://github.com/averygan/reclip/blob/main/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`](https://github.com/averygan/reclip/blob/main/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.