↓ Skip to main content
Zac Trolley
  1. Building Your Own Server/

Paperless-ngx - Self-Hosted Document Management

·780 words·4 mins

Paperless-ngx is a community supported open-source document management system that transforms your physical documents into a searchable online archive so you can keep, well, less paper. I use this to store all my important paperwork like tax records, health information, and insurance documents. You can scan in your own files, or upload PDFs. I also use this to keep all my manuals so that I don’t have to keep looking for them all the time, and I can quickly reference how I put my coffee maker into self-clean mode.

Paperless

Why Paperless-ngx:

  • Your Documents, Your Control: No corporate servers, no data mining, no subscriptions. Your documents belong to you, not a corporation.
  • Privacy First: Your sensitive documents stay on your own server. No one else can access your tax records, contracts, or personal documents.
  • Powerful Search: Full-text search across all your documents to find what you need quickly.
  • Open Source: Transparent, community-driven, and free to use.

Resources
#

Installation Prep
#

Before installing Paperless-ngx, ensure you have the following ready:

Time to Complete
#

  • Total Time: ~30 minutes
    • 10 min: File system prep
    • 10 min: Docker setup
    • 5 min: Download Paperless-ngx image
    • 5 min: Initial setup and configuration
  • Difficulty: Beginner

Installation
#

Step 1: File System Prep
#

We need to create the directories to keep the docker compose file and Paperless-ngx data.

Create the Paperless-ngx directory

mkdir -p ~/docker/paperless-ngx/

Create the folders where your data will live:

mkdir -p ~/docker/paperless-ngx/{data,media,export,import}

This creates the following structure:

/home/USER/docker/paperless-ngx/data/      # Paperless-ngx database
/home/USER/docker/paperless-ngx/media/     # Your documents
/home/USER/docker/paperless-ngx/export/    # Exported documents
/home/USER/docker/paperless-ngx/import/    # Documents to import

Step 2: Docker Setup
#

Make sure you are in your Paperless-ngx directory:

cd ~/docker/paperless-ngx

To double check you are in the right place, type pwd to see your current directory.

Create the docker compose.yaml file:

sudo nano docker compose.yaml

Step 3: docker compose file
#

Copy the following text into the docker compose file:

services:
  paperless-ngx:
    image: ghcr.io/paperless-ngx/paperless-ngx:latest
    container_name: paperless-ngx
    restart: unless-stopped
    ports:
      - "8000:8000"
    volumes:
      - ./data:/usr/src/paperless/data
      - ./media:/usr/src/paperless/media
      - ./export:/usr/src/paperless/export
      - ./import:/usr/src/paperless/import
    environment:
      - PAPERLESS_REDIS=redis://paperless-redis:6379
      - PAPERLESS_DBHOST=paperless-db
      - PAPERLESS_DBUSER=paperless
      - PAPERLESS_DBPASS=paperless
      - PAPERLESS_DBNAME=paperless
      - PAPERLESS_SECRET_KEY=your_secret_key_here
      - PAPERLESS_TIME_ZONE=America/Edmonton # Change to your timezone
      - PAPERLESS_URL=http://192.168.99.1:8000
    depends_on:
      - paperless-db
      - paperless-redis

  paperless-db:
    image: postgres:15
    container_name: paperless-db
    restart: unless-stopped
    volumes:
      - ./pgdata:/var/lib/postgresql/data
    environment:
      - POSTGRES_USER=paperless
      - POSTGRES_PASSWORD=paperless
      - POSTGRES_DB=paperless

  paperless-redis:
    image: redis:7
    container_name: paperless-redis
    restart: unless-stopped

Important: Replace your_secret_key_here with a strong, unique secret key.

Save and exit the file by pressing Ctrl+X and saying Y to save.

Step 4: Start Paperless-ngx
#

Now you can download and start Paperless-ngx:

sudo docker compose pull
sudo docker compose up -d

Once the pull is complete, verify the containers are running:

docker ps

You should see paperless-ngx, paperless-db, and paperless-redis all running.

Initial Setup and Configuration
#

Step 1: Access Paperless-ngx
#

Open your browser and navigate to:

http://192.168.99.1:8000

This is the IP address of your Linux Mint machine where Paperless-ngx is installed.

If you aren’t sure about your IP address or ports, refer to the networking guide or other internet sources. Understanding networking is critical to running and maintaining your own services.

Step 2: Create Your Account
#

  1. Create Account

    • Enter a username for your account
    • Enter a strong password
    • Click Create Account

  2. Login

    • Use your credentials to log in

Step 3: Configure Settings
#

  1. Go to Settings > Documents
  2. Configure Document Storage:
    • Document Storage Path: /usr/src/paperless/media/documents
    • Archive Storage Path: /usr/src/paperless/media/archive
  3. Configure Document Types:
    • Add custom document types as needed

Step 4: Import Documents
#

You can import documents in several ways:

Option A: Upload via Web Interface

  1. Click Documents in the sidebar
  2. Click Upload
  3. Select your documents
  4. Click Upload

Option B: Copy to Import Folder

  1. Copy documents to the import folder:
cp /path/to/your/documents ~/docker/paperless-ngx/import/
  1. Paperless-ngx will automatically import them

Usage
#

Web Interface
#

The Paperless-ngx web interface (http://192.168.99.1:8000) provides:

  • Documents: Browse, search, and manage your documents
  • Tags: Organize documents with tags
  • Correspondents: Categorize documents by sender
  • Types: Classify documents by type
  • Search: Full-text search across all documents

Common Tasks
#

Upload a Document:

  1. Click Documents in the sidebar
  2. Click Upload
  3. Select your document
  4. Add tags, correspondent, and type (optional)
  5. Click Upload

Search Documents:

  1. Use the search bar at the top
  2. Search by text, tags, correspondent, or type
  3. Use advanced search operators (e.g., tag:tax, correspondent:bank)

View Document Details:

  1. Click on a document
  2. View metadata, tags, and correspondent
  3. Download or delete the document

Organize Documents:

  1. Select documents
  2. Click Actions > Edit
  3. Add tags, correspondent, or type
  4. Click Save