Enhancement: allow paperless to run in read-only filesystem

[hegerdes]

Proposed change

Closes #4020

Type of change

• Bug fix: non-breaking change which fixes an issue.
• New feature / Enhancement: non-breaking change which adds functionality. Please read the important note above.
• Breaking change: fix or feature that would cause existing functionality to not work as expected.
• Documentation only.
• Other. Please explain:

Checklist:

• I have read & agree with the contributing guidelines.
• If applicable, I have included testing coverage for new code in this PR, for backend and / or front-end changes.
• If applicable, I have tested my code for new features & regressions on both mobile & desktop devices, using the latest version of major browsers.
• If applicable, I have checked that all tests pass, see documentation.
• I have run all pre-commit hooks, see documentation.
• I have made corresponding changes to the documentation as needed.
• I have checked my modifications for any breaking changes.

What changed

Currently it is not possible to run paperless-ngx in a read-only filesystem/container. On startup is writes supervisord log and pid's in the projects source files. Python also writes binary cache files in the __pycache__ folder. The creation of the __pycache__ folder can be disabled or changed. One way is to set the PYTHONPYCACHEPREFIX environment variable. All persistent data stores can also either be changed via env's and most people use volume or bind mounts.

For additional security and for idempotence you might want to run the container in read-only to prevent any unwanted changes. This PR enables it by also allowing to change supervisord log and pid file location via the PAPERLESS_SUPERVISORD_WORKING_DIR env.

Example:

version: "3.4"
services:
  webserver:
    image: ghcr.io/paperless-ngx/paperless-ngx:latest
    read_only: true                                                      # what we primary want
    user: paperless                                                      # need the paperless user
    depends_on:
      - broker
    ports:
      - "8000:8000"
    volumes:
      - tmp:/tmp
      - data:/usr/src/paperless/data
      - media:/usr/src/paperless/media
      - ./export:/usr/src/paperless/export
      - ./consume:/usr/src/paperless/consume
    env_file: docker-compose.env
    environment:
      PAPERLESS_REDIS: redis://broker:6379
      PAPERLESS_SUPERVISORD_WORKING_DIR: /tmp                            # supervisord
      PYTHONPYCACHEPREFIX: /tmp/pycache                                  # py-cache
      PAPERLESS_ADMIN_USER: "admin"
      PAPERLESS_ADMIN_PASSWORD: "geheim"

volumes:
  data:
  media:
  tmp:
```

[paperless-ngx-secretary]

Hello @hegerdes,

thank you very much for submitting this PR to us!

This is what will happen next:

1. My robotic colleagues will check your changes to see if they break anything. You can see the progress below.
2. Once that is finished, human contributors from paperless-ngx review your changes. Since this seems to be a small change, only a single contributor has to review your changes.
3. Please improve anything that comes up during the review until your pull request gets approved.
4. Your pull request will be merged into the dev branch. Changes there will be tested further.
5. Eventually, changes from you and other contributors will be merged into main and a new release will be made.

Please allow up to 7 days for an initial review. We're all very excited about new pull requests but we only do this as a hobby.
If any action will be required by you, please reply within a month.

[stumpylog]

This seems highly specific and not much upvoted. What is the purpose?

[hegerdes]

This seems highly specific and not much upvoted. What is the purpose?

Mixing code, user-data and runtime data (logs, pids) in a single directory can lead to unintended effects. Having the option to separate them makes deployments way more flexible.
Running it all on a read-only filesystem does improve security a little (if you have been compromised, that is one of the minor problems), but much more impotent it prevents unwanted changes and configuration shift. You can be sure that container behaves always the same.

I have no problem you want to make this an undocumented/unsupported feature. The shell script behaves exactly the same if PAPERLESS_SUPERVISORD_WORKING_DIR is not set. Then is defaults to the CWD which is just like the old path

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Comparison is base (4540986) 96.57% compared to head (bac9d43) 96.49%.
Report is 1 commits behind head on dev.

❗ Current head bac9d43 differs from pull request most recent head 3b8205f. Consider uploading reports for the commit 3b8205f to get more accurate results

Additional details and impacted files

@@            Coverage Diff             @@
##              dev    #5596      +/-   ##
==========================================
- Coverage   96.57%   96.49%   -0.09%     
==========================================
  Files         401      400       -1     
  Lines       15829    15729     -100     
  Branches     1227     1203      -24     
==========================================
- Hits        15287    15177     -110     
- Misses        538      548      +10     
  Partials        4        4              

Flag	Coverage Δ
backend	95.21% <ø> (-0.23%)	⬇️
frontend	98.01% <ø> (+0.07%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[github-actions]

This pull request has been automatically locked since there has not been any recent activity after it was closed. Please open a new discussion or issue for related concerns. See our contributing guidelines for more details.