Skip to content

Backup and restore

See also: Best practices · Management and maintenance

Dédalo manages two databases. The main one is the work system, which holds the full dataset with the ontology and all the data. The second is the publishing system, a copy that holds only the public data. To create a backup, you must back up both systems.

The work-system (PostgreSQL) backup below is TS-native: src/core/area_maintenance/backup.ts spawns the server's own pg_dump (version-matched against the running PostgreSQL server, probing versioned Homebrew installs) into ../private/backups/db, behind the "Make Backup" maintenance panel (make_backup widget in src/core/area_maintenance/widgets/make_backup.ts). The publishing-system (MariaDB/MySQL) backup is out of scope by design: MariaDB is the diffusion engine's responsibility, not the work server's, so the panel's MySQL file list is always empty. Use the manual mysqldump steps below for the publishing system.

The complete backup set

The work-system database alone is not a backup. The complete set is: the matrix database, the vector database (if you enabled semantic search), the media originals, ../private/ (the secrets and the state), and every site-builder instance on the host (if you run the site builder). The nightly backup units cover all five — see The nightly backup.

Recreating a publication database with work data

Publishing system is a copy and is possible recreate it doing a publication in work system. But some times will be necessary a copy because the work system is not ready to publish his data.

Best practices

Before you begin using Dédalo in production, you should set up a backup host, schedule automated backups, and develop a recovery plan as part of an overall backup strategy.

Requirements and recommendations

The most important data to backup is the work system. It has the full data and media files to be preserved. The publishing system should also be backed up, but as this part is a copy of the working system data that may be public, a backup is not mandatory, but highly recommended.

Your backup plan has to be focused on:

  • backup databases
  • backup media files
  • backup configuration files

A secondary host for backup

We recommend that the backup host and your Dédalo instance be geographically distant from each other. This ensures that backups are available for recovery in the face of major disaster or network outage at the primary site.

Storage space for the backup host: ~5x the size of the uncompressed Dédalo installation. Example: If you expect that your media files will require a 1TB, your backup host will need 5TB.

Backing up media files requires the most space, so calculate the size of your media files when configuring the backup space. We recommend keeping about 3 full copies of your media files and creating an incremental script for daily changes.

Use a RAID system for your backup; we recommend RAID 5 or RAID 6. RAID 5 is designed to survive 1 failed hard drive at a time, RAID 6 to survive 2. If your backup is large storage with many hard drives, RAID 6 may be necessary.

What to back up and how often

