Paperless-ngx

What it's good for#

Most homes have a drawer, or a box, of letters that might matter one day: bank statements, payslips, the boiler warranty, the council tax bill. Paperless-ngx is where they go instead. You give it a scan or a PDF, it reads every word on the page (that's the OCR, optical character recognition), and from then on you can search for "boiler" and find the warranty. It also learns as you go. Once you've tagged a few letters from your energy supplier, it starts tagging the next ones for you.

The originals are kept untouched, alongside a searchable PDF copy, so nothing you put in is altered.

Signing in#

The account is called admin. Paperless makes it itself on its very first start, after setting up its database and before its web page ever answers, so nobody can get in first. Its password is in the Login Details shown when the install finished; press Welcome on the app's page to see it again. Sign-ups are off.

That first start takes a few minutes. Once it's up, LibrePortal checks that Paperless refuses anyone without a login and accepts yours; if it ever answered without one, LibrePortal stops it rather than leave your documents open.

If you reinstall Paperless and it keeps its old database, the admin keeps the old password. Use Reset User Password on the Tools tab to set a new one; for admin, the new password replaces the one in Login Details.

Getting documents in#

There are four ways in, and you can mix them.

Upload in the browser. Drag files onto the Paperless page, or use the upload button on its dashboard. This is the easy one for a scan you've just made or a PDF you've downloaded.

From your phone. There's no official app, but Paperless-ngx's own wiki lists several community ones. Paperless Mobile (Android) and Swift Paperless (iPhone and iPad) are two popular choices, and many of them can scan a letter with the camera and upload it in one go. Give the app your Paperless address and your username and password.

The consume folder. Paperless watches a folder called consume in its app folder, which on a standard install is /libreportal-containers/paperless/consume on the server. Anything you put there is imported and then removed from the folder. That's handy for a scanner that can save to a network folder, but LibrePortal doesn't share that folder over your network for you; you'd need to copy files in on the server yourself, or set up a share for it.

Email. Paperless can log in to a mailbox and import the attachments from the messages you choose. Set it up on Paperless's own Mail page: add a mail account (the mailbox's IMAP address and login), then a mail rule saying which messages to take and what to do with them afterwards. Any mailbox with IMAP works. If you run Stalwart on the same server, its row under Works with on Paperless's page shows whether a mail account has been set up yet and tells you how if not.

The document language#

Paperless reads documents in the language set by Document Language on the Config tab, as a short code: eng for English, deu for German, fra for French. If your paperwork is in more than one language, join them with a plus: deu+eng.

It's worth setting before you add much, because it only affects documents as they're read. Changing it later applies to new documents; ones already in the archive keep the text they were read with, unless you ask Paperless to read them again from its document list.

English, German, French, Italian and Spanish are built in. Any other language is downloaded each time Paperless starts, so that start needs the internet. Don't add languages you don't have documents in: each one makes every document slower to read, uses more memory, and makes the results worse, not better.

Adding people#

Each person can have their own login, and Paperless lets you decide who sees which documents. That's all done on Paperless's own Users & Groups page, signed in as the admin, because that's also where the permissions are. The Tools tab has List Users and Reset User Password for when someone is locked out.

On your phone, away from home#

Paperless is Private to start with: only your trusted places, like your home network and your devices on the LibrePortal VPN, can reach it. What it holds is your post, bills and papers, so that's the right default. To use a phone app when you're out, connect the phone to the VPN first.

You can make it public, but think twice. And don't put a password prompt from Traefik in front of it either: the phone apps talk to the same address and can't get past one.

Good to know#

• Memory. Paperless uses about 750 MB sitting still and up to 1.1 GB while it reads a document. Every extra document language adds to that.
• Updates wait for you. Every Paperless release changes its database the first time it starts, with no way back, so LibrePortal pins an exact version (3.2.1) and nothing changes until you press Update. That only brings rebuilds of the same version, with a backup taken first; if the Updates tab offers a newer release, Upgrade can't move Paperless to it yet.
• Backups include the database (tags, correspondents and the text of every document), the archive itself, and the search index. The consume folder is a drop box and isn't backed up, so don't leave anything there that isn't also somewhere else.
• One per server. Paperless can't run as several copies side by side.
• With a domain, it's at docs.<your domain>. Signing in works on the domain, on HTTPS and on the plain address alike, with nothing to set.