How to Back Up and Restore Docmost with Docker Compose and PostgreSQL

Introduction

Backups are essential for any production Docmost deployment. Whether your server fails, a Docker volume is accidentally deleted, or your PostgreSQL database becomes corrupted, having a reliable backup lets you recover your workspace with minimal downtime and data loss.

A complete Docmost backup consists of three parts: the PostgreSQL database, the storage volume, and the application configuration. The database stores your users, workspaces, pages, comments, permissions, and attachment metadata. The storage volume holds the actual uploaded files, such as images, PDFs, and other attachments. The application configuration, made up of the .env file and docker-compose.yml, preserves the settings needed to start the application and connect it to the database. Backing up only one of these three is not enough to fully recover your instance.

In this article, you will back up a self-hosted Docmost instance running with Docker Compose, an external PostgreSQL database, and local file storage. To confirm the backup strategy actually works, you will then perform a complete disaster recovery test: deleting the application data, restoring it from your backups, and verifying from both the command line and the Docmost web interface that users, workspaces, pages, and uploaded files have been successfully recovered.

note

This article was tested on a live server before publication. Every command, configuration file, and verification step was validated on the final deployment to maintain accuracy.

Prerequisites

Before you begin, make sure you have the following:

A Running Docmost Deployment: A self-hosted Docmost instance running with Docker Compose, connected to an external PostgreSQL database, with local file storage configured for uploads.
A Non-Root User with Sudo Privileges: SSH access to the server using the non-root user created during deployment.
The PostgreSQL Client: pg_dump, pg_restore, and psql installed on the server. The client version should match or be compatible with your PostgreSQL server version.
Existing Data in Docmost: At least one workspace with pages and uploaded files, so you can confirm that the backup and restore process works correctly.

Infrastructure Used

This guide was validated using the following infrastructure:

Cloud Provider: DigitalOcean
Operating System: Ubuntu 24.04 LTS
Deployment Environment: Virtual Machine (Droplet)

Disclosure

This guide contains affiliate links. If you sign up through these links, I may earn a commission at no additional cost to you. I only recommend products and services that I personally use while testing my guides.

Create a DigitalOcean Droplet

Step 1: Create Create the Project Directory

Keeping the database backup, storage archive, and configuration files in a single location makes them easier to manage, transfer, and restore later. In this step, you'll create a dedicated directory to store all backup files for this run.

Create a backups directory inside your Docmost project, then create a timestamped folder for the current backup:
```
mkdir -p backups

BACKUP_DIR=backups/docmost-$(date +%F-%H-%M-%S)
mkdir -p "$BACKUP_DIR"

echo "$BACKUP_DIR"
```
The backup directory should look similar to this:
```
backups/
└── docmost-2026-07-04-07-08-29/
```

Step 2: Back Up the PostgreSQL Database

The PostgreSQL database stores all of your Docmost application data, including users, workspaces, pages, comments, permissions, and attachment metadata.

Install the PostgreSQL client, if it isn't already available on the server:
```
sudo apt update
sudo apt install postgresql-client -y
```
If your PostgreSQL server is running a newer major version than the default Ubuntu package, install the matching client from the official PostgreSQL repository instead.
Create the database backup using pg_dump:
```
pg_dump \
  --dbname="$(grep '^DATABASE_URL=' .env | cut -d '=' -f2-)" \
  --format=custom \
  --verbose \
  --file="$BACKUP_DIR/docmost-db.backup"
```
The --format=custom option creates a compressed backup that can be restored using pg_restore and supports more flexible recovery options than a plain SQL dump.
Confirm that the backup file was created and has a non-zero size:
```
ls -lh "$BACKUP_DIR"
```
Inspect the backup using pg_restore. This reads the archive and lists its contents without restoring any data:
```
pg_restore --list "$BACKUP_DIR/docmost-db.backup" | head -20
```
If the command lists database objects such as tables, functions, and extensions, the backup is valid and ready to be used for restoration.

