Systemd

In this installation method you use a special papermerge command startetc to generate a bunch of configuration files in <papermerge-proj>/run/etc folder. Then only with one single command:

systemctl --user start papermerge

you start a full fledged staging environment with nginx, gunicorn, one worker and recurring commands running as services on a single machine. I really love this method and I use in my local development environment. This method relies on systemd and its --user argument.

Package Dependencies

You will need to install os specific packages for webapp + worker first. Then make sure that PostreSQL is up and running.

Make sure that your machine has both nginx and systemd available:

nginx -V
systemd --version

Web App

Clone main papermerge project:

git clone https://github.com/ciur/papermerge papermerge-proj

Clone papermerge-js project (this is the frontend part):

git clone https://github.com/ciur/papermerge-js

Create python’s virtual environment .env:

cd papermerge-proj
python3 -m venv .venv

Activate python’s virtual environment:

source .venv/bin/activate

Install required python packages (now you are in papermerge-proj directory):

# while in <papermerge-proj> folder
pip install -r requirements.txt

Rename file config/settings/development.example.py to config/settings/development.py. This file is default for DJANGO_SETTINGS_MODULE and it is included in .gitignore.

Adjust following settings in config/settings/development.py:

  • DATABASES - name, username and password of database you created in PostgreSQL
  • MEDIA_ROOT - absolute path to media folder
  • STORAGE_ROOT- absolute path to same media root, but with a “local:/” prefix

Note

  1. Make sure that data_folder_in and data_folder_out point to the same location.
  2. Make sure that folder pointed by data_folder_in and data_folder_out exists.

Then, as in any django based project, run migrations and create super user:

cd <papermerge-proj>
./manage.py migrate
./manage.py createsuperuser

Run startetc command:

./manage.py startetc

Just out of curiousity, have a look <papermerge-proj>/run at folder generated by startetc command. Folder <papermerge-proj> should have following structure:

run
├── broker
│   ├── data_in
│   ├── data_out
│   └── data_processed
├── etc
│   ├── gunicorn.conf.py
│   ├── nginx.conf
│   ├── papermerge.env
│   ├── pmworker.env
│   ├── pmworker.py
│   └── systemd
│       ├── papermerge.service
│       ├── papermerge.target
│       ├── pm_nginx.service
│       ├── pmworker.service
│       ├── txt2db.service
│       ├── txt2db.timer
│       ├── update_fts.service
│       └── update_fts.timer
├── log
└── tmp

Systemd can be used to manage user services. For that –user flag is used. User services must be referenced in ~/.config/systemd/user folder. By the way, I made a video about systemd –user feature.

Create ~/.config/systemd/user if you don’t have it. Then reference (create symbolic links) <papermerge-proj>/run/etc/systemd/ units in ~/.config/systemd/user folder:

cd ~/.config/systemd/user
ln -s <papermerge-proj>/run/etc/systemd/* .

Important

Path <papermerge-proj>/run/etc/systemd/* must be absolute.

Start papermerge:

systemctl --user start papermerge.target