From 504d0806fd03909ae6d879addceb5cefaf84cedc Mon Sep 17 00:00:00 2001
From: GeorgeWebberley <george@brain-plus.com>
Date: Mon, 2 Feb 2026 21:02:00 +0100
Subject: [PATCH] Added README

---
 README.md | 53 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 53 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..e2ea43e
--- /dev/null
+++ b/README.md
@@ -0,0 +1,53 @@
+# 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:
+```bash
+cp .env.example .env
+```
+Edit the .env file and set a strong POSTGRES_PASSWORD.
+
+### 2. Manual Deployment
+
+Ensure the web_traffic network exists:
+```bash
+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.
\ No newline at end of file