Step 3: Back Up the Storage Volume

The storage volume contains all uploaded files, including images, PDFs, and other attachments. Backing up the database alone is not enough, because it only stores metadata about these files, not the files themselves.

Inspect the storage volume to confirm its contents:

docker run --rm \
  -v docmost_docmost:/data \
  alpine ls -R /data

Create a compressed archive of the storage volume and save it to the backup directory:

docker run --rm \
  -v docmost_docmost:/data:ro \
  -v "$(pwd)/$BACKUP_DIR":/backup \
  alpine \
  tar czf /backup/docmost-storage.tar.gz -C /data .

Inspect the archive without extracting it:
```
tar -tzf "$BACKUP_DIR/docmost-storage.tar.gz"
```
If the command lists the uploaded files and directories, the storage backup has been created successfully and is ready to be restored when needed.

Step 4: Back Up the Application Configuration

The application configuration contains the settings required to run your Docmost deployment, including the database connection, application secrets, and Docker Compose configuration.

Copy the configuration files to the backup directory:

cp .env "$BACKUP_DIR/"
cp docker-compose.yml "$BACKUP_DIR/"

Verify that the files were copied successfully:
```
ls -lah "$BACKUP_DIR"
```

The backup directory should now contain all the files required to restore your Docmost deployment:

backups/
└── docmost-2026-07-04-07-08-29/
    ├── .env
    ├── docker-compose.yml
    ├── docmost-db.backup
    └── docmost-storage.tar.gz

Step 5: Record a Pre-Disaster Baseline

Before simulating a disaster, record the current state of your Docmost instance. These values will confirm, later, that the restored instance matches the original deployment.

Connect to the PostgreSQL database:

psql "$(grep '^DATABASE_URL=' .env | cut -d '=' -f2-)"

Run the following queries:

SELECT COUNT(*) AS users FROM users;

SELECT COUNT(*) AS workspaces FROM workspaces;

SELECT COUNT(*) AS pages FROM pages;

SELECT COUNT(*) AS attachments FROM attachments;

Record the results, then exit the PostgreSQL shell:
```
\q
```

Step 6: Simulate a Disaster

Creating a backup is only half of a disaster recovery strategy. To trust your backups, you need to confirm they can successfully restore your deployment after a real data loss event.

Warning: The following steps permanently delete your existing Docmost data. Make sure you have completed and verified your backups before proceeding.

Stop and remove the running Docmost containers:
```
docker compose down
```
Verify that all containers have been removed:
```
docker compose ps
```
List the available Docker volumes:
```
docker volume ls
```
Remove the Docmost storage volume:
```
docker volume rm docmost_docmost
```
Verify that the volume has been removed:
```
docker volume ls
```

Connect to your PostgreSQL database:

psql "$(grep '^DATABASE_URL=' .env | cut -d '=' -f2-)"

Drop and recreate the public schema to remove all application data:

DROP SCHEMA public CASCADE;
CREATE SCHEMA public;
GRANT ALL ON SCHEMA public TO doadmin;
GRANT ALL ON SCHEMA public TO public;

Exit the PostgreSQL shell:
```
\q
```
Reconnect to the database and verify that all tables have been removed:
```
psql "$(grep '^DATABASE_URL=' .env | cut -d '=' -f2-)"
```
```
\dt
```
If the command returns Did not find any relations., the database has been successfully cleared and is ready for the restore process.

Step 7: Restore the Backup

Now that you've simulated a disaster, restore the Docmost deployment using the backups created earlier.

Create a new Docker volume to store the uploaded files:
```
docker volume create docmost_docmost
```

Extract the storage backup into the newly created volume:

docker run --rm \
  -v docmost_docmost:/data \
  -v "$(pwd)/$BACKUP_DIR":/backup:ro \
  alpine \
  sh -c "tar xzf /backup/docmost-storage.tar.gz -C /data"

