Back up and restore

Protect an Erde installation against data loss by backing up everything that holds state: the two databases, the file-storage blobs, and the server's encryption keys. This guide explains what to capture, how to take a consistent backup, and how to restore.

Before you start

• Role required: server administrator on the host machine (file-system and database access). No Erde role is involved — backup happens outside the application.
• Prerequisites: a running, configured installation (see Install with the MSI and First-run setup).

Erde ships no built-in backup or restore command. You back up and restore using your database vendor's tools and standard file copies. Take all four items below together so they describe the same point in time.

What to back up

An Erde deployment keeps its state in four places. Restoring a database without its matching encryption keys leaves sensitive values unreadable, so treat the keys as part of the backup, not an afterthought.

Item	Where it lives	Why it matters
Platform database	erde_platform	Identity, refresh tokens, system settings, and the Application database registry
Application database	erde_app	All domain data — projects, sites, samples, lab data, monitoring, imports, documents, comments
File-storage blobs	C:\ProgramData\Erde\storage\	The physical bytes of uploaded files; database rows point at these on disk
Server config and keys	C:\Program Files\Erde\api\appsettings.Production.json	Connection strings plus the cryptographic keys that decrypt sensitive database values

Database names default to erde_platform and erde_app; the setup wizard applies these names and does not offer them as editable fields. The active database provider is recorded as Database:Provider (postgresql or sqlserver) inside appsettings.Production.json.

Why the config file is required

appsettings.Production.json holds keys generated randomly at first-run setup. The two that matter most for restore are:

Key	Purpose
Encryption:AesKeyBase64	AES-256 encryption of sensitive database values (for example, SMTP passwords and ArcGIS keys stored as system settings)
Tokens:TokenHashSecret	HMAC hash for refresh tokens

If you restore the databases but lose Encryption:AesKeyBase64, encrypted settings become unreadable — the server logs warnings and treats them as "not configured." The file is not tracked by the installer, so it survives upgrades but is never captured by one. Back it up explicitly.

The license file at C:\Program Files\Erde\api\license.bin is also untracked by the installer. Including it in the backup saves a re-activation step after a restore.

Take a consistent backup

Run these steps as a set so the databases, files, and keys all reflect the same moment.

1. Stop the application so no writes land mid-backup. Stop the Windows Service:

   Stop-Service Erde

   In IIS deployments, stop the Erde site or its app pool instead. See Hosting: Windows Service vs IIS.

2. Back up the erde_platform database using your database vendor's tools (for example, a PostgreSQL dump or a SQL Server BACKUP DATABASE). Erde does not provide a dump command; consult your provider's documentation. See Database setup for which provider this installation runs.

3. Back up the erde_app database the same way.

4. Copy the file-storage folder C:\ProgramData\Erde\storage\ in full. These bytes are not in the database — FileRecord rows reference them by path.

5. Copy the config and license files from C:\Program Files\Erde\api\: appsettings.Production.json and, if present, license.bin.

6. Restart the application.

   Start-Service Erde

Store the four artifacts together and label them with the date. They form one restore point.

Backup copies do not keep the config file's permissions

On the server, appsettings.Production.json is locked down so only administrators and the Erde service can read it. A copy does not carry those permissions — it inherits whatever access the backup location grants. Because the file contains the encryption keys, store backups in a location with access restrictions equivalent to the server itself.

If you must back up while the server runs, take the database backups first and copy the storage folder last. The file-record lifecycle (below) is designed so a database backup that is slightly older than the file copy does not orphan downloads.

How file records survive a restore

Deletes are soft: deleting a file marks its FileRecord row but keeps the bytes on disk until the retention window passes, so a restore newer than FileStorage:DeletedFileRetentionDays (default 30 days) brings those files back intact. For the full soft-delete and purge lifecycle, see Aggregates, locking, and auditing.

The setup wizard does not write FileStorage:DeletedFileRetentionDays, so deployments use the 30-day default unless an administrator adds the key to appsettings.Production.json.

Restore

Restore the same four artifacts you captured, into the same locations.

1. Stop the application (Stop-Service Erde, or stop the IIS site).
2. Restore both databases from your backups using your database vendor's restore tooling — erde_platform and erde_app.
3. Restore the file-storage folder to C:\ProgramData\Erde\storage\.
4. Restore the config and license files to C:\Program Files\Erde\api\: appsettings.Production.json (with the original encryption keys) and license.bin.
5. Start the application (Start-Service Erde). On the first start, provided a valid license is active, the server applies any pending migrations, then serves normally. Restoring license.bin in step 4 keeps the license active and avoids this path; if no valid license is present, the server skips migrations and returns a license error until you activate one (see the "License Required" row under Troubleshooting).

Restore only a backup newer than the retention window

A backup older than FileStorage:DeletedFileRetentionDays (default 30 days) is unsafe to restore. Files that were soft-deleted and then purged in the meantime come back as live rows, but their bytes are already gone — every download of those files fails. Keep your backup-restore horizon shorter than the retention window, or raise FileStorage:DeletedFileRetentionDays to cover it. Restoring a database without its matching appsettings.Production.json also leaves all encrypted values unreadable.

Troubleshooting

Symptom	Cause	Resolution
Encrypted settings show as "not configured" after restore	appsettings.Production.json (with Encryption:AesKeyBase64) was not restored, or a different key was used	Restore the original config file that matches the database backup
File downloads fail for files that existed at backup time	The backup is older than the retention window, so purged bytes are gone	Restore a newer backup; going forward, keep backups within FileStorage:DeletedFileRetentionDays
Service reports error 1053 (timeout) on first start	If the restored database needs migrations applied, the first start can exceed Windows' service-start timeout	The service keeps running and completes startup; subsequent starts are fast
A "License Required" overlay covers the app and blocks data access (sign-in still works)	license.bin was not restored, or no license is active	Restore license.bin from the backup, or reactivate by running the installer (or Erde.Server.exe --activate --key <YOUR-KEY>) (see Activate and manage your license)

Related

• Upgrades
• Install with the MSI
• Database setup
• Aggregates, locking, and auditing