priority What? How often? Backup retention How to backup?
mandatory Work system database containing all of Dédalo data - postgreSQL daily backup (full) Keep last 30 days. Keep last 12 months, keep every year copy see how to make a full work system database backup
mandatory Media files daily (incremental) keep daily, keep weekly, keep monthly create a rsync or similar scrip to create an incremental backup
high Publishing system database containing public data - MariaDB/MySQL monthly backup(full) Keep for 30 days see how to make a full publishing system database backup
medium All config Dédalo files daily backup Keep for 30 days Create an archive of Dédalo config files and copy to backup server
low Dédalo codebase monthly backup Keep for 1 month create an archive of Dédalo site files and copy to backup server, it is not mandatory because Dédalo code is possible to install again
medium log files (reverse proxy access logs, the Dédalo server's own process output, PostgreSQL logs, MariaDB/MySQL logs, etc.) daily backup Keep for 6-24 months Copy any new log files to the backup server. Log files are listed in the Logging section.

The nightly backup

Every installation that runs under systemd has a nightly backup job; the compose stacks have their backup service (Docker › Backups).

An instance installed by the installer runs, as the instance user, dedalo-backup@<i>.service with its dedalo-backup@<i>.timer, writing to the instance's backup directory (/home/ded_<i>/backups by default). With --backup-site-builder, the site-builder store runs as root in its own unit, dedalo-backup-site-builder@<i>.service, with no access to the instance's .env. The install's last step (host_backup_verify) ran the set once and checked that every expected store succeeded before it enabled the timer. Check it at any time:

systemctl list-timers 'dedalo-backup@*'
cat /home/ded_<i>/backups/state/LAST_OK          # the stores of the last good run
journalctl -u dedalo-backup@<i> -n 50

A host set up by hand uses the reference units deploy/dedalo-backup.service and .timer (A host set up by hand › The units). The set runs as the service user; it pulls in deploy/dedalo-backup-site-builder.service, which copies the site-builder store as root, in a unit of its own: it reads no EnvironmentFile, runs its scripts from the root-owned root bin directory, and writes to /var/backups/dedalo-site-builder. A failed run fires dedalo-backup-alert@.service, which runs as the service user.

Each unit declares the stores it promises (DEDALO_BACKUP_EXPECTED_STORES), and a run that leaves one of them without a status fails, so a truncated store list cannot report success.

Backup the work system

Work system use PostgreSQL database, doing a backup of this database you will create the full copy of your data.

You can perform a backup in different ways:

Automatic backup

You can change the backup configuration — directory, cadence and other parameters — by editing Dédalo's backup settings in ../private/.env.

Gap: no automatic trigger on save

initBackupSequence() (src/core/area_maintenance/backup.ts) implements the throttle window (an 8-hour minimum between non-forced dumps, per DEDALO_BACKUP_TIME_RANGE) and a stable file-naming scheme, but nothing in the save/write path calls it automatically yet — it only runs when the "Make backup" button (or its API action) is invoked. Until this is wired in, treat backups as manual/cron only (see below).

Manual backup

But in some times you will need do a backup manually to fix a specific point. It can be useful to update major version or change the server.

To create a full copy of Dédalo work system manually, follow this:

  1. Login as global administrator or root account
  2. Enter into Maintenance panel:

    System administration -> Maintenance

  3. Locate the "Make Backup" panel

  4. Press the "Make backup" button.
  5. Wait to be finished.

The panel will indicate the directory of the copy, it will be storage into bk directory in the server and it will be named with the date, name of the database, as:

2023-09-09_205044.my_dedalo_db.postgresql_1_forced_dbv6-0-0.backup

The file lands in ../private/backups/db (getBackupDir() in src/core/area_maintenance/backup.ts), and the name carries a .custom. infix before the extension (custom pg_dump -F c format, e.g. 2026-07-04_205044.my_dedalo_db.postgresql_-1_forced_dbv7-0-0.custom.backup) — otherwise the naming follows <date>.<db>.postgresql_<user>[_forced]_dbv<version>. The user-id segment is always -1 (superuser), since the maintenance panel is a global-admin/root-only surface.

Making a manual backup in the server shell

If you want create a backup using the server shell, you can easily backup full Dédalo data using the following command.

pg_dump -h /tmp -p 5432 -U "dedalo_database_user" -F c -b dedalo_database_name  > "../dedalo_backup_database.backup"

You can see pg_dump official documentation here.

Restore a backup for the work system

A restore is a procedure the engine owns. Do not run pg_restore by hand against a live database: pg_restore continues past errors by default, so a run whose copy of one table failed leaves that table's OLD rows beside restored neighbours, and nothing you can see distinguishes it from a successful restore. The engine's restore door does the whole procedure in the right order, refuses at the first thing that is wrong, and leaves your database exactly as it was whenever it refuses.

You need shell access to the server with administration privileges, and the database user Dédalo connects with needs the CREATEDB privilege (the door builds the restored database beside the current one and swaps them by name):

ALTER ROLE dedalo_database_user CREATEDB;

The commands below name an instance <i> installed by the installer; on a host set up by hand, use its unit dedalo-ts, its code <instance directory>/master_dedalo and its runtime <root bin directory>/bun (The layout).

  1. Stop the engine, and the watchdog timer that would restart it:

    systemctl stop dedalo-ts@<i>.service dedalo-ts-watchdog@<i>.timer
    

    The door refuses while anything is still connected to the database — it tells you which connection, by process id.

  2. Run the door with the backup file:

    cd /home/ded_<i>/dedalo
    sudo -u ded_<i> /opt/dedalo/bun/<pin>/bun scripts/restore.ts /home/ded_<i>/backups/db/2026-08-29_033000.dedalo_<i>.custom.backup
    

    What it does, in order: it reads the WHOLE file to prove it is a complete dump (a file cut short by a failed backup passes every cheaper check); checks that nothing is connected; restores into a new, empty database in one transaction that either lands completely or not at all; renames your current database to <name>_pre_restore_<stamp> and the restored one to <name>; runs the reconcile checks a restore needs (the media counters are repaired, the rest are reported); writes a report to <backups>/restores/<stamp>.json; and switches maintenance mode on so an engine started early lets only superusers in.

    Exit status 0 means restored with nothing left to decide; 2 means restored, and the report lists checks HELD for your decision (the reconcile panel in the maintenance area, or bun scripts/reconcile.ts); 1 means it refused or failed — and your database is untouched.

  3. Restore the media files from a backup generation older than the problem (see below), rebuild the derivatives with the update cache tool, and start the engine again. Switch maintenance mode off from the maintenance area once you have read the report.

  4. When the restored system is accepted, drop the previous copy — it is a full second database on the same disk:

    DROP DATABASE my_dedalo_db_pre_restore_20260829_033000;
    

    (or pass --drop-previous to the door to skip keeping it).

To restore into a database with a different name — for a rehearsal, or a fresh server — pass --database other_name; when that database does not exist yet the door simply creates it, and nothing is renamed. This is a REHEARSAL, and the door treats it as one: it verifies, restores and swaps, but it does not run the reconcile checks and does not switch maintenance mode on — both belong to the database in your .env, the one the running engine serves, so a rehearsal is safe while the engine is up. Its verdict is the record count in other_name, which you read yourself; drop that database when you are done. Rehearse a restore quarterly this way: a backup that has never been restored is a hypothesis.

Backup of media files

Media files are the most large data to be backup, usually it will be a large list of image, audiovisual, pdf, and other documents. If your Dédalo project has large audiovisual files, or thousands or millions image files, you will expect a server with large storage (TBs instead GBs) and your backup storage need to be set to retain almost 3 copies of the media files.

The nightly backup (or the backup service of the compose stacks) already copies the media originals as dated generations: each night's copy is a directory named by its timestamp in which unchanged files are hard links into the previous night's, so fourteen generations cost little more disk than one, and a file deleted by mistake is still in every generation older than the mistake. The number kept is the --keep value of the job. To restore, copy the generation you want back over the media directory — never the newest one if the newest one already contains the mistake.

If you write your own script instead, keep the same rule: never a single mirror that deletes on the destination what was deleted at the source (rsync --delete into one directory is ONE copy, and it follows the mistake). Use dated rsync --link-dest generations, or filesystem snapshots.

Creating an incremental script for media files

You can use rsync with a cron or other backup solution to create a incremental script.

rsync -avzui --human-readable --links --progress --log-file="../my_backup_scrip_log$(date +%Y%m%d%H%M%S).log" -e "ssh -p 33333" "../dedalo/media" my_user@my_backup_sever.dedalo.dev:/backup/my_host/daily

ssh access to backup host

If you want to run the script automatically, maybe you will need to create a ssh keys access to backup system to log it directly without password. You can set it following this instructions or this.

And you can create a con job to execute it as:

00 01 * * * ../dd_backup_rsync/my_backup_daily.sh

You can read about rsync here

You can add more scripts to create a weekly or monthly backups in the same way.

Backup the publishing system

The publishing system uses the MariaDB/MySQL database. By backing up this database, you will create a copy of the data that was published, a copy of the public data.

Gap: no publishing-system backup button

MariaDB is the diffusion engine's database, not the work server's — the maintenance panel's get_dedalo_backup_files action always reports an empty mysql_backup_files list, and there is no "Make a publishing backup" action registered (make_backup in src/core/area_maintenance/widgets/make_backup.ts only implements make_psql_backup/get_dedalo_backup_files). Use the manual mysqldump steps below.

Manual backup

To create a full copy of Dédalo publishing system manually, follow this:

  1. Login as global administrator or root account
  2. Enter into Maintenance panel:

    System administration -> Maintenance

  3. Locate the "Make Backup" panel

  4. Press the "Make a publishing backup" button.
  5. Wait to be finished.

The panel will indicate the directory of the copy, it will be storage into bk directory in the server and it will be named with the date, name of the database, as:

2023-09-09_205044.mysql_dump_my_publishing_database.sql

Making a manual backup in the server shell

The simplest way to make a full copy of the MariaDB/MySQL database is to run the mysqldump command with this set of parameters:

mysqldump -u publishing_bd_user_name -p -v my_publishing_database > mysql_dump_my_publishing_database.sql

Using MariaDB

If you are using a MariaBD > 11.0, you will need to use mariadb-dump instead mysqldump

Optional: if you want to compress the backup:

tar zcf mysql_dump_my_publishing_database-$(date +%Y-%m-%d-%H.%M.%S).sql.tar.gz mysql_dump_my_publishing_database.sql

Restore a backup of publishing system

You can use Adminer or other database tools to import the file that you previously created, or restore the DB backup by running the following command:

mysql -u publishing_bd_user_name -p -v  mysql_dump_my_publishing_database < mysql_dump_my_publishing_database.sql

Backup of site-builder instances

If you run the site builder, each of its instances on the host is part of the backup set: its declaration and secrets, its workspaces and each site's webspace. The store runs as root in its own unit (dedalo-backup-site-builder@<i>.service on an installer instance, asked for with --backup-site-builder; deploy/dedalo-backup-site-builder.service on a host set up by hand), never beside an instance's .env; on a host with no site-builder instance it copies nothing. The destination holds root-owned secrets, so treat it like the ../private/ copy. A host running several Dédalo instances backs the site-builder instances up from one instance only, since the store covers the whole host (see several instances).

Backup a Dédalo config files

Config files store your environment, database configuration access, API access and other important information. Backup the config files ensure you that this information will be preserved in case of server failure, and it that could be necessary to restore a backup because the password encryption system need a keys stored into the config files.

The most important situations will happen in case you lose the configuration files could be:

  • you can loose the access to the database user, and will need use a pw reset in postgreSQL or MariaDB
  • you will need to rebuild all Dédalo passwords

Both situations are reversible but are not simple processes.

Configuration files do not change every day and usually only change when new features are required or some changes are set into the work system, so it's not mandatory to create a daily backup, but it's high recommendable create a script to automate the backup process. We recommended a monthly backup of the config files.

For transfer the files to the backup server consider compress the files in this way:

tar cvfz dedalo_configuration.tar.gz ../dedalo/config

Dédalo keeps its per-install configuration and secrets outside the code tree entirely, in ../private/ (a sibling of the install tree — see the check_config widget's computeCheckConfig, in src/core/area_maintenance/widgets/check_config.ts, which reports these exact sources): .env (credentials/config), ts_state.json (maintenance mode, notification and menu overrides) and the sessions database. Back these up together, e.g. tar cvfz dedalo_configuration.tar.gz ../private.