MrGeneration / Backup Paperless NGX with restic

# The UID and GID of the user used to run paperless in the container. Set this # to your UID and GID on the host so that you have write access to the # consumption directory. USERMAP_UID=1001 USERMAP_GID=1001 # Database credentials POSTGRES_DB=paperless POSTGRES_USER=paperless POSTGRES_PASSWORD=paperless PAPERLESS_DBHOST=paperless-ngx-db PAPERLESS_DBNAME=$POSTGRES_DB PAPERLESS_DBUSER=$POSTGRES_USER PAPERLESS_DBPASS=$POSTGRES_PASSWORD # Additional languages to install for text recognition, separated by a # whitespace. Note that this is # different from PAPERLESS_OCR_LANGUAGE (default=eng), which defines the # language used for OCR. # The container installs English, German, Italian, Spanish and French by # default. # See https://packages.debian.org/search?keywords=tesseract-ocr-&searchon=names&suite=buster # for available languages. PAPERLESS_OCR_LANGUAGES=deu fra eng nld ############################################################################### # Paperless-specific settings # ############################################################################### # All settings defined in the paperless.conf.example can be used here. The # Docker setup does not use the configuration file. # A few commonly adjusted settings are provided below. # This is required if you will be exposing Paperless-ngx on a public domain # (if doing so please consider security measures such as reverse proxy) PAPERLESS_URL=https://paperless.domain.tld # Adjust this key if you plan to make paperless available publicly. It should # be a very long sequence of random characters. You don't need to remember it. PAPERLESS_SECRET_KEY=GENERATEME # Use this variable to set a timezone for the Paperless Docker containers. If not specified, defaults to UTC. PAPERLESS_TIME_ZONE=Europe/Berlin # The default language to use for OCR. Set this to the language most of your # documents are written in. PAPERLESS_OCR_LANGUAGE=deu # Set if accessing paperless via a domain subpath e.g. https://domain.com/PATHPREFIX and using a reverse-proxy like traefik or nginx #PAPERLESS_FORCE_SCRIPT_NAME=/PATHPREFIX #PAPERLESS_STATIC_URL=/PATHPREFIX/static/ # trailing slash required PAPERLESS_CONSUMER_ENABLE_BARCODES=true PAPERLESS_OCR_USER_ARGS= '{"continue_on_soft_render_error": true, "invalidate_digital_signatures": true}' PAPERLESS_USE_X_FORWARD_HOST=true PAPERLESS_CONSUMER_POLLING=10 PAPERLESS_CONSUMER_POLLING_RETRY_COUNT=5 PAPERLESS_CONSUMER_POLLING_DELAY=20 PAPERLESS_ADMIN_USER=MyAmazingAdmin PAPERLESS_ADMIN_MAIL=alias@domain.tld PAPERLESS_ADMIN_PASSWORD="SuperSecure!" PAPERLESS_EMAIL_HOST=mail.domain.tld PAPERLESS_EMAIL_PORT=587 PAPERLESS_EMAIL_HOST_USER=paperless@domain.tld PAPERLESS_EMAIL_HOST_PASSWORD="SuperSecureToo!" PAPERLESS_EMAIL_USE_TLS=false PAPERLESS_EMAIL_USE_SSL=true

Last change: 2025-09-25 Marcel Herrguth As shown on https://youtu.be/P-Pr7Dy6mP8 Attribution back to this GIST is required! Parts of this script are oriented from https://github.com/zammad/zammad/tree/develop/contrib/backup This script supports PostGreSQL (docker) stacks only and expects your media to be in a mounted folder. Restoration only works on a pre-installed Paperless NGX installation of the same version (or higher). During Restore, this script will remove the existing database and stop all relevant containers. Containers will be re-started after the restoration finished. COMMAND REFERENCE - backup: creates a new snapshot and backs up database and storage. - restore <snapshot>: Restore a given snapshot from your backup. If you omit the snapshot ID, latest will be used. - list_snapshots: List all available snapshot IDs. - verify_health <percentage>: Verify the health of your backup repository. If you omit percentage, 100% will be assumed.

