Paperman
Introduction
Introduction
Features
Installation
Ubuntu PPA
Pre-built .deb Packages
Building from Source
User Guide
Command-line Interface
Basic Usage
Conversion Options
Other Options
Parallel PDF-to-max Conversion
How it works
Examples
Testing
Paperman Search Server
Overview
Building
Running the Server
Basic Usage
Options
API Endpoints
GET /status
GET /search
GET /list
Page Delivery
Supported File Types
CORS Support
Error Handling
Security Notes
Integration Examples
Using curl
Using Python
Using JavaScript (browser or Node.js)
Troubleshooting
License
Paperman Search Server API Documentation
Overview
Authentication
Enabling Authentication
Using Authentication
Authentication Behavior
Common Response Format
Success Response
Error Response
Endpoints
1. Server Status
2. List Repositories
3. Search Files
4. List Directory Contents
5. Get File Content
Supported File Types
Error Codes
CORS
Rate Limiting
Examples
JavaScript/Fetch API
Python
cURL
Security Considerations
Path Traversal Prevention
Network Security
File Access
Performance
Response Times
Caching
Troubleshooting
PDF Conversion Issues
File Access Issues
Changelog
Version 1.3 (Current)
Version 1.2
Version 1.1
Version 1.0
Support
License
Paperman Mobile App
Overview
Features
Prerequisites
Java JDK
Flutter SDK
Android SDK
Troubleshooting
Building
Project Structure
Architecture
Data Models
API Service
Screens
ConnectionScreen
BrowseScreen
SearchScreen
ViewerScreen
Widgets
FileTile
DirectoryTile
Navigation Flow
Server API Endpoints
Publishing to the Play Store
Signing
Building an app bundle
Uploading
Automated upload
Quick install via Google Drive
Quick install via scp
Connecting to the Server
Demo Mode
Implementation
Deployment
Deploying Paperman Server with HTTPS
Option 1: Using Apache (Recommended - Already Installed)
Step 1: Enable Required Apache Modules
Step 2: Create SSL Certificate
Step 3: Install Apache Configuration
Step 4: Deploy Paperman Server
Step 5: Test Access
Option 2: Using Nginx (Alternative)
Step 1: Install Nginx
Step 2: Create SSL Certificate
Step 3: Install Nginx Configuration
Step 4: Deploy Paperman Server
Firewall Configuration
Allow HTTPS through firewall
Block direct access to port 8080 (optional security)
Security Checklist
Generating Strong API Key
Troubleshooting
Check if services are running
View logs
Test SSL certificate
Common issues
Client Configuration Examples
Browser Bookmarklet
Python Script
Shell Script
Monitoring and Maintenance
Set up log rotation
Monitor with systemd
Performance Tuning
Paperman Server Deployment Guide
Prerequisites
Deployment Steps
1. Prepare Local Repository
2. Connect to the Server
3. Navigate to Paperman Directory
4. Pull Latest Changes
5. Build the Server
6. Verify Build Success
7. Stop Existing Server
8. Start New Server
9. Verify Server is Running
Testing the Deployment
Test Search Functionality
Test File Listing
Rollback Procedure
Troubleshooting
Build Fails
Server Won’t Start
API Returns Errors
Post-Deployment Checklist
Monitoring
Paperman Server Systemd Service
Files
Installation
Usage
Start the service
Stop the service
Check status
Enable autostart on boot
Disable autostart
View logs
Restart after configuration changes
Configuration
Modifying the Service
Advanced Options
Change port
Multiple repositories
Troubleshooting
Service won’t start
Permission issues
Port already in use
Uninstallation
Security Notes
Migrating from Apache to Nginx
Pre-Migration Checklist
Step-by-Step Migration
Step 1: Install Nginx
Step 2: Stop Apache (Temporary)
Step 3: Install Nginx Configuration
Step 4: SSL Certificates
Step 5: Configure Nginx
Step 6: Start Nginx
Step 7: Test the Setup
Step 8: Disable Apache (Permanent)
Step 9: Enable Nginx on Boot
Step 10: Update Certbot (if using Let’s Encrypt)
Rollback Plan (If Something Goes Wrong)
Verification Checklist
Nginx-Specific Commands
Useful Nginx Commands
Configuration Changes
Performance Tuning for Nginx
Firewall Configuration
Monitoring
Set up log rotation (automatic with nginx)
Monitor in real-time
Check error log for issues
Troubleshooting
“Address already in use”
“SSL certificate not found”
“502 Bad Gateway”
Configuration test fails
Let’s Encrypt renewal fails
Differences from Apache
Configuration Location
Reload Command
Test Configuration
Logs
Modules
Why Nginx is Better for Paperman
Migration Complete!
Paperman Services Guide
Overview
System Architecture
Components
Nginx Web Server
Service Management
Configuration Files
URL Structure and Authentication
Logs
Managing Authentication
Paperman-Server Backend
Service Management
Service Details
API Endpoints
Logs
Troubleshooting
Common Operations
Temporarily Disable Document API
Re-enable Document API
Update SSL Certificates
Backup Configuration Files
Restore from Backup
Security Notes
Static Files Location
Quick Reference
Check Everything is Running
View All Logs
Test Configuration
Development
Development
Prerequisites
Building
Project Layout
Key Source Files
Testing
Build Targets
Continuous Integration
Coding Style
Main Classes
Building
Environment
Build Everything
Flutter Builds
Build Targets
Output Locations
Releasing
Release Checklist
What the Workflow Does
Required Secrets
Manual PPA Upload
PPA (Personal Package Archive)
One-time Setup
Uploading
Checking Build Status
Target Distributions
Testing
Running Tests
Running a Single Suite
Listing Available Suites
Test Files
Flutter Widget Tests
Instructions for Claude Code: Set Up Paperman with Nginx
Context
Your Task
Step-by-Step Guidance
1. Prerequisites Check
2. Stop Apache (if running)
3. Generate SSL Certificate
4. Install Nginx Configuration
5. Install Paperman Service
6. Configure Firewall
7. Test the Setup
8. Verify Everything
Troubleshooting
Issue: “nginx: command not found”
Issue: “Address already in use” (port 80 or 443)
Issue: “502 Bad Gateway”
Issue: “nginx test failed”
Issue: Can’t access from external network
Success Criteria
Final Steps
Report to User
Remember
Installing Claude Code CLI on Your Server
Prerequisites
Installation Methods
Method 1: Using npm (Recommended)
Step 1: Install Node.js (if not already installed)
Step 2: Install Claude Code CLI
Method 2: Download Binary (Alternative)
Method 3: Build from Source (For Latest Features)
Configuration
Step 1: Get Anthropic API Key
Step 2: Configure Claude Code
Step 3: Verify Configuration
Basic Usage
Interactive Chat Mode
One-off Commands
Working with Files
Code Mode (for coding tasks)
Advanced Configuration
Custom Configuration File
Set Default Model
Enable Features
Using Claude Code with Paperman Development
Analyze Paperman Code
Git Integration
Debugging Help
SSH Usage (Running Claude on the Server from Dev Machine)
Option 1: SSH and Run
Option 2: SSH with Command
Option 3: tmux/screen Session
Troubleshooting
“command not found: claude”
“API key not found”
“Permission denied”
“Module not found” (if using npm)
Rate Limits / API Errors
Useful Aliases
Security Best Practices
Protect Your API Key
Sensitive Data
Cost Management
Monitor Usage
Cost-Saving Tips
Updating Claude Code
Update via npm
Update via binary
Integration with paperman-server Development
Example Workflow
Quick Reference
Essential Commands
Common Tasks
Next Steps
Resources
Support
Paperman
Index
Index