Instructions for Claude Code: Set Up Paperman with Nginx

TO CLAUDE CODE ON THE SERVER:

You are running on a Linux server. Your task is to set up the paperman search server with nginx as a reverse proxy with HTTPS.

Context

You have these files in the current directory: - paperman - Main application binary - paperman-server - Search server binary - nginx-paperman.conf - nginx configuration template - paperman-server.service - Systemd service file - setup-paperman-nginx.sh - Setup script (execute this)

Your Task

Execute the setup script and help the user through any issues:

sudo ./setup-paperman-nginx.sh

The script will: 1. Check prerequisites (nginx, openssl, systemd) 2. Create SSL certificates 3. Install nginx configuration 4. Install systemd service with API key 5. Configure firewall 6. Start services 7. Test everything

Step-by-Step Guidance

1. Prerequisites Check

Verify these are installed: - nginx - openssl - systemd - curl (for testing)

If missing, install with:

sudo apt update
sudo apt install nginx openssl curl

2. Stop Apache (if running)

sudo systemctl stop apache2
sudo systemctl disable apache2

3. Generate SSL Certificate

Create self-signed certificate:

sudo mkdir -p /etc/nginx/ssl
sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
    -keyout /etc/nginx/ssl/paperman.key \
    -out /etc/nginx/ssl/paperman.crt \
    -subj "/CN=$(hostname)"
sudo chmod 600 /etc/nginx/ssl/paperman.key
sudo chmod 644 /etc/nginx/ssl/paperman.crt

4. Install Nginx Configuration

# Copy configuration
sudo cp nginx-paperman.conf /etc/nginx/sites-available/paperman

# Edit to set correct hostname
HOSTNAME=$(hostname -f)
sudo sed -i "s/your-server.example.com/$HOSTNAME/g" /etc/nginx/sites-available/paperman

# Enable site
sudo rm -f /etc/nginx/sites-enabled/default
sudo ln -s /etc/nginx/sites-available/paperman /etc/nginx/sites-enabled/

# Test configuration
sudo nginx -t

# If test passes, reload
sudo systemctl reload nginx || sudo systemctl start nginx
sudo systemctl enable nginx

5. Install Paperman Service

# Generate strong API key
API_KEY=$(openssl rand -base64 32)
echo "Generated API Key: $API_KEY"
echo "Save this key - you'll need it to access the API!"
echo "$API_KEY" > ~/paperman-api-key.txt
chmod 600 ~/paperman-api-key.txt

# Copy service file
sudo cp paperman-server.service /etc/systemd/system/

# Add API key to service
sudo sed -i "/\[Service\]/a Environment=\"PAPERMAN_API_KEY=$API_KEY\"" /etc/systemd/system/paperman-server.service

# Update paths in service file (assuming files are in current directory)
CURRENT_DIR=$(pwd)
sudo sed -i "s|/opt/paperman|$CURRENT_DIR|g" /etc/systemd/system/paperman-server.service
sudo sed -i "s|/srv/papers|$CURRENT_DIR/papers|g" /etc/systemd/system/paperman-server.service

# Create papers directory if it doesn't exist
mkdir -p $CURRENT_DIR/papers

# Reload and start
sudo systemctl daemon-reload
sudo systemctl start paperman-server
sudo systemctl enable paperman-server
sudo systemctl status paperman-server

6. Configure Firewall

# Allow HTTPS
sudo ufw allow 443/tcp || sudo iptables -A INPUT -p tcp --dport 443 -j ACCEPT

# Allow HTTP (for redirects)
sudo ufw allow 80/tcp || sudo iptables -A INPUT -p tcp --dport 80 -j ACCEPT

# Block direct access to 8080 from external (security)
sudo ufw deny 8080/tcp || {
    sudo iptables -A INPUT -p tcp --dport 8080 -i lo -j ACCEPT
    sudo iptables -A INPUT -p tcp --dport 8080 -j DROP
}

# Save iptables if using
which netfilter-persistent && sudo netfilter-persistent save

7. Test the Setup

# Get the API key
API_KEY=$(cat ~/paperman-api-key.txt)

# Test status endpoint (no auth needed)
curl -k https://localhost/status

# Test search with API key
curl -k -H "X-API-Key: $API_KEY" https://localhost/search?q=test

# Check logs
sudo journalctl -u paperman-server -n 20
sudo tail -20 /var/log/nginx/paperman-error.log

8. Verify Everything

Check these items: - [ ] nginx is running: sudo systemctl status nginx - [ ] paperman-server is running: sudo systemctl status paperman-server - [ ] Port 443 is listening: sudo netstat -tlnp | grep 443 - [ ] Port 8080 is listening: sudo netstat -tlnp | grep 8080 - [ ] Status endpoint works: curl -k https://localhost/status - [ ] API key authentication works - [ ] Firewall is configured - [ ] Services start on boot

Troubleshooting

Issue: “nginx: command not found”

sudo apt update
sudo apt install nginx

Issue: “Address already in use” (port 80 or 443)

# Check what's using the port
sudo netstat -tlnp | grep -E ':(80|443)'

# If Apache is still running
sudo systemctl stop apache2
sudo systemctl disable apache2

Issue: “502 Bad Gateway”

# Check if paperman-server is running
sudo systemctl status paperman-server

# Check if it's listening on 8080
sudo netstat -tlnp | grep 8080

# Check logs
sudo journalctl -u paperman-server -n 50

Issue: “nginx test failed”

# See detailed error
sudo nginx -t

# Common fixes:
# - Check SSL certificate paths exist
# - Check syntax (semicolons, braces)
# - Check file permissions

Issue: Can’t access from external network

# Check firewall
sudo ufw status
sudo iptables -L -n

# Check nginx is listening on all interfaces
sudo netstat -tlnp | grep nginx

# Check logs
sudo tail -f /var/log/nginx/paperman-error.log

Success Criteria

When complete, you should see:

Nginx status:

● nginx.service - A high performance web server
Active: active (running)

Paperman status:

● paperman-server.service - Paperman Search Server
Active: active (running)

Status endpoint works:

{"status":"running","repository":"..."}

API authentication works:

# Without key - fails
curl -k https://localhost/search?q=test
# Returns: {"error":"Invalid or missing API key..."}

# With key - works
curl -k -H "X-API-Key: YOUR-KEY" https://localhost/search?q=test
# Returns: {"success":true,...}

Final Steps

Once everything is working:

Save the API key - Located in ~/paperman-api-key.txt
Note the server URL - https://$(hostname -f) or https://$(hostname -I | awk '{print $1}')
Test from external machine if applicable

Set up monitoring (optional):

# Watch logs
sudo journalctl -u paperman-server -f

# Watch nginx logs
sudo tail -f /var/log/nginx/paperman-access.log

Report to User

When complete, provide: 1. ✅ Status of all services 2. ✅ API key (from ~/paperman-api-key.txt) 3. ✅ Server URL 4. ✅ Test results 5. ✅ Any warnings or issues encountered

Tell the user: - How to access the server - How to use the API key - Where logs are located - How to check service status

Remember

Always run commands with sudo where needed
Check for errors after each step
If something fails, check logs and explain the issue to the user
The API key is sensitive - handle it securely
Test everything before declaring success

Good luck! 🚀