HUB
Sign inSign up

derkezorm/nexpaper

By derkezorm

•Updated 1 day ago

A light filing cabinet for a household or a small firm: OCR, search, vaults, Paperless-ngx import.

Image
0

2.1K

derkezorm/nexpaper repository overview

⁠nexpaper

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.

  • One inbox for everything. Photos from the phone, files from the browser, a scanner's folder, a mailbox, an import from Paperless: all of it waits in the inbox with the fields filled in, and one click files it.
  • Vaults. Everybody has a vault of their own, and the operator makes shared ones ("Household", "Business"). Rights are read, edit or manage; single documents can also be shared with a person or, for somebody without an account, as a link that ends.
  • Text recognition and search. Scans become searchable PDFs; the original stays exactly as it came, with its checksum. The search understands parts of words and filters (kind:invoice amount:>100).
  • Tools for pages. Turn, delete and order pages, join documents, split a stack at blank separator sheets. Every change is a new version; nothing is overwritten.
  • What goes together. nexpaper reads the invoice, order and delivery note numbers of a paper and proposes the delivery note that goes with an invoice. Connected documents show each other, and a link to the outside or the export can take them along.
  • Small helpers. The archive adds up the amounts of what it shows and changes several documents at once, a search can be saved to the side bar, a transfer code fills in the banking app, a note on a sender keeps the customer number at hand, and a PDF with a password is opened once and read like any other.
  • Deadlines and reminders. What has to be paid, cancelled or claimed under a warranty stands on one page, with the last day to cancel worked out from the notice period. nexpaper reminds the people who may edit the vault, by push, by mail or in a weekly overview, each reminder once.
  • Keeping times. A kind can say how many years its documents are kept. When the time is over the document shows up in the archive under "May go". Nothing is deleted by itself; a kind can ask nexpaper to put its expired documents in the trash once a day, at night (off from the start, they stay there for 30 days).
  • For small firms. E-invoices (ZUGFeRD, Factur-X, XRechnung) are read from their data, there is a history of who changed what, and an export for the tax adviser (a ZIP with the PDFs and a list). No claim of GoBD compliance.
  • No Redis, no Celery, no Postgres. One container, SQLite, plain readable files on the disk.
  • Best kept at home. nexpaper is meant for your own network; from on the way, reach it through a VPN. It still comes with a second factor from the start, passkeys, sign-in through your own provider and a checklist in the settings. Everything the web app does goes through an open API (/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 archive: documents by month, with sender, kind and amount

The inbox with proposalsA document with its fields, notes and history
Vaults and who may do whatThe quick upload on a phone

The pictures show a made-up household.

⁠Start

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.

⁠Reaching nexpaper from outside

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:

  1. Set it up first, from your own network, with the setup code from the log. Only then forward a port.
  2. https at a reverse proxy, and nexpaper reachable only through it: publish the port as 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.
  3. Tell nexpaper about 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".
  4. A second factor is required from the start: right after the password every account sets one up (a code from an app, or a passkey) and keeps the recovery codes. The operator may switch the requirement off; do not.
  5. Look at "Ready for the internet?" (Settings, Sign-in). It checks the points above for itself: https, the second factor, your own account with one, the brake, the server secrets, the cookies, the proxy and the backups.
  6. Backups somewhere else, as carefully as the data folder. A backup holds every account and the server's secrets (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.
  7. Leave the switches closed that you do not need: API keys, upload requests and the AI are off until the operator opens them. Pin a version instead of 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⁠).
  8. Nobody, the operator included, sets a password for somebody else. Whoever forgot theirs gets a link to set a new one: the operator sends it (Settings, Accounts), or, where a mail server and the public address are set, the person asks for it on the sign-in page. The link works once and for 24 hours. An operator without a mail server who forgot their own password makes one in the container (below).
  9. Passkeys work under the public https address, or on localhost.

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).

