Upgrading the Paperless-ngx PostgreSQL database to v16

Upgrading the Paperless-ngx PostgreSQL database to v16

Table Of Contents
  1. Upgrading PostgreSQL

Hi there,

It’s been a while, hasn’t it. Had a few stressful months, but I should be back now. So, to get back into it, I will start with something simple.

I’ve had my Paperless-ngx server running for years, using Docker to host my personal documents. The main application has been updated to the latest version, except for the database, which has remained on version 13 since its initial setup.

An in-place upgrade is not possible with PostgreSQL. We need to back up the database, deploy a new empty server, and then import the backup. However, for Paperless-ngx, there’s an easier way.

The integrated exporter in Paperless-ngx can export everything, including the database. This means we can redeploy a clean instance of Paperless-ngx and import the data, making the process much smoother.

Let’s begin.

Upgrading PostgreSQL

Create Paperless-ngx backup

FLet’s begin by examining the Docker Compose configuration file used in this setup, which has some differences from the standard image. We’ll focus on areas marked in red. Please note that this file is located at /root/paperless-ngx and ensure you’re within this directory when running commands.

The current PostgreSQL version is 13 und the folder path ist /etc/paperless-ngx.

version: "3.4"
name: paperless-ngx
services:
  broker:
    image: docker.io/library/redis:7
    restart: unless-stopped
    networks:
       - INTERNAL
    volumes:
      - redisdata:/data

  db:
    image: docker.io/library/postgres:13
    restart: unless-stopped
    networks:
       - INTERNAL
    volumes:
      - pgdata:/var/lib/postgresql/data
    environment:
      POSTGRES_DB: paperless
      POSTGRES_USER: paperless
      POSTGRES_PASSWORD: paperless

  webserver:
    image: ghcr.io/paperless-ngx/paperless-ngx:latest
    restart: unless-stopped
    networks:
       - INTERNAL
    dns:
      - 10.10.0.50
    depends_on:
      - db
      - broker
      - gotenberg
      - tika
    ports:
      - 8000:8000
    healthcheck:
      test: ["CMD", "curl", "-fs", "-S", "--max-time", "2", "http://localhost:8000"]
      interval: 30s
      timeout: 10s
      retries: 5
    volumes:
      - /etc/paperless-ngx/data:/usr/src/paperless/data
      - /etc/paperless-ngx/media:/usr/src/paperless/media
      - /etc/paperless-ngx/export:/usr/src/paperless/export
      - /etc/paperless-ngx/consume:/usr/src/paperless/consume
    env_file: docker-compose.env
    environment:
      PAPERLESS_REDIS: redis://broker:6379
      PAPERLESS_DBHOST: db
      PAPERLESS_TIKA_ENABLED: 1
      PAPERLESS_TIKA_GOTENBERG_ENDPOINT: http://gotenberg:3000
      PAPERLESS_TIKA_ENDPOINT: http://tika:9998
      PAPERLESS_CSRF_TRUSTED_ORIGINS: "YOUR-URL"


  gotenberg:
    image: docker.io/gotenberg/gotenberg:8.7
    restart: unless-stopped
    networks:
       - INTERNAL
    command:
      - "gotenberg"
      - "--chromium-disable-routes=true"

  tika:
    image: ghcr.io/paperless-ngx/tika:latest
    restart: unless-stopped
    networks:
       - INTERNAL

volumes:
  data:
  media:
  pgdata:
  redisdata:

networks:
  INTERNAL:
    external: true

Confirm that paperless is running and execute the following command to export the database. I will be executing them as “root”

## Change folder
paperless-ngx :: ~ » cd /root/paperless-ngx
## Create a Paperless-NGX backup
paperless-ngx :: paperless-ngx » docker compose exec webserver document_exporter ../export

The export will be within the /etc/paperless-ngx/export folder.

Once that’s done, stop the containers.

paperless-ngx :: paperless-ngx » docker compose stop

Restore Paperless-ngx Backup

Alright. The next few steps are irreversible, so make sure you either have a recent backup of the system, a snapshot or anything similar.

Next, we need to remove the PostgreSQL database. To do this, I will delete the volume associated with it. But first, we need to identify it.

## List the docker volumes
paperless-ngx :: ~ » docker volume ls
local     authentik_database
local     authentik_redis
local     graylog_graylog_data
local     graylog_log_data
local     graylog_mongo_data
local     mealie_mealie-data
local     paperless-ngx_pgdata
local     paperless-ngx_redisdata
local     portainer_data

Ok. We have the volume. It’s “paperless-ngx_pgdata” in my case. Make sure you have the correct one. Let’s remove it.

paperless-ngx :: ~ » docker volume rm paperless-ngx_pgdata

Next, delete (or move) the folders “data” and “media” within the paperless-ngx folder. 

## Remove folders with data
paperless-ngx :: ~ » rm -rf /etc/paperless-ngx/data
paperless-ngx :: ~ » rm -rf /etc/paperless-ngx/media

## Recreate folder
paperless-ngx :: ~ » mkdir /etc/paperless-ngx/data
paperless-ngx :: ~ » mkdir /etc/paperless-ngx/media

Great. We need to change the PostgreSQL version in the docker-compose.yml file. Change it to “16” and save the file.

...
    volumes:
      - redisdata:/data

  db:
    image: docker.io/library/postgres:16
    restart: unless-stopped
...

Pull the new image and start the stack.

## Switch to the docker-compose.yml folder
paperless-ngx :: ~ » cd /root/paperless-ngx
## Pull the latest image
paperless-ngx :: paperless-ngx » docker compose pull
## Start the containers
paperless-ngx :: paperless-ngx » docker compose up -d

Now we can restore the backup.

## Restore the Backup
paperless-ngx :: paperless-ngx » docker compose exec webserver document_importer ../export

After a few seconds, the server should be restored.

That’s it.

Hope this helps. Till next time.

Post Views: 15
Tags: , ,

Leave a Reply