services: paperless-ngx-broker: image: docker.io/library/redis:8.2-alpine container_name: paperless-ngx-broker hostname: paperless-ngx-broker restart: always networks: - paperless-ngx volumes: - ./data/redis:/data paperless-ngx-db: image: docker.io/library/postgres:17-alpine container_name: paperless-ngx-db hostname: paperless-ngx-db restart: always networks: - paperless-ngx volumes: - ./pg:/var/lib/postgresql/data paperless-ngx-webserver: image: ghcr.io/paperless-ngx/paperless-ngx:2.18.2 restart: always container_name: paperless-ngx-webserver hostname: paperless-ngx-webserver depends_on: - paperless-ngx-db - paperless-ngx-broker - paperless-ngx-gotenberg - paperless-ngx-tika networks: - paperless-ngx - external_network volumes: - ./data/paperless:/usr/src/paperless/data - ./data/media:/usr/src/paperless/media - ./volume/_consume:/usr/src/paperless/consume:z - ./volume/_export:/usr/src/paperless/export:z ports: - "127.0.0.1:8000:8000" env_file: .env environment: PAPERLESS_REDIS: redis://paperless-ngx-broker:6379 PAPERLESS_TIKA_ENABLED: 1 PAPERLESS_TIKA_GOTENBERG_ENDPOINT: http://paperless-ngx-gotenberg:3000 PAPERLESS_TIKA_ENDPOINT: http://paperless-ngx-tika:9998 paperless-ngx-gotenberg: image: docker.io/gotenberg/gotenberg:8.22 restart: always networks: - paperless-ngx container_name: paperless-ngx-gotenberg hostname: paperless-ngx-gotenberg # The gotenberg chromium route is used to convert .eml files. We do not # want to allow external content like tracking pixels or even javascript. # environment: # CHROMIUM_DISABLE_ROUTES: 1 command: - 'gotenberg' - "--chromium-disable-javascript=true" - "--chromium-allow-list=file:///tmp/.*" # - "--chromium-disable-routes=true" # - "--chromium-restart-after=5" # - "--chromium-auto-start=true" # - "--chromium-ignore-certificate-errors=true" # - "--chromium-disable-web-security=true" # - '--chromium-allow-insecure-localhost=true' # - "--chromium-start-timeout=30s" # - "--uno-listener-start-timeout=180s" # - "--libreoffice-disable-routes=false" # - "--libreoffice-auto-start=true" # - "--libreoffice-restart-after=5" # - '--libreoffice-start-timeout=30s' # - '--api-timeout=3000s' paperless-ngx-tika: image: ghcr.io/paperless-ngx/tika:2.9.1-full container_name: paperless-ngx-tika hostname: paperless-ngx-tika restart: always networks: - paperless-ngx networks: paperless-ngx: name: paperless-ngx internal: true external_network: enable_ipv6: true ipam: config: - subnet: fd63:e614:1cf8:fb00::2:0/112 # volumes: # consume: # driver: local # driver_opts: # type: nfs # o: addr=yamato.tha.vpn,nfsvers=4.1,nolock,soft,rw,async # device: :/volume1/import/_consume