⁠Sign-in with a provider

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.

  • authentik in one step: give the address of authentik and an API token that may create applications; nexpaper sets up provider and application there and enters them here. The token is used for that run only and never stored. Who would rather not hand out a token downloads the blueprint instead and enters client ID and secret by hand.
  • By hand: "Add a provider" asks for the name on the button, a short name (part of the redirect address 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.
  • Who comes in: an identity is known by its provider and its subject only, never by its mail address. An account links itself on its own page (Security, with its password); new people come in by invitation, or, where the operator switches "New people get an account" on for a provider, as members. Everybody gets a vault of their own.
  • Addresses from a provider are shown and can be taken, but they are never confirmed by that alone: a mail to the intake counts only for an address the person confirmed by the link nexpaper sends. An address 1.0.1 took from the provider as confirmed waits for that link once after the update (My account, Profile); it needs the mail server.
  • The second factor: "The provider checks the second factor itself" is on for a new provider. Off, whoever has a second factor in nexpaper is asked for its code after the provider. "Require a second factor" is for signing in with a password: an account without a password, and whoever comes in through a provider whose entry has "The provider checks the second factor itself" on, is not made to set one up (a change from 1.0.1). Device tokens and API keys of an account with a password and no second factor of its own wait until it sets one up, also when it signs in through a provider that checks one.
  • Password sign-in can go off once a provider is active; the operator can always sign in with the password.

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.

⁠Forgot your password, and no mail server

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.

⁠Where things are stored

Everything lives in /data:

WhereWhat
nexpaper.dbThe SQLite database: accounts, settings, the filing, the recognised text and the search index.
secret.keyThe 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.

⁠Backup

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.

⁠Checking the files, and the storage card

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.

⁠Updating

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.

⁠Environment

VariableDefaultMeaning
NEXPAPER_DATA_DIR/dataDatabase, logs, backups, secrets and the languages
NEXPAPER_LOCALES_DIR<data>/localesExtra languages, one JSON file each
NEXPAPER_SECRET_KEYmade on first startProtects server-side secrets; when set, it wins over secret.key
NEXPAPER_PUBLIC_URLfrom the requestThe address people use, for invitation links and the redirect address of the sign-in providers. The setting in the interface wins
NEXPAPER_TRUSTED_PROXIESnoneAddresses or networks of reverse proxies whose X-Forwarded-For and X-Forwarded-Proto are believed, comma separated
NEXPAPER_SETUP_TOKENmade at startThe code the first account needs
NEXPAPER_OPERATOR_NETWORKSnoneNetworks the operator's settings may be changed from, comma separated
NEXPAPER_SESSION_DAYS30A session of "stay signed in on this device" ends after this many days without use
NEXPAPER_COOKIE_SECUREautoon, off or auto (from the request, or X-Forwarded-Proto of a trusted proxy)
NEXPAPER_COOKIE_SUFFIXnoneAppended to the cookie names; keeps two instances on one host apart
NEXPAPER_LOG_LEVELstored settingquiet, normal, detailed or trace; overrides the setting
NEXPAPER_DECODE_SLOTS1How many pictures are unpacked at the same moment (each takes some 150 MB while open)
NEXPAPER_UPDATE_URLGitHubWhere the update check asks for the newest release
NEXPAPER_ARGON2_TIME, NEXPAPER_ARGON2_MEMORY_KIB, NEXPAPER_ARGON2_PARALLELISM3, 65536, 2Cost of the password hash; only the tests lower it
NEXPAPER_FRONTEND_DIST/app/staticWhere the built interface lies (set by the image)
NEXPAPER_DISABLE_BACKGROUNDfalseSwitches 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_PORT8000The port inside the container; only for host networking
PUID, PGID1000Owner of the files in the data directory
TZThe 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⁠

Tag summary

Content type

Image

Digest

sha256:c62a330f0…

Size

173.9 MB

Last updated

1 day ago

docker pull derkezorm/nexpaper