Skip to content

Drop folder

A folder Arca watches: each PDF or photo you put there becomes a draft in To validate, its type guessed and its values read, as if you had used Quick add. Nothing is saved before you validate it. Off by default.

Useful with a scanner or a printer that saves to a network folder, with photos synced from a phone, or with the PDFs you download.

Turning it on

Arca needs write access to the folder: it removes each file it takes and moves the ones it refuses. In Docker, Arca runs as the user with uid 1000: the folder must be writable by it (chown 1000:1000, or a group it is in). Without write access nothing is taken, and the Integrity page says why.

With Docker, in .env:

ARCA_INBOX_DIR=/inbox

In compose.yaml, uncomment the folder's mount (- /srv/scans:/inbox) in both the arca and inbox services, with your folder in place of /srv/scans: Arca itself needs the folder too (a draft's file goes back to it, see below). Then start the inbox service, which scans the folder every minute:

docker compose --profile inbox up -d

Pass --profile inbox to every docker compose command that should include it (pull, up), or add COMPOSE_PROFILES=inbox to .env (ai,inbox with the AI gateway). Started without ARCA_INBOX_DIR, the service says so once in its log and waits, doing nothing. When files wait in the folder and it has not been scanned for 10 minutes, the Integrity page warns: the service is probably not started.

From the sources, set ARCA_INBOX_DIR to the folder, then run uv run manage.py inbox --watch as a service, or uv run manage.py inbox (one scan) every minute from cron.

What happens to a file

  • A file is taken once it has not changed for one minute (same size and modification time over two scans), so a file still being copied is left alone. A copy that stalls for more than a minute without changing could be taken early, incomplete: copy to a temporary name (.part, .tmp) and rename at the end, as most sync tools do.
  • Accepted: PDF, JPEG, PNG, WebP and HEIC, up to the upload limit (ARCA_MAX_UPLOAD_MB). Only the top level of the folder is read; subfolders, hidden files (.name) and temporary files (~$name, .part, .tmp) are ignored.
  • Refused files are moved to a refused subfolder, never deleted, with a name.why.txt file beside each one giving the reason in English and French: another type, too large, unreadable, or the same file already waiting in To validate or already in Arca.
  • A file that fails for another reason (a reading error, a full disk) is put back in the folder and tried again one hour later.
  • At most 100 drafts from the folder wait at once: beyond, files stay in the folder until you validate or reject some.
  • A draft not handled within 30 days is dropped and its file goes back to refused. After a backup is restored, the files of drop-folder drafts the restored data does not know also go back to refused (files sent through the API do not).
  • Arca's log names the files it handles, never what they contain.

The guess

Arca reads the text of the PDF, or the photo with Tesseract, then picks the type by the words it finds (tax notice, rent receipt, energy contract…). For a photo, a machine-readable zone (the <<< lines) means an identity document. Scanned PDFs, without text, are read like photos, their first 10 pages only (also in Quick add, by Fill in from the document). Nothing clear: Other document.

The guess can be wrong: on the draft, choose another Type of document and the form of that type shows, with what was read in the same file placed for it. Keep the file as a document of the record, ticked by default, attaches the file to the record; unticked, only the values are saved and the file is deleted with the draft. See To validate.

HEIC photos are accepted but not read: the draft opens as Other document, to fill in by hand. On an iPhone, Settings › Camera › Formats › Most Compatible takes JPEG photos instead.

Recipes

A network share (NAS, scanner). Mount the share on the Docker host, then mount that folder on /inbox. With NFS, prefer the soft option with timeouts (soft,timeo=100,retrans=3): a hard mount of a server that stops answering blocks, until it comes back, Arca's start (it checks the folder), the Integrity page and the drafts. A soft mount returns read or write errors instead, which Arca handles by trying again later. A local folder kept in sync avoids both.

# /etc/fstab
<nas>:/scans  /srv/scans  nfs  soft,timeo=100,retrans=3  0  0

Photos from a phone (Syncthing). Share a phone folder with a Syncthing folder on the server (/srv/scans), mounted on /inbox. Syncthing writes under hidden temporary names, which Arca ignores. In two-way sync, a photo Arca takes disappears from the phone too; to keep the phone's copy, make the phone's folder Send Only.

A local folder. For downloads or a desktop scanner:

sudo mkdir -p /srv/scans
sudo chown 1000:1000 /srv/scans