.\"
.\" Copyright (c) 2019 Michael Gmelin
.\"
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.\" $FreeBSD: head/deskutils/py-paperless/files/paperless.7.in 548839 2020-09-17 12:04:40Z grembo $
.\"
.Dd September 17, 2020
.Dt PAPERLESS 7
.Os
.Sh NAME
.Nm paperless
.Nd Index and archive scanned paper documents - installation
.Sh SYNOPSIS
.Nm pkg install %%PKGBASE%%
.Sh DESCRIPTION
.Em Paperless
is a simple Django application running in two parts: The consumer,
which does the indexing and a web interface, which allows searching
and downloading already-indexed documents.
.Pp
This man page documents how the
.Fx FreeBSD
port is installed and configured.
It assumes that the paperless package was already installed, e.g., from the
.Fx FreeBSD
package repo as described in
.Sx SYNOPSIS .
.Pp
For more information about using paperless, see
.Dq the official paperless documentation
.Pa ( file:/%%DOCSDIR%%/index.html
or
.Pa https://paperless.readthedocs.io ) .
.Pp
The package creates a symlink from
.Pa %%PYTHONPREFIX_SITELIBDIR%%/paperless/manage.py
to
.Pa %%PREFIX%%/bin/paperless
for convenience reasons, so whenever the official
documentation mentions
.Em manage.py
it can be substituted with
.Pa %%PREFIX%%/bin/paperless
or simply
.Pa paperless .
.Pp
.Em Paperless always needs to be run using the correct system user
and an UTF-8 codepage.
.Pp
The package %%PKGBASE%% created a user
.Em paperless
with the following home directory layout, setting appropriate
restrictive access permissions:
.Bl -tag -width "/var"
.It Pa /var/db/paperless
home directory (only writeable by root)
.Bl -tag -width "consume/" -compact
.It Pa consume/
Consume directory writable by root, used as chroot directory
for sftp access (see below).
.Bl -tag -width "123" -compact
.It Pa input/
Input files are dropped in there to be processed by the
paperless document consumer - either directly or via
a mechanism like sftp.
.El
.It Pa media/
Directory used by paperless to store original files and
thumbnails.
.It Pa sqlite/
Contains paperless' SQLite database.
.El
.El
.Sh CONSUMER SETUP
In case documents should be PGP encrypted,
.Va PAPERLESS_PASSPHRASE
needs to be configured in
.Pa %%PREFIX%%/etc/paperless.conf
first.
.Pp
Also,
.Va PAPERLESS_OCR_THREADS
can be tuned in the same configuration file to limit
the impact on system performance.
.Pp
To use paperless, the consumer is enabled
.Bd -literal -offset indent
sysrc paperless_consumer_enable=YES
.Ed
.Pp
and subsequently started
.Bd -literal -offset indent
service paperless-consumer start
.Ed
.Pp
(which also creates/updates the paperless SQLite database).
.Pp
Therefore, restarting the consumer after updates
.Bd -literal -offset indent
service paperless-consumer restart
.Ed
.Pp
updates the database before starting the new program version.
.Sh WEB UI SETUP
Before using the web ui, make sure to create a super user and assign
a password
.Bd -literal -offset indent
su -l paperless -c '%%PREFIX%%/bin/paperless createsuperuser'
.Ed
.Pp
It is recommended to host the web component using a real
web server, e.g., nginx + uwsgi.
.Pp
Install and configure uwsgi:
.Bd -literal -offset indent
pkg install uwsgi
mkdir -p %%PREFIX%%/etc/uwsgi
cp %%EXAMPLESDIR%%/uwsgi.ini \\
    %%PREFIX%%/etc/uwsgi/paperless.ini
sysrc uwsgi_enable=YES
sysrc uwsgi_profiles+=paperless
sysrc uwsgi_paperless_socket_owner=paperless:www
sysrc uwsgi_paperless_uid=paperless
sysrc uwsgi_paperless_gid=paperless
sysrc uwsgi_paperless_configfile=%%PREFIX%%/etc/uwsgi/paperless.ini
.Ed
.Pp
Start the uwsgi process:
.Bd -literal -offset indent
service uwsgi start paperless
.Ed
.Pp
Install nginx:
.Bd -literal -offset indent
pkg install nginx
.Ed
.Pp
Create a basic server configuration (
.Pa %%PREFIX%%/etc/nginx/nginx.conf
), example snippet:
.Bd -literal -offset indent
server {
    listen 80;
    server_name localhost;

    location /static/ {
        alias %%WWWDIR%%/static/;
    }

    location / {
        uwsgi_pass unix:/tmp/uwsgi-paperless.sock;
        include uwsgi_params;
    }

    error_page   500 502 503 504  /50x.html;
    location = /50x.html {
        root   %%PREFIX%%/www/nginx-dist;
    }
}
.Ed
.Pp
Enable and start nginx:
.Bd -literal -offset indent
sysrc nginx_enable=YES
service nginx start
.Ed
.Pp
.Em \In a real world setup, nginx should be configured to use TLS
.Em and (potentially) client certificates .
.Sh SFTP SETUP
Setting up
.Em sftp
enabled direct upload of files to be processed by the paperless
consumer.
Some scanners allow configuring sftp with key based authentication,
which is convenient as it scans directly to the paperless processing
pipeline.
.Pp
In case paperless is using a dedicated instance of
.Xr sshd 8 ,
access can be limited to the paperless user by adding
these lines to
.Pa /etc/ssh/sshd_config :
.Bd -literal -offset indent
# Only include if sshd is dedicated to paperless
# otherwise you'll lock yourself out
AllowUsers paperless
.Ed
.Pp
The following block limits the paperless user to using the
.Xr sftp 1
protocol and locks it into the consume directory:
.Bd -literal -offset indent
# 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
.Ed
.Pp
The public keys of authorized users/devices need to be added to
.Pa /var/db/paperless/.ssh/authorized_keys :
.Bd -literal -offset indent
mkdir -p /var/db/paperless/.ssh
cat path/to/pubkey >>/var/db/paperless/.ssh/authorized_keys
.Ed
.Pp
Make sure
.Xr sshd 8
is enabled and restart (or reload) it:
.Bd -literal -offset indent
sysrc sshd_enable=YES
service sshd restart
.Ed
.Pp
The user will be dropped into the correct directory, so uploading
a file is as simple as:
.Bd -literal -offset indent
echo put file.pdf | sftp -b - paperless@host
.Ed
.Sh FILES
.Bl -tag -width ".Pa %%PREFIX%%/etc/paperless.conf" -compact
.It Pa %%PREFIX%%/etc/paperless.conf
See self-documented
.Pa %%PREFIX%%/etc/paperless.conf.sample
for example.
.It Pa %%DOCSDIR%%/index.html
Official documentation for the version installed.
.It Pa %%DOCSDIR%%/presentation/index.html
Presentation of the motivation for and technology behind paperless.
.It Pa %%EXAMPLESDIR%%
Configuration examples, complementary to this man page.
.El
.Sh SEE ALSO
.Xr sftp 1 ,
.Xr sshd_config 5 ,
.Xr ports 7 ,
.Xr daemon 8 ,
.Xr service 8 ,
.Xr sysrc 8
.Pp
.Rs
.%B "Official paperless documentation"
.Re
.Pp
.Pa https://paperless.readthedocs.io
.Sh AUTHORS
.An -nosplit
This manual page was written by
.An Michael Gmelin Aq Mt grembo@FreeBSD.org .