#!/usr/bin/env bash # # 2025-09-25 Marcel Herrguth # As shown on https://youtu.be/P-Pr7Dy6mP8 # Attribution back to this GIST is required! # # Parts of this script are oriented from https://github.com/zammad/zammad/tree/develop/contrib/backup # This script supports PostGreSQL (docker) stacks only and expects your media to be in a mounted folder. # # Restoration only works on a pre-installed Paperless NGX installation of the same version (or higher). # During Restore, this script will remove the existing database and stop all relevant containers. # Containers will be re-started after the restoration finished. #----- CONFIG -------------------------------------------------------------------------------# # Use either a directory or a supported repository type (like s3:https//domain.tld/bucket) BACKUP_REPOSITORY='s3:https://s3.domain.tld/resticsample' # Data directory where your Paperless NGX stores your files # If you're using volumes, use /var/lib/docker/volumes/paperless_* # Alternatively, use several folder-paths seperated by space if needed DATA_DIR='/opt/paperless-ngx/data/' # Path and filename of the environment file of your stack # This file will be evaluated for access credentials ENV_FILE='/opt/paperless-ngx/.env' # Paperless Stack name # Used as prefix for being able to STACK_NAME='paperless-ngx' # If you're not using PostGreSQL but SQlite, set the following to 'no' BACKUP_DATABASE='yes' # How many daily and hourly snapshot should stay available? HOLD_DAYS=14 HOLD_HOURLY=1 # Do you want to cause downtime during backup? (This is the safest backup way) STOP_DURING_BACKUP='yes' #----- CONFIG END ---------------------------------------------------------------------------# # ---- Magic --------------------------------------------------------------------------------# function pre_flight () { # Verify that we have all we need. if [[ ""$BACKUP_REPOSITORY"" == s3:* ]]; then if [[ -z "${AWS_ACCESS_KEY_ID}" || -z "${AWS_SECRET_ACCESS_KEY}" ]]; then echo "You have chosen to backup to S3 (it seems), but either AWS_ACCESS_KEY_ID and/or AWS_SECRET_ACCESS_KEY." exit 1 fi else echo "This script has been tested with S3 only. This should be fine." echo "Ensure that the required environment information for restic are available as per their documentation:" echo "https://restic.readthedocs.io/en/stable/030_preparing_a_new_repo.html" fi if [[ -z "${RESTIC_PASSWORD}" ]]; then echo "You forgot to set RESTIC_PASSWORD which is mandatory for your backup repository!" exit 1 fi # Get all currently running NGX containers DC_DB=$(docker ps| grep "${STACK_NAME}-db" |cut -d " " -f1) DC_BROKER=$(docker ps| grep "${STACK_NAME}-broker" |cut -d " " -f1) DC_GOTENBERG=$(docker ps| grep "${STACK_NAME}-gotenberg" |cut -d " " -f1) DC_TIKA=$(docker ps| grep "${STACK_NAME}-tika" |cut -d " " -f1) DC_WEB=$(docker ps| grep "${STACK_NAME}-webserver" |cut -d " " -f1) } function start_paperless () { echo "# Starting Paperless" docker start $DC_WEB $DC_TIKA $DC_GOTENBERG $DC_BROKER } function stop_paperless () { echo "# Stopping Paperless" docker stop $DC_WEB $DC_TIKA $DC_GOTENBERG $DC_BROKER for i in {15..1}; do echo -ne "... Waiting $i seconds for the stack to stop.\r"; sleep 1 done } function ensure_variable_set () { if [ -z $1 ]; then echo "ERROR: environment variable ${1} not set!" exit 1 fi } function get_db_credentials () { if [ ! -f $ENV_FILE ]; then echo "ERROR: Could not find the configured environment file!" exit 1 fi eval $(grep -E '^(POSTGRES_DB|POSTGRES_USER|POSTGRES_PASSWORD|USERMAP_UID|USERMAP_GID)=' "$ENV_FILE") } function kind_exit () { # We're nice to our admin and bring Zammad back up before exiting start_paperless exit 1 } function delete_old_backups () { echo "# Invoking cleanup as per snapshot rules" restic -r "$BACKUP_REPOSITORY" forget --group-by '' --keep-hourly $HOLD_HOURLY --keep-daily $HOLD_DAYS --prune } function write_backup () { stop_paperless if "${STOP_DURING_BACKUP}x" == 'yesx' echo "# Creating postgresql backup..." docker exec $DC_DB pg_dump --dbname "${POSTGRES_DB}" \ --username "${POSTGRES_USER}" \ --no-privileges --no-owner > /tmp/paperless_db.psql state=$? if [ "${state}" == "1" ]; then echo -e "\n\n # ERROR(${state}) - Database credentials are wrong or database server configuration is invalid." echo -e " #-> BACKUP WAS NOT SUCCESSFUL" kind_exit exit 2 fi restic -r "$BACKUP_REPOSITORY" migrate restic --no-scan --read-concurrency=25 --pack-size=128 --compression off -r "$BACKUP_REPOSITORY" backup \ ${DATA_DIR} /tmp/paperless_db.psql state=$? # clean up temporary database dump rm -f /tmp/paperless_db.psql start_paperless if "${STOP_DURING_BACKUP}x" == 'yesx' if [ $state == '1' ]; then echo "# FATAL - Restic could not create the snapshot." elif [ $state == '3' ]; then echo "# WARNING - Files changed during snapshot creation; Snapshot potentially incomplete!" fi if [ $state -gt 0 ]; then echo "# BACKUP WAS NOT SUCCESSFUL" exit $state fi } function list_available_snapshots () { pre_flight echo "# Here's your currently available snapshots in your backup repository:" restic -r "$BACKUP_REPOSITORY" snapshots } function verify_backup_repository_health () { pre_flight VERIFY_PERCENTAGE="${1:-100}" echo "# Checking ${VERIFY_PERCENTAGE} of your repository ..." restic -r "$BACKUP_REPOSITORY" check --read-data-subset="${VERIFY_PERCENTAGE}%" } function get_snapshot_id () { if [ -n "${1}" ]; then RESTORE_SNAPSHOT_ID="${1}" else # User did not provide snapshot so we'll hard guess 'latest' RESTORE_SNAPSHOT_ID='latest' echo "... No Snapshot provided, guessing you want to restore 'latest'!" for i in {15..1}; do echo -ne "... You have $i seconds to abort.\r"; sleep 1 done fi } function restore_backup () { stop_paperless echo "# ... Dropping current database ${POSTGRES_DB}" docker exec $DC_DB psql -U ${POSTGRES_USER} -c "\c postgres; DROP DATABASE IF EXISTS ${POSTGRES_DB}; CREATE DATABASE ${POSTGRES_DB} OWNED BY ${POSTGRES_USER};" echo "# Restoring PostgreSQL DB" # We're removing uncritical dump information that caused "ugly" error # messages on older script versions. These could safely be ignored. restic -r "$BACKUP_REPOSITORY" dump latest '/tmp/paperless_db.psql' | \ sed '/^CREATE EXTENSION IF NOT EXISTS plpgsql/d'| \ sed '/^COMMENT ON EXTENSION plpgsql/d'| \ docker exec $DC_DB psql -U ${POSTGRES_USER} ${POSTGRES_DB} state=$? if [[ ("${state}" == "1") || ( "${state}" == "2") || ( "${state}" == "3") ]]; then # We're checking for critical restoration errors # It may not cover all possible errors which is out of scope of this script echo -e "\n\n # ERROR(${state}) - Database credentials are wrong or database server configuration is invalid." echo -e " #-> RESTORE WAS NOT SUCCESSFUL" kind_exit exit 2 fi echo "# Restoring Files" restic -r "$BACKUP_REPOSITORY" restore $RESTORE_SNAPSHOT_ID --include "$DATA_DIR" --target / state=$? if [[ ($state == '1') || ($state == '2') ]]; then echo "# ERROR(${state}) - File restore reported an error." echo "- Check file permissions, and ensure Zammad IS NOT running, and try again." echo -e " \n# RESTORE WAS NOT SUCCESSFUL" exit 1 fi echo "# Ensuring correct file permissions ..." chown -R ${USERMAP_UID}:${USERMAP_GID} ${DATA_DIR} start_paperless } function start_backup_message () { echo -e "\n# Backup script started - $(date)!\n" } function start_restore_message () { echo -e "\n# Restore script started - $(date)!\n" } function finished_backup_message () { echo -e "\n# Backup script finished; Check output! - $(date)!\n" } function finished_restore_message () { echo -e "\n# Restore script finished; Check output! - $(date)!\n" } function execute_backup () { pre_flight get_db_credentials start_backup_message write_backup delete_old_backups finished_backup_message } function execute_restoration () { pre_flight get_db_credentials start_restore_message get_snapshot_id $1 restore_backup finished_restore_message } function command_reference () { echo "COMMAND REFERENCE" echo "- backup: creates a new snapshot and backs up database and storage." echo "- restore <snapshot>: Restore a given snapshot from your backup. If you omit the snapshot ID, latest will be used." echo "- list_snapshots: List all available snapshot IDs." echo "- verify_health <percentage>: Verify the health of your backup repository. If you omit percentage, 100% will be assumed." } # ---- Option part and control --------------------------------------------------------------# case "$1" in backup) execute_backup ;; restore) execute_restoration $2 ;; list_snapshots) list_available_snapshots ;; verify_health) verify_backup_repository_health "$2" ;; *) command_reference ;; esac