53 lines
2.1 KiB
Markdown
53 lines
2.1 KiB
Markdown
# 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. |