Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
PAPERLESS(7)	   FreeBSD Miscellaneous Information Manual	  PAPERLESS(7)

     paperless -- Index	and archive scanned paper documents - installation

     pkg install py37-paperless

     Paperless is a simple Django application running in two parts: The	con-
     sumer, which does the indexing and	a web interface, which allows search-
     ing and downloading already-indexed documents.

     This man page documents how the FreeBSD FreeBSD port is installed and
     configured.  It assumes that the paperless	package	was already installed,
     e.g., from	the FreeBSD FreeBSD package repo as described in SYNOPSIS.

     For more information about	using paperless, see "the official paperless
     documentation" (file://usr/local/share/doc/paperless/index.html or

     The package creates a symlink from
     /usr/local/lib/python3.7/site-packages/paperless/	to
     /usr/local/bin/paperless for convenience reasons, so whenever the offi-
     cial documentation	mentions it can be substituted with
     /usr/local/bin/paperless or simply	paperless.

     Paperless always needs to be run using the	correct	system user and	an
     UTF-8 codepage.

     The package py37-paperless	created	a user paperless with the following
     home directory layout, setting appropriate	restrictive access permis-

	   home	directory (only	writeable by root)
	   consume/  Consume directory writable	by root, used as chroot	direc-
		     tory for sftp access (see below).
			  Input	files are dropped in there to be processed by
			  the paperless	document consumer - either directly or
			  via a	mechanism like sftp.
	   media/    Directory used by paperless to store original files and
	   sqlite/   Contains paperless' SQLite	database.

     In	case documents should be PGP encrypted,	PAPERLESS_PASSPHRASE needs to
     be	configured in /usr/local/etc/paperless.conf first.

     Also, PAPERLESS_OCR_THREADS can be	tuned in the same configuration	file
     to	limit the impact on system performance.

     To	use paperless, the consumer is enabled

	   sysrc paperless_consumer_enable=YES

     and subsequently started

	   service paperless-consumer start

     (which also creates/updates the paperless SQLite database).

     Therefore,	restarting the consumer	after updates

	   service paperless-consumer restart

     updates the database before starting the new program version.

     Before using the web ui, make sure	to create a super user and assign a

	   su -l paperless -c '/usr/local/bin/paperless	createsuperuser'

     It	is recommended to host the web component using a real web server,
     e.g., nginx + uwsgi.

     Install and configure uwsgi:

	   pkg install uwsgi
	   mkdir -p /usr/local/etc/uwsgi

	   R] .ne 2 Start the uwsgi process:
	   R] .ne 2
	   R] .ne 2 Install nginx:
	   R] .ne 2
	   R] .ne 2 Create a basic server configuration	( doc-arg-limit] .ds
	   doc-macro-name Pa $]	.nop doc-Pa-font]~] doc-arg-limit] .return ),
	   example snippet:
	   R] .ne 2
	   R] .ne 2 Enable and start nginx:
	   R] .ne 2
	   R] .ne 2 doc-arg-limit] .ie 0.$] .ds	doc-macro-name Em doc-arg-
	   limit] .return doc-arg-limit] .ie 0.$] .ds doc-macro-name Em	doc-
	   arg-limit] .return $] .tm Usage: .Sh	section_name ... (#0.c]) c-
	   macro-name Sh.if t .ad

     Setting up	sftp enabled direct upload of files to be processed by the pa-
     perless consumer.	Some scanners allow configuring	sftp with key based
     authentication, which is convenient as it scans directly to the paperless
     processing	pipeline.

     In	case paperless is using	a dedicated instance of	sshd(8), access	can be
     limited to	the paperless user by adding these lines to

	   # Only include if sshd is dedicated to paperless
	   # otherwise you'll lock yourself out
	   AllowUsers paperless

     The following block limits	the paperless user to using the	sftp(1)	proto-
     col and locks it into the consume directory:

	   # paperless can only	do sftp	and is dropped into correct directory
	   Match User paperless
		ChrootDirectory	%h/consume
		ForceCommand internal-sftp -u 0077 -d /input
		AllowTcpForwarding no
		X11Forwarding no
		PasswordAuthentication no

     The public	keys of	authorized users/devices need to be added to

	   mkdir -p /var/db/paperless/.ssh
	   cat path/to/pubkey >>/var/db/paperless/.ssh/authorized_keys

     Make sure sshd(8) is enabled and restart (or reload) it:

	   sysrc sshd_enable=YES
	   service sshd	restart

     The user will be dropped into the correct directory, so uploading a file
     is	as simple as:

	   echo	put file.pdf | sftp -b - paperless@host

     /usr/local/etc/paperless.conf  See	self-documented
				    /usr/local/etc/paperless.conf.sample for
				    Official documentation for the version in-
				    Presentation of the	motivation for and
				    technology behind paperless.
				    Configuration examples, complementary to
				    this man page.

     sftp(1), sshd_config(5), ports(7),	daemon(8), service(8), sysrc(8)

     Official paperless	documentation.

     This manual page was written by Michael Gmelin <>.

FreeBSD	13.0			January	3, 2020			  FreeBSD 13.0


Want to link to this manual page? Use this URL:

home | help