Backing Up Citadel and Setting Up a Standby Server

All persistent state for a Citadel installation lives inside the Citadel root directory (by default, /usr/local/citadel). This includes the database, server configuration, mail spools, and TLS encryption keys. WebCit is stateless and does not store persistent data, so only the Citadel directory needs to be protected.

Recommended Method: Filesystem Snapshots

The safest and most efficient way to back up Citadel (or keep a standby server updated) is using read-only filesystem snapshots with a modern volume manager or copy-on-write filesystem such as ZFS, Btrfs, or LVM.

• Zero Downtime: Because Citadel's storage engine uses atomic, copy-on-write transactions, a filesystem snapshot captures a perfectly consistent point-in-time database image in a fraction of a second without locking active sessions or interrupting connected users.
• Backups: You can back up the read-only snapshot volume using standard backup tools (such as Borg, Restic, or tar) while Citadel continues running normally.
• Replication: Snapshots can be sent incrementally over the network to a secondary host (for example, using zfs send and zfs recv) at whatever frequency you require (such as hourly or nightly).

Alternative Method: File-Level Copy (tar or rsync)

If your system does not support filesystem snapshots and you must copy files directly from disk, you must stop the Citadel server before copying:

1. Stop the Citadel service (for example, systemctl stop citadel or stopping your Docker container).
2. Create your archive (e.g., with tar) or synchronize /usr/local/citadel to your backup destination or standby server using rsync.
3. Restart Citadel.

Running file-level copy tools like rsync or tar against an active, running database without stopping the server risks capturing inconsistent data, which will lead to database corruption upon restore.

Maintaining a Standby Server

To prepare a secondary system for rapid disaster recovery or hardware failover:

• Install Citadel on the secondary host, configured to use the replicated /usr/local/citadel directory.
• Keep the Citadel service stopped on the standby system during normal operation so both machines never attempt to write to the data simultaneously.
• WebCit only needs to be installed on the standby machine and ready to launch against the local server.
• In the event of a primary server failure, switch your DNS records or virtual IP to point to the secondary server, and start the Citadel service.