Deploying copyparty

Introduction

copyparty is a portable, self-hosted file server that provides comprehensive file sharing capabilities through a modern web interface. Written in Python with minimal dependencies, copyparty offers a lightweight alternative to heavier file sharing solutions while still providing powerful features like resumable uploads, media streaming, and multiple access protocols.

What sets copyparty apart is its focus on simplicity and portability. It runs as a single Python script, requires no database, and stores all configuration in simple text files. Despite its lightweight nature, copyparty supports advanced features including deduplication, file indexing, and integration with external tools for media processing.

Key highlights of copyparty:

• Portable Design: Single Python script with minimal dependencies
• Web Interface: Modern, responsive file browser with drag-and-drop uploads
• Multiple Protocols: HTTP, WebDAV, and FTP access in one package
• Resumable Uploads: Handle large file uploads that survive connection interruptions
• Media Streaming: Stream audio and video files directly in the browser
• Deduplication: Optional content-based deduplication saves storage space
• File Indexing: Full-text search through indexed documents
• Thumbnail Generation: Automatic thumbnails for images and videos
• Access Control: Fine-grained permissions per user and folder
• No Database: File-based configuration and metadata storage
• 100% Open Source: MIT licensed with active development

This guide walks through deploying copyparty on Klutch.sh, configuring file shares, and setting up secure access for your team.

Why Deploy copyparty on Klutch.sh

Deploying copyparty on Klutch.sh provides several advantages for file sharing:

Simplified Deployment: Klutch.sh handles container orchestration, letting you focus on organizing your file shares.

Persistent Storage: Attach volumes for your files that persist across container restarts and updates.

HTTPS by Default: Automatic SSL certificates ensure secure file transfers without configuration.

GitHub Integration: Connect your configuration repository for automated deployments.

Custom Domains: Use your own domain for professional file sharing URLs.

Scalable Resources: Allocate CPU and memory based on your file sharing needs and user count.

Always-On Availability: Your file server remains accessible 24/7 from anywhere.

Prerequisites

Before deploying copyparty on Klutch.sh, ensure you have:

• A Klutch.sh account
• A GitHub account with a repository for your configuration
• Basic familiarity with file servers and access control concepts
• A plan for organizing your file structure and access permissions
• (Optional) A custom domain for your file server

Understanding copyparty Architecture

copyparty uses a straightforward architecture:

Python Server: The core application is a Python HTTP server handling all requests and file operations.

File-Based Storage: All files, metadata, and configuration are stored on the file system without requiring a database.

Protocol Handlers: Built-in handlers for HTTP, WebDAV, and FTP provide multiple access methods.

Optional Indexer: The indexing system creates searchable catalogs of file contents and metadata.

Media Processors: Integration with FFmpeg and other tools enables thumbnail generation and media streaming.

Preparing Your Repository

Create a GitHub repository with your copyparty configuration.

Repository Structure

copyparty-deploy/
├── Dockerfile
├── config/
│   └── config.json
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile for your copyparty deployment:

FROM python:3.11-slim

