A light filing cabinet for a household or a small firm: OCR, search, vaults, Paperless-ngx import.
2.1K
Paperless-ngx for the home: the simple version. A light filing cabinet for the papers of a household or a small firm, on your own server. Upload, find, done. One container, no Redis, no Celery, no Postgres, and an import that takes over what you already have in Paperless-ngx.
kind:invoice amount:>100)./api/v1) for your own tools.nexpaper is one of the nex apps and looks like them: light paper and kraft by day, a dark desk by night.
1.0.0. Back up /data like any other data of yours (the documents are plain files in /data/dokumente) and read
what a backup holds and what it does not (below). nexpaper is an independent project and not affiliated with
Paperless-ngx; it only reads from a Paperless-ngx server when you import.
![]() | ![]() |
![]() | ![]() |
The pictures show a made-up household.
services:
nexpaper:
image: ghcr.io/derkezorm/nexpaper:latest
container_name: nexpaper
restart: unless-stopped
ports:
- "127.0.0.1:8560:8000"
security_opt:
- no-new-privileges:true
cap_drop:
- ALL
cap_add:
- CHOWN
- DAC_READ_SEARCH
- SETUID
- SETGID
volumes:
- ./data:/data
environment:
PUID: 1000
PGID: 1000
TZ: Europe/Berlin
docker compose up -d
The container may not gain rights later and keeps only what its start needs: setting the owner of /data (CHOWN,
DAC_READ_SEARCH) and dropping from root to the user nexpaper (SETUID, SETGID). nexpaper itself runs as that
user, with none.
Built from source instead: clone this repository, use docker-compose.yml as it is (it has build: .) and run
docker compose up -d --build. The file has every option explained.
Open http://127.0.0.1:8560 on that machine (the port listens only there; the comment in
docker-compose.yml says how to change that). The first account you create there is the operator.
It needs the setup code from the log, so that nobody who reaches a fresh instance first can take it:
docker logs nexpaper
shows the code, new at every start until nexpaper is set up. To choose it yourself, set NEXPAPER_SETUP_TOKEN. Right
after the password the account sets up its second factor; then the operator invites the others by link. Everything
personal is under "My account" for everybody; "Settings" is the operator's and holds the server.
Your papers are best kept in your own network. To reach nexpaper on the way, a VPN into your home network (WireGuard, Tailscale, NetBird and the like) is the safer choice than opening a port. If you open it to the internet anyway, do it with care and at least this:
127.0.0.1:8560:8000 when
the proxy runs on the same host, or keep both on a Docker network without a published port. Send HSTS from the proxy.NEXPAPER_PUBLIC_URL (the address people use), NEXPAPER_TRUSTED_PROXIES (the
proxy's address or network; without it every sign-in seems to come from the proxy and the brake against guessing
cannot tell people apart) and NEXPAPER_COOKIE_SECURE: "on".secret.key) but not the documents: those are plain files in /data/dokumente and belong in the backup your
server makes anyway. Try a restore with "Check" now and then.latest, update on purpose, back up before. An upload request is the one way
in for somebody without an account that takes files: whoever holds its address can put up to its number of files
into one person's inbox, nothing else (see Inputs, and SECURITY.md).Optionally keep the operator's settings at home: NEXPAPER_OPERATOR_NETWORKS: "192.168.0.0/16" refuses them from
anywhere else (behind a proxy only together with NEXPAPER_TRUSTED_PROXIES).
Besides the password, people can sign in through any provider that speaks OpenID Connect: authentik, Microsoft Entra ID, Keycloak, Authelia, Pocket ID. Settings, Sign-in has three cards: the sign-in itself (password sign-in, the public address, the second factor), the list of sign-in providers (each gets a button on the sign-in page, in the order of the list), and authentik in one step.
https://paper.example.com/api/v1/oidc/<short name>/callback, fixed once made), the issuer, client ID and secret.
For Microsoft Entra ID the issuer is https://login.microsoftonline.com/<tenant>/v2.0, or common or
organizations for several tenants.Behind a reverse proxy the redirect address is the public address (set it in Settings, Sign-in, or the authentik
card offers the address the browser uses). For the authentik card and the Secure flag to see https, name the proxy in
NEXPAPER_TRUSTED_PROXIES: nexpaper then believes its X-Forwarded-For and its X-Forwarded-Proto (the last value the
proxy wrote), and nobody else's.
Coming from 1.0.1: the one provider of 1.0.1 becomes the entry oidc with every account linked as before, after a
backup, and keeps its redirect address /api/v1/oidc/callback, so nothing changes at the provider. Whether it checks
the second factor comes from 1.0.1's switch. Going back to 1.0.1 works for this version: 1.0.1 finds its settings as the
entry oidc stands while the entry is on and checks the second factor itself (its switch on), otherwise without a
client, so that 1.0.1 never lets anybody in with less than the entry asks. What 1.0.1 changes there is taken over at the
next start of the newer version.
Whoever can run a command in the container holds the database and the secrets anyway, so a link made there gives nothing away. It is the same link the operator sends from Settings, Accounts: it works once and for 24 hours, a new one replaces the one before, and using it ends every session and lifts a lock after failed sign-ins. The second factor stays: sign in with the new password, then with the code from your app, a passkey or a recovery code. An account that signs in only through a provider gets a password this way and becomes an account with a password, as with the link the operator sends.
docker exec -it -u nexpaper nexpaper python -m app.reset_link <account>
-u nexpaper runs it as the user the server runs as (with the ids of PUID and PGID); as root it refuses, because a
file root makes in /data the server could not open any more. Where the compose file starts the container with a
user: of its own, give that instead. Without an account name it lists the accounts. It prints the whole link when
the public address is set (Settings, Sign-in, or NEXPAPER_PUBLIC_URL), otherwise the path /reset/... to open at the
address you use. An unknown or blocked account gets no link and a message, and the command ends with an error. The log
notes that a link was made this way, and for whom, never the link itself.
Everything lives in /data:
| Where | What |
|---|---|
nexpaper.db | The SQLite database: accounts, settings, the filing, the recognised text and the search index. |
secret.key | The server's own secret (the secrets of the sign-in providers, the mail password, the AI key and the like). |
backups/, logs/, locales/ | Backups, the log, extra languages as JSON files. |
dokumente/ | The documents themselves, as readable files (below). Readable without nexpaper. |
cache/, uploads/, exports/ | Pictures of pages (trimmed to a size you set), uploads in progress, ZIPs for the tax adviser. |
eingang/ | The intake folder, when it is switched on (Settings, Inputs): one subfolder per person. |
The documents lie as <vault>/<year>/<sender>/<date> <kind>.<ending>, the original as it came, for example
Household/2026/City Utilities/2026-10-07 Invoice.pdf. Beside it lie the searchable copy (2026-10-07 Invoice (searchable).pdf, also the PDF made from a photo) and the older versions (2026-10-07 Invoice (version 1).pdf); two
documents with the same name get (2). The title is not part of the name (the export for the tax adviser names its
files by date and title). Where a part is missing, the folders and files on the disk have English names whatever the
language of the interface: undated for the year and the date, no sender, and Document for the kind. The interface
shows them translated; the names on the disk stay as they are.
Mount /data from a local disk, never from an SMB or NFS share: SQLite's locking does not work reliably over network
filesystems. There is no per-person encryption: it would stop search and make the files unreadable without nexpaper. A
personal vault means only that nexpaper shows it to nobody else; protecting the disk is the operator's business.
When the operator deletes an account, they decide where the documents of its personal vault go, and may give them to
themselves or to a vault they are in: the dialog says so, and every document's history notes the takeover and by whom.
A backup is one ZIP file with the database, the settings and secret.key, made while nexpaper runs (through SQLite's
backup function, never as a file copy). It holds no documents: they lie as plain files in /data/dokumente and belong
in the backup your server makes anyway (Hyper Backup, restic, snapshots). It holds no search index either: that is
the largest part of the database, and it is built anew from the recognised text after a restore (the search works while
that goes on, with more and more hits). Together with secret.key it opens the mail and AI credentials, the addresses
of open links and the kept PDF passwords, so keep backups protected.
Settings, Backups: automatic daily or weekly with a number to keep, "Back up now", upload, download, check and restore. The trial run ("Check", and again in the dialog before a restore) starts the database of the archive the way the server would, on a scratch copy, and says whether the archive is whole (a damaged one is told as damaged) and can be started, which version made it (one from a newer nexpaper is refused), how many documents it knows, which of their files are missing on the disk or have another checksum, which documents of today the restore would remove (their files stay in the folder), and which devices, keys and links it would bring back to life: a backup does not know what you withdrew after it was made. Download, delete and restore ask for the operator's password again. A restore keeps the state before it as a backup; if it cannot be put in place at the restart, the staged files are put aside, you are told, and the server goes on with the database it had. Moving to a new server: download a backup, upload it on the new one, check it, restore it, and copy the documents folder along.
Every file has a checksum. Once a week, and on a click (Settings, Backups, "Check files"), nexpaper reads them all in small portions with pauses and compares. A document whose file is missing or changed gets a warning sign in the archive, the inbox and on its page, a line in its history, and the operator a notice. The sign goes at the next check, or at once when the operator asks for that one document on its page, when a new version of it was read, when a version that could not be read is put away, or when the document comes back from the trash. The storage card beside it shows what the database (and of it the search index), the documents, the cache, the exports and the backups take, and how much room is left. It warns, here and in the log at the start, when the database lies on a network share.
With an image: docker compose pull && docker compose up -d. Built from source: pull the new code and run
docker compose up -d --build. nexpaper adds what the database lacks at the start and makes a backup first; nothing
needs doing by hand. The way back is under Settings, Backups.
Going back from 1.1.0 to 1.0.1: there, the sign-in through the provider works only if its entry had "The provider checks the second factor itself" on; otherwise only the password does. Coming up to 1.1.0 again brings everything back.
From 1.4.0 on there is no way back to an older version. 1.4.0 changes the database (schema 11 to 13: deadlines, keeping times, reminders; 1.4.1 adds the switch of the kinds, schema 14), and an older nexpaper does not open it: it stops at the start with a message that the database is newer. That includes going back to 1.1.0 or 1.0.1, which was possible until 1.3.0. Make a backup before you update (Settings, Backups; nexpaper also makes one itself before it changes the database). The only way back is to restore that backup with the older version, and what was entered after the update is lost with it. The first start after the update sends no wave of reminders for deadlines that were entered before.
1.5.0 changes the database again (schema 14 to 20: what goes together, saved searches, pins and notes, links with more than one document, remembered PDF passwords, upload requests), so the same holds: back up first, and the way back is only that backup with the older version. After the update nexpaper reads the numbers of the documents that are already there once, in the background; nothing needs doing by hand.
| Variable | Default | Meaning |
|---|---|---|
NEXPAPER_DATA_DIR | /data | Database, logs, backups, secrets and the languages |
NEXPAPER_LOCALES_DIR | <data>/locales | Extra languages, one JSON file each |
NEXPAPER_SECRET_KEY | made on first start | Protects server-side secrets; when set, it wins over secret.key |
NEXPAPER_PUBLIC_URL | from the request | The address people use, for invitation links and the redirect address of the sign-in providers. The setting in the interface wins |
NEXPAPER_TRUSTED_PROXIES | none | Addresses or networks of reverse proxies whose X-Forwarded-For and X-Forwarded-Proto are believed, comma separated |
NEXPAPER_SETUP_TOKEN | made at start | The code the first account needs |
NEXPAPER_OPERATOR_NETWORKS | none | Networks the operator's settings may be changed from, comma separated |
NEXPAPER_SESSION_DAYS | 30 | A session of "stay signed in on this device" ends after this many days without use |
NEXPAPER_COOKIE_SECURE | auto | on, off or auto (from the request, or X-Forwarded-Proto of a trusted proxy) |
NEXPAPER_COOKIE_SUFFIX | none | Appended to the cookie names; keeps two instances on one host apart |
NEXPAPER_LOG_LEVEL | stored setting | quiet, normal, detailed or trace; overrides the setting |
NEXPAPER_DECODE_SLOTS | 1 | How many pictures are unpacked at the same moment (each takes some 150 MB while open) |
NEXPAPER_UPDATE_URL | GitHub | Where the update check asks for the newest release |
NEXPAPER_ARGON2_TIME, NEXPAPER_ARGON2_MEMORY_KIB, NEXPAPER_ARGON2_PARALLELISM | 3, 65536, 2 | Cost of the password hash; only the tests lower it |
NEXPAPER_FRONTEND_DIST | /app/static | Where the built interface lies (set by the image) |
NEXPAPER_DISABLE_BACKGROUND | false | Switches off the background jobs (the log, backups, tidying up, the queue, checking the files, the inputs); for tests. The update check is none of them: it asks only when somebody opens the about page and the last answer is older than a day |
NEXPAPER_PORT | 8000 | The port inside the container; only for host networking |
PUID, PGID | 1000 | Owner of the files in the data directory |
TZ | The time zone of the container's log. People's own time zones come from their browsers |
The full README is on GitHub: https://github.com/DerKezorm/nexpaper#readme
Content type
Image
Digest
sha256:c62a330f0…
Size
173.9 MB
Last updated
1 day ago
docker pull derkezorm/nexpaper