Paperclip self-hosting guide

Self-hosting Paperclip gives you full control — your data, your infrastructure, your rules. This guide is for intermediate users who are comfortable with Linux and want to run Paperclip outside of a managed platform.

Who this guide is for

This guide assumes you have a Linux server (bare metal, a homelab machine, or a rented VPS), are comfortable with SSH and the command line, and want to manage the full deployment yourself. If you'd prefer a simpler start, see the Hostinger or Railway guides instead.

Server requirements

Minimum: 1 vCPU, 1 GB RAM, 10 GB storage. Recommended: 2 vCPU, 2 GB RAM for comfortable operation with multiple users. Ubuntu 22.04 LTS or Debian 12 are the best-supported distributions.

Step 1: Prepare the server

Create a non-root user for running Paperclip, update the system, and configure your firewall.

adduser paperclip
usermod -aG sudo paperclip
apt update && apt upgrade -y
ufw allow OpenSSH
ufw allow 80
ufw allow 443
ufw enable

Step 2: Install Node.js, Git, and nginx

Install the required runtime and reverse proxy. nginx will handle SSL and forward traffic to your Paperclip process.

curl -fsSL https://deb.nodesource.com/setup_20.x | bash -
apt install -y nodejs git nginx
nginx -v

Step 3: Clone, configure, and build

Switch to the paperclip user, clone the repository, and configure your environment.

su - paperclip
git clone https://github.com/paperclip-app/paperclip.git
cd paperclip
npm install
cp .env.example .env
nano .env  # fill in your values
npm run build

Step 4: Configure nginx as a reverse proxy

Create an nginx site config to proxy requests to your Paperclip instance. Replace YOUR_DOMAIN with your actual domain or server IP.

# /etc/nginx/sites-available/paperclip
server {
  listen 80;
  server_name YOUR_DOMAIN;
  location / {
    proxy_pass http://localhost:3000;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection 'upgrade';
    proxy_set_header Host $host;
    proxy_cache_bypass $http_upgrade;
  }
}

Step 5: Run as a systemd service

Use a systemd unit file to keep Paperclip running and restart it automatically after reboots or crashes.

# /etc/systemd/system/paperclip.service
[Unit]
Description=Paperclip
After=network.target

[Service]
User=paperclip
WorkingDirectory=/home/paperclip/paperclip
ExecStart=/usr/bin/npm start
Restart=always

[Install]
WantedBy=multi-user.target

# Then:
systemctl enable paperclip
systemctl start paperclip

Keeping Paperclip updated

To update your self-hosted instance, pull the latest changes, reinstall dependencies if needed, rebuild, and restart the service.

cd /home/paperclip/paperclip
git pull
npm install
npm run build
systemctl restart paperclip