Verify that the uploaded files have been restored:

docker run --rm \
  -v docmost_docmost:/data \
  alpine \
  find /data -type f

Restore the database from the backup archive:

pg_restore \
  --dbname="$(grep '^DATABASE_URL=' .env | cut -d '=' -f2-)" \
  --clean \
  --if-exists \
  --verbose \
  "$BACKUP_DIR/docmost-db.backup"

Verify that the database tables have been recreated:

psql "$(grep '^DATABASE_URL=' .env | cut -d '=' -f2-)"

\dt

Exit the PostgreSQL shell:
```
\q
```
Start the application:
```
docker compose up -d
```
Verify that all containers are running:
```
docker compose ps
```
Check the application logs to confirm that Docmost starts successfully:
```
docker compose logs -f docmost
```

Step 8: Verify the Restore

After restoring the backup, confirm that your Docmost deployment has been recovered successfully by comparing it against the baseline you recorded in Step 5.

Connect to the PostgreSQL database:

psql "$(grep '^DATABASE_URL=' .env | cut -d '=' -f2-)"

Run the same queries again:

SELECT COUNT(*) AS users FROM users;

SELECT COUNT(*) AS workspaces FROM workspaces;

SELECT COUNT(*) AS pages FROM pages;

SELECT COUNT(*) AS attachments FROM attachments;

The values should match the counts you recorded before the disaster simulation.

Verify that the uploaded files have been restored:

sudo find /var/lib/docker/volumes/docmost_docmost/_data -type f

Open your Docmost instance in a browser and verify the following:

You can log in successfully.
The workspace has been restored.
All pages are present.
Uploaded PDFs and images open correctly.
Attachments are accessible without errors.

If all of these checks pass, your backup and restore process has been successfully validated.

Troubleshooting

pg_dump Reports a Server Version Mismatch: If your PostgreSQL client version is older than your PostgreSQL server version, you'll see an error similar to the following:
```
pg_dump: error: aborting because of server version mismatch
```
Fix: Install a PostgreSQL client version that matches or is newer than your PostgreSQL server, then run the backup again.
pg_restore Cannot Connect to the Database: If pg_restore attempts to connect to a local PostgreSQL server instead of your remote database, the DATABASE_URL may not be set correctly.

Fix: Read the connection string directly from the .env file to confirm it's correct:
```
grep '^DATABASE_URL=' .env
```
Backup Files Cannot Be Found: If commands fail with an error similar to the following:
```
No such file or directory
```
Fix: Verify that the BACKUP_DIR variable points to the correct backup directory:
```
echo "$BACKUP_DIR"
```
You can also pass the backup directory path directly in each command instead of relying on the environment variable.
Uploaded Files Are Missing After the Restore: If pages are restored but attachments are missing, the storage volume likely wasn't restored correctly.

Fix: Confirm that docmost-storage.tar.gz was extracted into the docmost_docmost Docker volume before starting the application, then repeat the storage restore step.

Conclusion

In this article, you backed up a self-hosted Docmost deployment, including the PostgreSQL database, uploaded files, and application configuration. You also performed a complete disaster recovery test by deleting the application data, restoring it from your backups, and verifying that users, workspaces, pages, and attachments were recovered successfully.

With a tested backup and restore process in place, you can run your Docmost deployment with confidence, knowing that a server failure, accidental deletion, or database corruption won't result in permanent data loss.

Introduction​

Prerequisites​

Infrastructure Used​

Step 1: Create Create the Project Directory​

Step 2: Back Up the PostgreSQL Database​

Step 3: Back Up the Storage Volume​

Step 4: Back Up the Application Configuration​

Step 5: Record a Pre-Disaster Baseline​

Step 6: Simulate a Disaster​

Step 7: Restore the Backup​

Step 8: Verify the Restore​

Troubleshooting​

Conclusion​