# Install system dependencies
RUN apt-get update && apt-get install -y \
    ffmpeg \
    imagemagick \
    && rm -rf /var/lib/apt/lists/*

# Install copyparty
RUN pip install --no-cache-dir copyparty

# Create directories
RUN mkdir -p /data /config

# Copy configuration
COPY config/ /config/

# Create data directories
RUN mkdir -p /data/public /data/private /data/uploads

# Expose ports
EXPOSE 3923

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=10s --retries=3 \
    CMD curl -f http://localhost:3923/ || exit 1

# Set environment variables
ENV CPP_ARGS=""

# Start copyparty
CMD python -m copyparty \
    --http-port 3923 \
    --bind 0.0.0.0 \
    -c /config/config.json \
    $CPP_ARGS

Creating Configuration File

Create config/config.json with your copyparty settings:

{
  "acct": {
    "admin": {
      "pw": "CHANGE_THIS_PASSWORD",
      "admin": true
    },
    "user": {
      "pw": "user_password",
      "admin": false
    }
  },
  "vol": {
    "/data/public": {
      "flags": ["r"],
      "name": "Public Files"
    },
    "/data/private": {
      "flags": ["rwmd"],
      "accs": ["admin"],
      "name": "Private Files"
    },
    "/data/uploads": {
      "flags": ["rwm"],
      "accs": ["admin", "user"],
      "name": "Uploads"
    }
  },
  "args": {
    "e2ds": true,
    "e2dsa": true,
    "no-thumb": false,
    "th-size": 256
  }
}

Permission Flags Reference

copyparty uses single-letter permission flags:

Flag	Description
r	Read (download files)
w	Write (upload new files)
m	Move/rename files
d	Delete files
g	Get (list directory contents)
a	Admin (manage server)

Creating the .dockerignore File

Create a .dockerignore file:

.git
.github
*.md
LICENSE
.gitignore
.DS_Store

Deploying copyparty on Klutch.sh

Follow these steps to deploy your copyparty file server:

Configure Your Accounts

Update config/config.json with secure passwords for all accounts. Never use default passwords in production.

Define Your Volumes

Plan your file share structure in the configuration:

• Public shares for open access
• Private shares for authenticated users
• Upload areas for receiving files

Push Your Repository to GitHub

Initialize and push your configuration:

git init
git add .
git commit -m "Initial copyparty configuration"
git remote add origin https://github.com/yourusername/copyparty-deploy.git
git push -u origin main

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project for your file server.

Create a New App

Create a new app within your project and connect your GitHub repository.

Configure HTTP Traffic

In the deployment settings:

• Select HTTP as the traffic type
• Set the internal port to 3923 (copyparty default)

Attach Persistent Volumes

Add persistent volumes for your file storage:

Mount Path	Recommended Size	Purpose
/data	Variable	All shared files and uploads
/config	100 MB	Configuration and metadata

Size your data volume according to your storage needs.

Deploy Your Application

Click Deploy to build and start copyparty. Klutch.sh will:

• Build the container with copyparty
• Mount persistent volumes
• Start the file server
• Provision an HTTPS certificate

Access copyparty

Once deployed, access your file server at https://your-app-name.klutch.sh. Log in with your configured credentials.

Managing Files and Shares

Web Interface

The web interface provides:

• File Browser: Navigate directories with a clean, modern interface
• Drag-and-Drop Upload: Drop files anywhere to upload
• Preview: View images, play audio/video, and preview documents
• Search: Find files by name or content
• Bulk Operations: Select multiple files for download or deletion

Creating Share Links

Generate shareable links for files or folders:

1. Right-click the file or folder
2. Select “Copy Link” or “Share”
3. Choose link options (read-only, password, expiration)
4. Share the generated URL

Organizing Files

Best practices for file organization:

/data/
├── public/          # Publicly accessible files
│   ├── documents/
│   └── media/
├── private/         # Admin-only files
│   └── confidential/
├── uploads/         # User upload area
│   ├── pending/
│   └── processed/
└── archives/        # Long-term storage

User Management

Adding Users

Add users through the configuration file:

{
  "acct": {
    "newuser": {
      "pw": "secure_password",
      "admin": false
    }
  }
}

Per-Volume Access

Control access per volume:

{
  "vol": {
    "/data/team-a": {
      "flags": ["rwmd"],
      "accs": ["admin", "team-a-lead", "team-a-member"]
    },
    "/data/team-b": {
      "flags": ["rwmd"],
      "accs": ["admin", "team-b-lead"]
    }
  }
}

Anonymous Access

Allow anonymous access to public shares:

{
  "vol": {
    "/data/public": {
      "flags": ["r"],
      "accs": ["*"]
    }
  }
}

Advanced Features

Deduplication

Enable content-based deduplication to save space:

{
  "args": {
    "e2ds": true,
    "e2dsa": true
  }
}

This creates hard links for duplicate files rather than storing multiple copies.

Thumbnail Generation

Configure thumbnail settings:

{
  "args": {
    "no-thumb": false,
    "th-size": 256,
    "th-convt": "jpg"
  }
}

Requires FFmpeg for video thumbnails.

Full-Text Search

Enable document indexing for search:

{
  "args": {
    "e2t": true,
    "e2ts": "*.txt,*.md,*.pdf,*.doc,*.docx"
  }
}

Upload Processing

Configure upload behavior:

{
  "args": {
    "dup": "rename",
    "ah": true
  }
}

Options for duplicate handling:

Value	Behavior
reject	Reject duplicate uploads
rename	Rename duplicates with suffix
replace	Replace existing files

WebDAV Access

copyparty includes WebDAV support for desktop integration:

Connecting from Windows

1. Open File Explorer
2. Right-click “This PC” and select “Map network drive”
3. Enter: https://your-app-name.klutch.sh/dav/
4. Enter your username and password

Connecting from macOS

1. Open Finder
2. Press Cmd+K or Go > Connect to Server
3. Enter: https://your-app-name.klutch.sh/dav/
4. Enter your credentials

Connecting from Linux

Mount WebDAV shares with davfs2:

sudo mount -t davfs https://your-app-name.klutch.sh/dav/ /mnt/copyparty

Production Best Practices

Security Recommendations

• Strong Passwords: Use unique, complex passwords for all accounts
• Limited Admin Access: Only grant admin access when necessary
• Regular Audits: Review access logs and permissions periodically
• File Type Restrictions: Limit uploadable file types if appropriate

Performance Optimization

• SSD Storage: Use SSD-backed volumes for better performance
• Adequate Resources: Allocate sufficient CPU for thumbnail generation
• Caching: Enable browser caching for static assets

Backup Strategy

Regular backups should include:

1. All files in /data
2. Configuration in /config
3. Index databases if using full-text search

Troubleshooting Common Issues

Upload Failures

Symptoms: Uploads fail or timeout.

Solutions:

• Check available storage space
• Verify user has write permission
• Increase timeout settings
• Check maximum file size limits

Slow Performance

Symptoms: Interface feels sluggish.

Solutions:

• Increase container resources
• Disable thumbnail generation for large directories
• Reduce the number of items displayed per page

Permission Denied

Symptoms: Cannot access certain files or directories.

Solutions:

• Verify user is in the access list for the volume
• Check permission flags include needed access
• Ensure correct volume configuration syntax

WebDAV Connection Issues

Symptoms: Cannot connect via WebDAV.

Solutions:

• Verify the WebDAV URL includes /dav/ suffix
• Check client supports HTTPS WebDAV
• Confirm credentials are correct

Additional Resources

• copyparty GitHub Repository
• copyparty Documentation
• Configuration Examples
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying copyparty on Klutch.sh gives you a lightweight, versatile file server with a modern web interface and multiple access protocols. The combination of copyparty’s minimal resource requirements and Klutch.sh’s container management means you get powerful file sharing capabilities without infrastructure complexity.

With support for resumable uploads, media streaming, WebDAV access, and fine-grained permissions, copyparty handles everything from simple file sharing to complex team collaboration. Whether you’re sharing documents with clients, distributing media files, or setting up a team file repository, copyparty on Klutch.sh provides reliable, accessible file sharing from anywhere.