Docker Deployment - copyparty

Overview

Copyparty is available in multiple Docker images with different feature sets. All images are available on both Docker Hub and GitHub Container Registry, supporting multiple architectures including x86_64, ARM, and more.

Quick Start

docker run --rm -it -u 1000 -p 3923:3923 -v /mnt/nas:/w -v $PWD/cfgdir:/cfg copyparty/ac

/w is the path inside the container that gets shared by default
/cfg is an optional folder with zero or more config files (*.conf) to load
copyparty/ac is the recommended image edition
If using rootless Podman, remove -u 1000
If you have SELinux, append :z to all -v args (e.g., -v /mnt/nas:/w:z)

Available Editions

Choose the edition that matches your requirements:

Edition	Size	Features	Best For
min	57 MiB (20 gz)	Just copyparty	Minimal installs
im	70 MiB (25 gz)	+ Pillow, Mutagen	Image thumbnails, music tags
ac	163 MiB (56 gz)	+ FFmpeg	Video/audio thumbnails, transcoding
iv	211 MiB (73 gz)	+ VIPS	Faster HEIF/AVIF/JXL thumbnails
dj	309 MiB (104 gz)	+ BPM/Key detection	DJ features

ac is recommended for most users as it provides the best balance of features and size.

Architecture Support

min, im, ac: x86, x86_64, armhf, aarch64, ppc64le, s390x
iv: x86, x86_64, armhf, aarch64
dj: x86_64, aarch64

Image Sources

# Docker Hub (default)
docker pull copyparty/ac

# GitHub Container Registry
docker pull ghcr.io/9001/copyparty-ac

Installation

Pull the image

docker pull copyparty/ac

Create configuration directory

mkdir -p ~/copyparty/config

Create configuration file

Create ~/copyparty/config/copyparty.conf:

[global]
  e2dsa  # enable file indexing
  e2ts   # enable multimedia indexing
  
  # Store database/thumbnails in config folder (recommended)
  hist: /cfg/hists/

[accounts]
  admin: your_password_here

[/]
  /w
  accs:
    r: *
    rwmda: admin
  flags:
    grid

Run the container

docker run -d \
  --name copyparty \
  -u 1000:1000 \
  -p 3923:3923 \
  -v /path/to/share:/w \
  -v ~/copyparty/config:/cfg \
  --restart unless-stopped \
  copyparty/ac

Replace /path/to/share with the actual directory you want to share.

Docker Compose

Recommended for easier management:

docker-compose.yml

version: '3.8'

services:
  copyparty:
    image: copyparty/ac
    container_name: copyparty
    user: "1000:1000"
    ports:
      - "3923:3923"
    volumes:
      - /path/to/share:/w
      - ./config:/cfg
    restart: unless-stopped
    environment:
      - TZ=America/New_York

Start with:

docker-compose up -d

For Podman with systemd, you may need to run systemctl enable --now podman.socket first.

Configuration

Volume Mapping

The container uses two primary mount points:

/w - The default web root (files to share)
/cfg - Configuration files directory

Multiple Shared Folders

docker run -d \
  --name copyparty \
  -p 3923:3923 \
  -v /mnt/music:/w/music \
  -v /mnt/videos:/w/videos \
  -v /mnt/documents:/w/docs \
  -v ~/copyparty/config:/cfg \
  copyparty/ac

Then configure in copyparty.conf:

[/music]
  /w/music
  accs:
    r: *

[/videos]
  /w/videos
  accs:
    r: *
    rw: admin

[/docs]
  /w/docs
  accs:
    rw: admin

Environment Variables

docker run -d \
  --name copyparty \
  -e TZ=America/New_York \
  -e PRTY_CONFIG=/cfg/custom.conf \
  -p 3923:3923 \
  -v /path/to/share:/w \
  -v ~/copyparty/config:/cfg \
  copyparty/ac

Command-Line Arguments

You can pass arguments directly instead of using config files:

docker run -d \
  --name copyparty \
  -p 3923:3923 \
  -v /path/to/share:/w \
  copyparty/ac \
  -v /w::rw \
  -a admin:password \
  -e2dsa -e2ts

Advanced Features

FTP Server

Enabling FTP in Docker requires additional configuration:

Update configuration

Add to copyparty.conf:

[global]
  ftp: 3921  # FTP port
  ftp-nat: 192.168.1.100  # Replace with your server's external IP
  ftp-pr: 12000-12099  # Passive mode port range

Do not add ftp-nat if using host networking (--network host).

Expose FTP ports

docker run -d \
  --name copyparty \
  -p 3923:3923 \
  -p 3921:3921 \
  -p 12000-12099:12000-12099 \
  -v /path/to/share:/w \
  -v ~/copyparty/config:/cfg \
  copyparty/ac

BPM and Musical Key Detection (DJ Edition)

The dj edition includes BPM and musical key detection:

copyparty.conf

[global]
  e2dsa, e2ts  # Enable indexing
  mtp: .bpm=f,t30,/mtag/audio-bpm.py  # ~10sec per file
  mtp: key=f,t190,/mtag/audio-key.py  # ~50sec per file

[/music]
  /w/music
  flags:
    e2dsa, e2ts
    mtp: .bpm=f,t30,/mtag/audio-bpm.py
    mtp: key=f,t190,/mtag/audio-key.py

