← All articles

Why Docker Compose for Paperclip

Docker Compose gives you reproducible, portable deployments. The same docker-compose.yml works on your local Mac, a Ubuntu VPS, or a Raspberry Pi. It handles service restarts, volume persistence, and networking — all defined in a single file.

Prerequisites

• Docker and Docker Compose installed
• A server with at least 1 GB RAM (2 GB recommended)

Install Docker:

# Ubuntu/Debian
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
newgrp docker

# Verify
docker --version
docker compose version

Step 1: Create the project directory

mkdir paperclip && cd paperclip

Step 2: Write the docker-compose.yml

services:
  paperclip:
    image: node:20-alpine
    container_name: paperclip
    restart: unless-stopped
    working_dir: /app
    command: sh -c "npm install -g paperclipai && npx paperclipai server start --port 3100 --host 0.0.0.0"
    environment:
      - NODE_ENV=production
      - PAPERCLIP_DATA_DIR=/data
      - BETTER_AUTH_SECRET=${BETTER_AUTH_SECRET}
      - PAPERCLIP_LISTEN_PORT=3100
      - PAPERCLIP_LISTEN_HOST=0.0.0.0
    volumes:
      - paperclip_data:/data
    ports:
      - "127.0.0.1:3100:3100"
    healthcheck:
      test: ["CMD", "wget", "-qO-", "http://localhost:3100/api/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 60s

volumes:
  paperclip_data:
    driver: local

Step 3: Create the .env file

cat > .env << EOF
BETTER_AUTH_SECRET=$(openssl rand -hex 32)
EOF
chmod 600 .env

Never commit .env to version control. Add it to .gitignore.

Step 4: Start Paperclip

docker compose up -d

Check logs:

docker compose logs -f paperclip

Wait for Paperclip to finish starting (30–60 seconds on first run while npm installs).

Step 5: Access locally

If you're running this on your local machine:

http://localhost:3100

Complete the setup wizard to create your admin account.

Step 6: nginx reverse proxy (for VPS deployment)

If you're running on a VPS and want HTTPS with a custom domain:

# Install nginx
sudo apt install -y nginx certbot python3-certbot-nginx

# Create nginx config
sudo tee /etc/nginx/sites-available/paperclip << 'EOF'
server {
    listen 80;
    server_name paperclip.yourdomain.com;

    location / {
        proxy_pass http://127.0.0.1:3100;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 300;
    }
}
EOF

sudo ln -s /etc/nginx/sites-available/paperclip /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx
sudo certbot --nginx -d paperclip.yourdomain.com

Docker Compose commands reference

# Start in background
docker compose up -d

# Stop services
docker compose down

# Restart paperclip only
docker compose restart paperclip

# View logs
docker compose logs -f

# Check status
docker compose ps

# Pull latest image
docker compose pull

# Rebuild and restart
docker compose up -d --build

Updating Paperclip

Since the image is node:20-alpine with Paperclip installed at runtime, updating means pulling a fresh install:

docker compose down
docker compose up -d --force-recreate

Or pin a specific Paperclip version in your command:

command: sh -c "npm install -g paperclipai@1.2.3 && npx paperclipai server start ..."

Persistent storage

The paperclip_data volume stores everything Paperclip writes:

• SQLite database
• Agent workspace files
• Upload attachments

Inspect the volume:

docker volume inspect paperclip_paperclip_data

Backup the volume:

docker run --rm \
  -v paperclip_paperclip_data:/data \
  -v $(pwd):/backup \
  alpine tar czf /backup/paperclip-backup-$(date +%Y%m%d).tar.gz /data

Running on a Raspberry Pi

Docker Compose works on Raspberry Pi 4 (arm64). Use the same docker-compose.yml — node:20-alpine has official arm64 builds.

Minimum specs: Raspberry Pi 4 with 4 GB RAM. The 2 GB model may work for light use but will be tight.

Cost

Docker Compose itself is free. Cost depends on where you run it:

• Local machine: Free (uses existing hardware)
• VPS (Hetzner CX22): ~€4.51/month
• DigitalOcean Droplet: ~$6/month

For managed deploys with zero Docker knowledge required, Railway gives you $20 free credit.

This is an independent guide. Paperclip Hosting is not affiliated with the official Paperclip project. Guide steps are based on real deployments and are subject to change as the software evolves.