For a private household archive, the most practical Docker-based route is Paperless-ngx deployed with Docker Compose. Compose starts the application, PostgreSQL, a Redis-compatible message broker, persistent storage, and any optional conversion services as one manageable stack. The installation is straightforward; the lasting work is yours: choose a trusted host, protect access, back up every data layer, test restoration, and maintain the stack.
What you are building
Paperless-ngx turns scanned or already-digital records into a searchable online archive. You can upload files through the web interface or place them in a monitored consume directory. The system processes documents with OCR, extracts text and metadata, and lets you search, tag, and organize the resulting archive.
As an Amazon Associate I earn from qualifying purchases.
Docker packages the application and its supporting software into containers. Docker Compose is the description and control layer: a YAML configuration declares the containers, networks, volumes, environment values, and secrets, then the docker compose command creates and starts that group. This is different from installing one desktop application. You are operating a small service platform whose storage and security remain under your control.
Compose is suitable for a single-server deployment, including a home lab, but Docker’s production guidance expects you to adjust the example configuration for your environment. A default file is a starting point, not a complete security, monitoring, or disaster-recovery design.
#1 Best Overall
- Read Before You Buy — No Video Output: These adapters support charging and USB 2.0 data transfer, but cannot transmit video signals. Except for standard USB webcams (which use USB data only), they are not compatible with HDMI/DisplayPort cables, video-capable USB-C hubs, or docking stations with video output.
- Convert USB-A Ports to USB-C: Designed to connect USB-C earphones, cables, flash drives, card readers, and other USB-C accessories to standard USB-A ports. Plug-and-play with no drivers or software required.
- Aluminum Alloy Housing: Built with a sturdy aluminum alloy shell that aids in heat dissipation and protects against daily wear and scratches. Designed to maintain a stable and secure connection.
- Compact & Travel-Friendly: The ultra-compact design allows the adapter to stay plugged into your device without blocking adjacent ports or adding bulk, reducing wear and tear on your original USB ports.
- 12-Month Warranty: Backed by a 12-month manufacturer warranty for peace of mind. Designed to meet strict quality control standards for reliable everyday performance.
What do I need to run a document management system at home?
A host you control
Use a computer, server, virtual machine, or NAS that you administer and can keep powered whenever documents need to be uploaded or searched. The host must support Docker Engine and the Docker Compose plugin. Choose an operating system and Docker installation method supported by Docker for that platform, then verify that both docker and docker compose work before installing Paperless-ngx.
There is no vendor-supported minimum RAM, CPU, or disk figure established for this deployment. Plan capacity instead of relying on a generic number. Estimate the size of original files, OCR working data, database growth, and several backup generations. OCR of a large scan batch can use substantially more CPU and storage temporarily than browsing an existing archive.
Free tools Windows power users keep installed
One-click scans. No signup required.
Storage with a recovery plan
Decide host paths before starting containers. Paperless-ngx separates at least three kinds of persistent information:
- Document media: the originals and processed files in the
paperless_mediavolume. - Application data: auxiliary files and, in SQLite deployments, the SQLite database in the
paperless_datavolume. - Database contents: a separate PostgreSQL or MariaDB volume when you use an external database service.
Keep these paths on storage that is backed up independently of the container lifecycle. Removing and recreating a container should not remove your archive. Read the complete Compose file and change bind mounts only after you understand which host directory maps to which container path and which account needs access.
A trusted network boundary
Start with local access or a trusted home network. Tax returns, identity documents, invoices, contracts, and medical records are sensitive even when the archive is convenient. Public internet access requires a separately designed authentication, TLS, firewall, update, and threat-model setup; a default Compose deployment does not establish any of those controls or compliance with a regulated-data framework.
Optional scanning hardware
A duplex document scanner is useful when you are converting paper, but it is not required if your records already exist as PDFs or image files. The important input is a legible file; Paperless-ngx does not require a particular scanner model.
Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Repair Windows errors before they cause bigger problems3Scan for outdated or missing drivers - takes under a minuteHow do I install Paperless-ngx with Docker Compose?
Paperless-ngx supports two official setup styles. The interactive installer asks questions and creates the required files for you. The manual route gives you the Compose template and environment files so you can inspect and edit them before starting anything.
| Approach | Best for | What it does | Trade-off |
|---|---|---|---|
| Interactive installer | First deployment or a quick home-lab setup | Prompts for configuration, creates files, pulls the image, starts services, and creates the initial superuser. | Less typing, but you still need to review storage, access, secrets, and backup choices. |
| Manual Compose templates | Operators who want explicit control or repeatable configuration | Downloads the template for the selected database backend and its environment files; optional Tika templates add Office and other document conversion support. | More review and editing, with more control over paths and settings. |
1. Select the database and document-format options
For a new installation, current Paperless-ngx setup guidance recommends PostgreSQL. Alternate templates exist, so do not silently substitute a different backend: record which template and database you actually deploy because it affects volumes, backups, and future migration work.
Rank #2
- 5-in-1 USB-C Hub: Experience comprehensive connectivity featuring a Power Delivery input, two USB-A 2.0 ports, a USB-A 3.0 port, and an HDMI port. (Note: The USB-C power delivery input port is only for connecting an external wall charger to power your laptop and cannot power peripheral devices.)
- 90W Pass-Through Charging: Achieve optimal charging with 90W pass-through power to your laptop, supported by a total input of 100W, with the hub reserving 10W for operational efficiency. (Note: Wall charger not included.)
- Quick Data Transfers: Accelerate your productivity with rapid data transfers using a high-speed 5Gbps USB 3.0 port and two 480Mbps USB 2.0 ports.
- 4K HDMI Display: Enhance your visual experience with a hub capable of delivering 4K resolution at 30Hz in both mirror and extend modes. Please note that this hub is compatible with MacBook (macOS 12 and newer), Windows 10 and 11, ChromeOS, and laptops equipped with DP Alt Mode and Power Delivery. Note: This device is not compatible with Linux.
- What You Get: Anker USB-C Hub (5-in-1, 4K HDMI), welcome guide, 18-month warranty, and our friendly customer service.
The base deployment handles the normal document formats described by the project. If you need Office and other additional formats, choose the optional template that includes Tika. Treat that as an additional service with its own image, resource use, and update cycle rather than assuming every format is handled by the base stack.
2. Create or obtain the Compose files
For the guided route, run the project’s current interactive Docker Compose installer and answer its configuration questions. It creates the Compose and environment files, pulls the image, starts the containers, and creates an initial superuser.
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →For the manual route, download the Compose template for PostgreSQL (or the backend you deliberately selected) together with its environment files. Optional -tika templates add Tika support. Keep the files in a dedicated directory that you can include in your backup set; the Compose file and environment values are part of the deployment’s recovery documentation.
3. Inspect the resolved configuration before startup
Compose files can combine multiple files and substitute environment variables. Resolve the configuration and review it before launching services:
docker compose configCheck the output for host bind mounts, published ports, database names, credentials, image references, restart policies, devices, and any privileged settings. Docker treats a Compose file as trusted input: it can request host networking, device access, privileged operations, host directories, and arbitrary images. Only run a file whose author and contents you understand.
4. Set host paths and required settings
Edit the generated environment files and Compose mounts to point to the directories you selected. Confirm that the Docker service account can read and write those paths, while unrelated host users cannot browse the archive unnecessarily. Do not place a document directory on a temporary filesystem or inside a location routinely cleaned by the operating system.
Set the OCR language to match the documents you will process and set the timezone for the actual installation. A correct timezone keeps timestamps and scheduled behavior intelligible; it does not add support for a file type that requires Tika.
5. Pull images and start the stack
From the directory containing the Compose files, pull the referenced images and start the services:
Rank #3
- Sleek 7-in-1 USB-C Hub: Features an HDMI port, two USB-A 3.0 ports, and a USB-C data port, each providing 5Gbps transfer speeds. It also includes a USB-C PD input port for charging up to 100W and dual SD and TF card slots, all in a compact design.
- Flawless 4K@60Hz Video with HDMI: Delivers exceptional clarity and smoothness with its 4K@60Hz HDMI port, making it ideal for high-definition presentations and entertainment. (Note: Only the HDMI port supports video projection; the USB-C port is for data transfer only.)
- Double Up on Efficiency: The two USB-A 3.0 ports and a USB-C port support a fast 5Gbps data rate, significantly boosting your transfer speeds and improving productivity.
- Fast and Reliable 85W Charging: Offers high-capacity, speedy charging for laptops up to 85W, so you spend less time tethered to an outlet and more time being productive.
- What You Get: Anker USB-C Hub (7-in-1), welcome guide, 18-month warranty, and our friendly customer service.
docker compose pull
docker compose up -dThe exact service list depends on the selected template. A current PostgreSQL deployment normally includes the Paperless-ngx web application and worker components, PostgreSQL, and a Redis-compatible broker. The official FAQ identifies Valkey as the default broker in current bundled Compose files. Optional Tika adds conversion services.
The standard example is reachable on the local host at port 8000 unless you changed the port binding. Open that address from an allowed machine, sign in with the superuser created by the installer, and immediately review the account, password, and access settings.
6. Confirm that ingestion works
Upload a small, non-sensitive test document first. Verify that it appears in the archive, that OCR text is searchable, and that metadata and timestamps use the expected language and timezone. Then test the consume-directory workflow if you plan to use it. A successful container start does not prove that file permissions, OCR, the database, and background workers are all functioning.
How the Paperless-ngx Compose stack fits together
Understanding the roles of the services makes failures easier to diagnose:
- Web application: serves the interface and API and coordinates user actions.
- Background workers: perform OCR, classification, indexing, and other tasks outside the immediate web request.
- PostgreSQL: stores structured metadata, users, tags, and search-related records in a new recommended deployment.
- Redis-compatible broker: queues work between the web application and workers. Valkey is the default in current bundled Compose files according to the project’s FAQ.
- Persistent volumes: retain media, auxiliary data, and database contents when containers are recreated.
- Optional Tika service: converts or extracts text from Office and other additional formats when you select a Tika-enabled template.
These services communicate over the Compose network. You generally should not publish every internal port to the host; expose only the interface you intend users to reach.
When does the consume folder fail to notice new files?
Paperless-ngx normally relies on filesystem notifications to detect files placed in the consume directory. NFS and some other network filesystems do not provide the required inotify behavior. In that case, a file can exist on disk while the application never receives an event.
Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Clear out junk files and repair common Windows errorsFree Scan →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Configure polling with PAPERLESS_CONSUMER_POLLING_INTERVAL when the consume directory is on a filesystem without inotify support. Choose an interval appropriate for your workload: shorter polling detects files sooner but creates more filesystem checks. After changing the setting, recreate or restart the relevant Compose services and confirm detection with a test file.
How do I keep a self-hosted archive private?
Use a trusted host
Paperless-ngx states: “Paperless-ngx should never be run on an untrusted host because information is stored in clear text without encryption.” That warning applies to the host, its storage, administrators, and any backup destination. Container isolation is not a substitute for trusting the machine that can read the mounted files.
Rank #4
- Dual Converters, Infinite Potential：Includes 2× USB C male to USB A female adapters and 2× USB A male to USB C female adapters. Perfect for a wide range of uses—tablets with Bluetooth keyboards, expand USB ports on macbook, and more. Two different converters for all your daily needs
- Next-Level 10Gbps & 3A Charging: No more slow 480Mbps, this usb to usb c adapter has a transfer speed of up to 10Gbps, allowing you to do more transferring in less time. This usb adapter fits both USB A and USB C charger, supporting up to 3A fast charging
- Upgraded Exquisite Craftsmanship: With an aluminum alloy housing and metal connector, the usbc to usb adapter is extremely durable and sturdy. Rigorously tested to withstand more than 10,000 times of plugging and unplugging, ensuring long-lasting performance
- Broad Compatible: The usb c to usb adapter widely supports all USB C/ USB A devices like laptops, tablets, cellphones, car chargers, and phone chargers. Such as compatible with MacBook Pro/Air 2023/2022, Thunderbolt 4/3 Devices,Apple MagSafe Watch 9/8/7/SE/Ultra, iPad Pro 2022/2021, Samsung Galaxy S23/S20/S10, and iPhone 17/16/15 Pro. Plug and play
- Please Note: To reach 10Gbps speed, keep the cable under 3.3 ft. For USB A Male to USB C adapters, try flipping the USB C connector. USB C Male to USB A adapters support bidirectional 10Gbps transfer within 3.3 ft
Review Compose as a privileged input
Before startup, inspect the fully resolved output from docker compose config. Look for:
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
- Bind mounts that expose more of the host than the archive needs.
- Host networking, privileged mode, device mappings, or unexpected capabilities.
- Images from registries or authors you did not intend to trust.
- Published ports that make the service reachable beyond your local network.
- Credentials repeated in several services or written into shell history.
Docker Compose secrets can grant a selected service a secret as a file under /run/secrets/. Access is explicit per service. This scoping can be preferable to exposing a credential as an environment variable to every process in a container, but Compose secrets do not automatically encrypt the source file on the host or guarantee encryption at rest.
Limit exposure
Keep the web port bound to the local host or trusted LAN unless you have designed remote access separately. Use strong, unique administrator credentials, remove or disable accounts you do not need, and keep the host and images updated. Do not describe the unmodified example as secure for a particular regulated workload.
How do I back up Paperless-ngx?
A reliable backup covers more than the visible PDF directory. Treat the archive as three related recovery sets: document media, application data, and database contents. Also preserve the Compose file, environment settings, secret sources, and the image version used to create the backup.
Back up each persistent layer
- Media: back up the
paperless_mediavolume or its mapped host directory. This contains the documents you cannot recreate from metadata alone. - Application data: back up
paperless_data, including auxiliary data and any SQLite database if your deployment uses SQLite. - Database: back up the PostgreSQL or MariaDB database volume and use a database-consistent dump strategy appropriate to that engine. A media-only copy does not restore users, tags, correspondents, metadata, or search state.
- Configuration: retain the exact Compose files, environment values, secret files or secret-generation process, host-path mapping, and image tags needed to recreate the services.
Paperless-ngx also provides document exporter and importer tools. An application-level export is useful for moving documents between installations or recovering the archive’s logical content, but it is not identical to a complete infrastructure backup of volumes, database, configuration, and secrets.
Windows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallOutdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchStore a copy away from the Docker host
A second copy should survive loss of the server, its disks, or its operating-system installation. An external drive, another computer, a NAS, or an off-site destination can serve that role, but no single device is automatically a complete backup plan. Consider access control, encryption, retention, and whether the destination itself can be restored.
Test an actual restore
- Provision a separate test host or isolated directory; do not experiment first on the only live archive.
- Install the Docker and Compose versions required by the recorded deployment.
- Restore the Compose files, environment values, secrets, media, application data, and database backup.
- Start the restored stack and verify that users can sign in, documents open, OCR text searches correctly, and metadata is present.
- Record the elapsed time, missing steps, and any version-specific changes, then update the recovery notes.
A backup that has never been restored is an assumption, not a demonstrated recovery path.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Can I run Paperless-ngx on a NAS?
Yes, if the NAS can run a supported Docker Engine and Compose environment and can provide storage with permissions and reliability suitable for the archive. The NAS must remain available when you want to ingest or search documents, and its storage must be included in a backup plan that survives failure of the NAS itself.
Best Value
- 5-in-1 Connectivity: Equipped with a 4K HDMI port, a 5 Gbps USB-C data port, two 5 Gbps USB-A ports, and a USB C 100W PD-IN port. Note: The USB C 100W PD-IN port supports only charging and does not support data transfer devices such as headphones or speakers.
- Powerful Pass-Through Charging: Supports up to 85W pass-through charging so you can power up your laptop while you use the hub. Note: Pass-through charging requires a charger (not included). Note: To achieve full power for iPad, we recommend using a 45W wall charger.
- Transfer Files in Seconds: Move files to and from your laptop at speeds of up to 5 Gbps via the USB-C and USB-A data ports. Note: The USB C 5Gbps Data port does not support video output.
- HD Display: Connect to the HDMI port to stream or mirror content to an external monitor in resolutions of up to 4K@30Hz. Note: The USB-C ports do not support video output.
- What You Get: Anker 332 USB-C Hub (5-in-1), welcome guide, our worry-free 18-month warranty, and friendly customer service.
Pay particular attention to filesystem notifications. If the consume directory is on NFS or another filesystem without inotify support, configure PAPERLESS_CONSUMER_POLLING_INTERVAL so new files are discovered by polling. Network storage also adds latency and another failure boundary for database and media access; test ingestion and restoration before moving a live archive.
Recommended Free Tools
Do not treat RAID, snapshots, or a second NAS as a substitute for an independently recoverable copy. Those features can improve availability or rollback, but they do not protect against every deletion, corruption, account compromise, or site-level loss.
How do I maintain and upgrade the deployment?
Back up before changing images
Record the currently running image versions and configuration, then complete a verified backup before an upgrade. This gives you a known point for investigating changed behavior or rolling back according to the project’s version guidance.
Pull and recreate the services
The administration guidance uses the Compose workflow of pulling updated images and starting the application again so required database migrations can run:
docker compose pull
docker compose up -dWatch container logs and the web interface after the restart. Confirm that workers process a test document and that the database remains accessible. Do not delete volumes as part of routine updating; volumes are where the persistent archive lives.
Use production-specific overrides when needed
Docker’s Compose guidance recommends production-specific overrides for changes such as port bindings, environment values, extra services, and restart policies. Keep those overrides under version control or in the recovery documentation. A restart policy can bring a stopped process back after termination, but it is not monitoring, a health check, a backup, or proof that OCR and database operations are healthy.
Common failure modes and fixes
The web page does not open
- Confirm that the containers are running and that the host port is the one you configured.
- Check whether the port is bound only to localhost when you are connecting from another machine.
- Review Compose logs for an application, database, or broker startup error.
- Run
docker compose configagain to catch an unset variable or an unexpected merged override.
Documents remain in the consume directory
- Check permissions on the host directory and its parent paths.
- Confirm that the worker services are running and that the database and broker are reachable.
- On NFS or another notification-limited filesystem, set
PAPERLESS_CONSUMER_POLLING_INTERVALand test with a newly copied file. - Inspect logs for an unsupported format, a failed conversion, or an OCR error.
OCR text is missing or searches return nothing
- Verify that the worker completed processing rather than only accepting the upload.
- Check the configured OCR language against the document language.
- Use a clear, legible test scan to separate image-quality problems from service configuration problems.
- If you need Office or another additional format, confirm that you selected and started the Tika-enabled template.
The archive disappears after a container recreation
This usually indicates that data was written to a container layer or an unintended host path instead of the declared persistent volumes. Stop making changes, inspect the Compose volume mappings, and compare them with the location included in your backups. Do not remove volumes while troubleshooting.
Interactive installer or manual Compose: which should you choose?
| Decision | Interactive installer | Manual templates |
|---|---|---|
| Initial effort | Lowest: questions and file generation are automated. | Higher: you obtain, inspect, and edit the files yourself. |
| Visibility before launch | Review the generated files and run docker compose config before trusting them. |
Configuration is visible from the beginning and easier to place under change control. |
| Database | Choose the supported option presented by the installer; PostgreSQL is recommended for new installations. | Select the matching backend template and preserve its database-specific backup plan. |
| Additional formats | Select the optional Tika choice if offered and required. | Use a Tika-enabled template when Office or other additional formats are needed. |
| Filesystem behavior | Still requires polling configuration when the consume path lacks inotify. | Still requires polling configuration when the consume path lacks inotify. |
| Long-term operations | Does not automate your backups, updates, security reviews, or restore tests. | Does not reduce those responsibilities either, but makes custom operations easier to document. |
A practical first-day checklist
- Choose a host and document who can administer it.
- Choose separate persistent locations for media, application data, and the database.
- Install Docker Engine and the Compose plugin supported by your host.
- Select PostgreSQL for a new deployment unless you have a documented reason to use another backend.
- Choose a Tika-enabled template only when you need its additional format support.
- Generate or download the official Compose and environment files.
- Run
docker compose configand inspect mounts, ports, images, credentials, and privileges. - Set OCR language, timezone, host paths, and secrets.
- Run
docker compose pullfollowed bydocker compose up -d. - Sign in on the configured web port, normally
8000in the example, and change initial credentials as appropriate. - Process a harmless test document and verify OCR, search, and metadata.
- Configure polling if the consume directory is on a filesystem without inotify.
- Back up media, application data, database contents, and deployment configuration.
- Restore the backup on an isolated test environment before entrusting the system with irreplaceable records.
Is self-hosting the right fit?
Self-hosting is a good fit when you want control over where household records live, can maintain a Docker host, and are willing to own the operational tasks. It is a poor fit if you cannot keep the host patched, protect administrator access, provide independent backups, or test recovery. Paperless-ngx and Docker make deployment repeatable, but they do not remove the responsibilities that come with holding the data.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