Performance Optimization

Enable mimalloc for better performance (experimental):

docker run -d \
  --name copyparty \
  -e LD_PRELOAD=/usr/lib/libmimalloc-secure.so.2 \
  -p 3923:3923 \
  -v /path/to/share:/w \
  -v ~/copyparty/config:/cfg \
  copyparty/ac

Mimalloc doubles RAM usage but can make zip downloads 3x faster and indexing 1.5x faster.

Docker-Specific Recommendations

Store .hist in Config Folder

By default, copyparty creates a .hist folder in each volume for the database and thumbnails. Store these in the config folder instead:

[global]
  hist: /cfg/hists/

Benefits:

Better performance (especially with network storage)
Keeps shared folders clean
Easier backups

SELinux Systems

On Fedora, RHEL, CentOS with SELinux:

docker run -d \
  --name copyparty \
  -p 3923:3923 \
  -v /path/to/share:/w:z \
  -v ~/copyparty/config:/cfg:z \
  copyparty/ac

The :z flag relabels the content for container access.

Rootless Podman

When using rootless Podman, remove the -u flag:

podman run -d \
  --name copyparty \
  -p 3923:3923 \
  -v /path/to/share:/w \
  -v ~/copyparty/config:/cfg \
  copyparty/ac

Container Management

Start/Stop

# Start
docker start copyparty

# Stop
docker stop copyparty

# Restart
docker restart copyparty

# Remove
docker stop copyparty && docker rm copyparty

View Logs

# Follow logs
docker logs -f copyparty

# Last 100 lines
docker logs --tail 100 copyparty

Update Container

# Pull latest image
docker pull copyparty/ac

# Stop and remove old container
docker stop copyparty
docker rm copyparty

# Start new container with same configuration
docker run -d \
  --name copyparty \
  -p 3923:3923 \
  -v /path/to/share:/w \
  -v ~/copyparty/config:/cfg \
  copyparty/ac

With Docker Compose:

docker-compose pull
docker-compose up -d

Access Container Shell

# Alpine-based images use sh
docker exec -it copyparty sh

# Check copyparty version
docker exec copyparty copyparty --version

Portainer

For GUI-based container management, see the Portainer setup guide.

Troubleshooting

Debian 12 Rootless Error

Error: failed to register layer: lsetxattr user.overlay.impure /etc: operation not supported Solutions:

Use Podman instead of Docker (recommended)
Configure Docker to use fuse-overlayfs storage driver

Permission Denied

Ensure the user ID matches the file owner:

# Check file ownership
ls -la /path/to/share

# Run container with matching UID:GID
docker run -d -u 1000:1000 ...

Port Already in Use

# Check what's using the port
sudo lsof -i :3923

# Use a different port
docker run -d -p 8080:3923 ...

Cannot Access from Other Machines

Ensure the container binds to all interfaces:

# Explicitly bind to 0.0.0.0
docker run -d -p 0.0.0.0:3923:3923 ...

# Check firewall
sudo firewall-cmd --list-ports

Building Custom Images

From Source

# Clone repository
git clone https://github.com/9001/copyparty.git
cd copyparty/scripts/docker

# Build all images
./make.sh hclean pull img push

Adding Python Packages

To add packages without rebuilding from scratch:

FROM copyparty/ac:latest

RUN apk add --no-cache python3-dev gcc musl-dev && \
    pip install --no-cache-dir your-package-name && \
    apk del python3-dev gcc musl-dev

Build and run:

docker build -t copyparty-custom .
docker run -d --name copyparty -p 3923:3923 copyparty-custom

Next Steps

Reverse Proxy

Set up nginx or Apache

Security

Harden your Docker installation

Systemd

Native systemd service

Get Started

Core Features

Configuration

Deployment

Guides

​Overview

​Quick Start

​Available Editions

​Architecture Support

​Image Sources

​Installation

​Docker Compose

​Configuration

​Volume Mapping

​Multiple Shared Folders

​Environment Variables

​Command-Line Arguments

​Advanced Features

​FTP Server

​BPM and Musical Key Detection (DJ Edition)

​Performance Optimization

​Docker-Specific Recommendations

​Store .hist in Config Folder

​SELinux Systems

​Rootless Podman

​Container Management

​Start/Stop

​View Logs

​Update Container

​Access Container Shell

​Portainer

​Troubleshooting

​Debian 12 Rootless Error

​Permission Denied

​Port Already in Use

​Cannot Access from Other Machines

​Building Custom Images

​From Source

​Adding Python Packages

​Next Steps

Reverse Proxy

Security

Systemd

Build docs developers (and LLMs) love

Overview

Quick Start

Available Editions

Architecture Support

Image Sources

Installation

Docker Compose

Configuration

Volume Mapping

Multiple Shared Folders

Environment Variables

Command-Line Arguments

Advanced Features

FTP Server

BPM and Musical Key Detection (DJ Edition)

Performance Optimization

Docker-Specific Recommendations

Store .hist in Config Folder

SELinux Systems

Rootless Podman

Container Management

Start/Stop

View Logs

Update Container

Access Container Shell

Portainer

Troubleshooting

Debian 12 Rootless Error

Permission Denied

Port Already in Use

Cannot Access from Other Machines

Building Custom Images

From Source

Adding Python Packages

Next Steps