How to Self-Host Paperclip on a VPS (2026 Step-by-Step Guide)

How to Self-Host Paperclip on a VPS (2026 Step-by-Step Guide)

Paperclip is one of the cleanest self-hosted document management systems available. It runs as a single Docker container, stores files on a local volume, and exposes a web UI on port 8080. This guide walks you through a complete production-ready installation on a Linux VPS — from provisioning the server to your first document upload.

Prerequisites

• A VPS running Ubuntu 22.04 LTS or Debian 12 (recommended)
• At least 1 vCPU, 1GB RAM, 20GB storage (2GB RAM recommended for OCR)
• Root or sudo access via SSH
• A domain or subdomain pointed to your VPS IP (optional but recommended for HTTPS)

Recommended VPS options:

• Hetzner Cloud CX22 — €4.15/mo, 2 vCPU, 4GB RAM, 40GB NVMe
• Contabo VPS S — €5.99/mo, 4 vCPU, 8GB RAM, 200GB NVMe

Step 1: Update Your Server

apt update && apt upgrade -y

Step 2: Install Docker

curl -fsSL https://get.docker.com | sh
systemctl enable docker
systemctl start docker

Verify Docker is running:

docker --version

Step 3: Install Docker Compose

apt install docker-compose-plugin -y
docker compose version

Step 4: Create a Working Directory

mkdir -p /opt/paperclip && cd /opt/paperclip

Step 5: Create a docker-compose.yml

nano /opt/paperclip/docker-compose.yml

Paste the following configuration:

version: "3.8"

services:
  paperclip:
    image: paperclip/paperclip:latest
    container_name: paperclip
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - paperclip_data:/data
    environment:
      - PAPERCLIP_SECRET_KEY=change_this_to_a_random_secret
      - PAPERCLIP_OCR_ENABLED=true
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 30s
      timeout: 10s
      retries: 3

volumes:
  paperclip_data:

Important: Replace change_this_to_a_random_secret with a random string. Generate one with:

openssl rand -hex 32

Step 6: (Optional) Use PostgreSQL Instead of SQLite

For multi-user or production use, extend the compose file:

version: "3.8"

services:
  db:
    image: postgres:16-alpine
    container_name: paperclip_db
    restart: unless-stopped
    environment:
      POSTGRES_DB: paperclip
      POSTGRES_USER: paperclip
      POSTGRES_PASSWORD: strongpassword
    volumes:
      - pg_data:/var/lib/postgresql/data

  paperclip:
    image: paperclip/paperclip:latest
    container_name: paperclip
    restart: unless-stopped
    depends_on:
      - db
    ports:
      - "8080:8080"
    volumes:
      - paperclip_data:/data
    environment:
      - PAPERCLIP_SECRET_KEY=your_random_secret
      - PAPERCLIP_DB_HOST=db
      - PAPERCLIP_DB_NAME=paperclip
      - PAPERCLIP_DB_USER=paperclip
      - PAPERCLIP_DB_PASSWORD=strongpassword
      - PAPERCLIP_OCR_ENABLED=true

volumes:
  paperclip_data:
  pg_data:

Step 7: Start Paperclip

cd /opt/paperclip
docker compose up -d

Check that the container started:

docker compose ps
docker compose logs -f paperclip

Step 8: Configure a Firewall

ufw allow OpenSSH
ufw allow 80
ufw allow 443
ufw enable

Note: Port 8080 is intentionally not exposed directly — we’ll proxy through Caddy/Nginx with HTTPS.

Step 9: Set Up HTTPS with Caddy

apt install caddy -y

Edit the Caddyfile:

nano /etc/caddy/Caddyfile

docs.yourdomain.com {
    reverse_proxy localhost:8080
}

Reload Caddy:

systemctl reload caddy

Caddy automatically provisions a Let’s Encrypt certificate.

Step 10: First Login

1. Open https://docs.yourdomain.com (or http://YOUR_VPS_IP:8080 if no domain)
2. Complete the initial setup wizard — set your admin email and password
3. Upload your first document
4. Enable OCR if you need full-text search on scanned files

Step 11: Set Up Backups

Back up the Docker volume to your local machine or an S3-compatible bucket:

# Backup to local file
docker run --rm \
  -v paperclip_data:/data \
  -v $(pwd):/backup \
  alpine tar czf /backup/paperclip-backup-$(date +%Y%m%d).tar.gz /data

Schedule this with a cron job:

crontab -e
# Add:
0 3 * * * /opt/paperclip/backup.sh

Troubleshooting

For VPS provider recommendations, see the best VPS for Paperclip or the full VPS comparison.