Database Backups

DocuMan can take scheduled and on-demand backups of its PostgreSQL database via pg_dump, writing each backup as a single timestamped .dump file to a folder you choose — either a local path or a remote network share.

How It Works

1. You set a destination folder (and optionally the path to pg_dump) in Admin → Backups.
2. Optionally, you enable a schedule (daily / weekly / monthly at a specific time).
3. The API service runs pg_dump --format=custom at the scheduled time, or whenever you click Back Up Now, and writes a file named JimRanDocuMan_YYYYMMDD_HHMMSS.dump to the destination.
4. After each successful backup, files beyond your retention count are deleted (only files matching the DocuMan naming pattern — anything else in the folder is left alone).
5. Every attempt (manual or scheduled, success or failure) is recorded in the backup history table for audit.

Destination Options

Local folder

Any folder on the DocuMan server that the API service account has write access to. Examples:

• D:\Backups\DocuMan
• C:\ProgramData\DocuMan\backups

Remote folder (network share)

A UNC path to a Windows share or NAS:

• \\backup-server\docman\
• \\nas01.local\share\DocuMan-Backups

The Windows account the DocuMan API service runs as must have write permission on the share. The default LocalSystem service account does not have access to most network shares; either change the service to run as a domain account with share access, or grant the machine account permission on the share.

Configuration

Navigate to Admin → Backups.

Destination

Setting	Description
Backup folder	Local path or UNC share where each .dump file is written. Leave blank to disable backups entirely.
pg_dump executable	Optional. Leave blank to auto-detect (looks in standard PostgreSQL install paths like C:\Program Files\PostgreSQL\18\bin\pg_dump.exe, then on the system PATH). Override if you have a non-standard install.

Schedule

Setting	Description
Enabled	Master switch for the recurring schedule. Manual Back Up Now still works when disabled.
Frequency	Daily, Weekly, or Monthly.
Start time	Local time of day the backup should fire, in HH:MM 24-hour format. The scheduler wakes once a minute and runs the next backup the first time the clock crosses this time after the previous successful run.
Day of week (weekly only)	Which weekday to run on (Sunday – Saturday).
Day of month (monthly only)	1–28 recommended — values higher than 28 will skip months that don't have that day (e.g. day 31 in February).
Keep last N backups	Retention count. After each successful run, the oldest backup files beyond this number are deleted from the destination folder. Set to 0 to disable cleanup and keep every backup forever.

Manual run

The Back Up Now button on the same page runs a single backup immediately, using the current destination settings. The history row appears in the table below as running, then flips to success (or failed) when pg_dump finishes.

Behavior & Format

• Format: custom (pg_dump --format=custom) — compressed by default and supports parallel restore.
• Filename pattern: JimRanDocuMan_YYYYMMDD_HHMMSS.dump.
• Atomicity: pg_dump takes a consistent snapshot using a single read transaction; no need to stop the DocuMan service before a backup.
• Duplicate-slot protection: after a successful scheduled run, the slot (e.g. daily:2026-05-25 or weekly:2026-W21) is marked done. The same slot won't fire twice even if the server is restarted within it.
• Missed runs: if the server is down at the scheduled time, the next start picks up the missed run only if it's still within the same calendar slot (same day / week / month) and the start time has already passed.
• Audit: manual runs and failures are recorded in the standard audit log in addition to the Backups history table.

Restoring a Backup

Restore is a deliberate, destructive operation and is intentionally not exposed through the web UI. Use the standard PostgreSQL tooling from the command line:

pg_restore --clean --if-exists --no-owner --no-privileges \
    --host=localhost --port=5432 \
    --username=docman \
    --dbname=JimRanDocuMan \
    "D:\Backups\DocuMan\JimRanDocuMan_20260525_020000.dump"

Before restoring in a production scenario:

1. Stop the four DocuMan services so nothing writes to the database during the restore.
2. Take a fresh backup of the current state (so you have a rollback point if the restore goes wrong).
3. Run pg_restore against a fresh empty database, verify it loaded cleanly, then either swap names or repoint DocuMan at it.

If the restored database lives at a different path on disk, remember that DocuMan's document storage lives outside the database under each cabinet's base_path — the database row points at file locations, the rows themselves don't contain the files.

Troubleshooting

• "backup_path is not configured": set the Backup folder under Admin → Backups → Destination.
• "pg_dump executable not found": auto-detect could not find it. Set the pg_dump executable field explicitly to the full path of pg_dump.exe (Windows) or pg_dump (Linux).
• "Permission denied" writing to a UNC share: the DocuMan API service account doesn't have write access to the share. Change the service to run as a domain account with permission, or grant the machine account write access on the share's NTFS + share permissions.
• Backups appear in history as failed: open the row's error message column. Common causes are wrong pg_dump path, network share unreachable, disk full, or a stale credential. The full pg_dump stderr is captured in the error column (truncated to 2000 characters).
• Scheduled backups not firing: verify Schedule enabled is on, Start time is in the future for the current day, and check the API service log for docman-backup-scheduler entries. The scheduler wakes every 60 seconds and will log when a slot fires.
• Disk filling up: lower the Keep last N backups retention setting, or set up a separate cleanup process if you want different retention behavior than "delete oldest N+1".

---

See also: Services & Processes — how the API service that runs the scheduler is managed; Configuration — other admin settings.