Paperless-ngx Deployment

This repository contains the deployment configuration for Paperless-ngx, a community-supported document management system that transforms your physical documents into a searchable online archive.

🏗️ Architecture Overview

The stack consists of three interconnected services:

• Webserver: The core Paperless-ngx application.
• Database: PostgreSQL 16 (Alpine-based) for metadata storage.
• Broker: Redis 7 (Alpine-based) for task queuing and caching.

Networking: All services reside on the web_traffic external network to facilitate communication with a reverse proxy and handle CSRF-trusted origins via https://paperless.georgew.dev.

📂 Repository Structure

• docker-compose.yaml: Orchestrates the webserver, DB, and Redis broker.
• .woodpecker.yaml: Automation script for deployment to the host.
• .env.example: Template for required sensitive environment variables.
• .gitignore: Configured to ensure .env and local data directories are not tracked.

🚀 Getting Started

1. Environment Configuration

Before deploying, you must create a local .env file from the provided template:

cp .env.example .env

Edit the .env file and set a strong POSTGRES_PASSWORD.

2. Manual Deployment

Ensure the web_traffic network exists:

docker network create web_traffic
docker compose up -d

🔄 CI/CD Workflow

The Woodpecker CI pipeline triggers on every push to main. It:

• Syncs the repository (including your server-side .env) to /home/george/paperless-ngx/.
• Performs a docker compose up -d with --pull always and --force-recreate.
• Utilizes a healthcheck on the webserver (http://localhost:8000) to ensure service availability.

💾 Data Persistence

The following local directories are mapped to persist your data:

• ./data: Application data.
• ./media: Your uploaded documents.
• ./pgdata: PostgreSQL database files.
• ./consume: The "magic" folder—drop files here to have them automatically imported.

Note: Ensure that the user running the containers has the appropriate permissions to write to these local directories.