Schedule automatic backups of your log, photos, and settings, copy them off the server, and put everything back when you need it.
Field Day Commander ships with two scripts, backup.sh and restore.sh, that will save the database, uploaded photos, and settings, and can put them back onto the same server or a new one.
This guide covers a native install made with deploy.sh and a Docker Compose install. You'll need an SSH session on the server and an account that can run sudo. If SSH is new to you, start with SSH Basics.
You only need to set up the backup schedule once, ideally a few weeks before Field Day. The rest of this guide covers copying backups off the server, restoring, and moving to new hardware.
Each backup writes three files that share a timestamp in the form YYYYMMDD-HHMMSS:
| File | What's in it |
|---|---|
fdc-db-STAMP.sql.gz | The whole database: contacts, stations, users, shifts, equipment, and everything else you entered. |
fdc-files-STAMP.tar.gz | Uploaded files from storage/app, such as gallery photos, equipment photos, and your club logo. |
fdc-env-STAMP | A copy of the server's .env settings file, including APP_KEY, the mail settings, and the database password. |
Keep the three files together. The APP_KEY in the env file encrypts each user's two-factor authentication secret, so a database restored under a different key will lock those users out. The env file also holds passwords, so the backup folder is readable by root only.
Field Day Commander keeps running during a backup, so you can take one in the middle of the event. Server logs, cached data, and TLS certificates aren't included. The cache rebuilds on its own.
On a native install the scripts are in /var/www/fd-commander. If backup.sh isn't there, run sudo ./update.sh from your Field Day Commander folder to copy both scripts into place.
This command sets up two systemd timers (Linux's built-in job scheduler): a database backup every hour, and a full backup of all three files every night at 02:30.
sudo /var/www/fd-commander/backup.sh --install-schedule
You should see Hourly database backups and nightly full backups (02:30) enabled, followed by where the backups go and how many days they're kept.
Backups go to /var/backups/fd-commander, and anything older than 7 days is deleted each time a backup runs. To change either, add --dest or --keep-days. The timers remember whatever you pass here. --keep-days 0 keeps everything.
sudo /var/www/fd-commander/backup.sh --install-schedule --keep-days 30
To change the settings later, run --install-schedule again with the new values. It replaces the old schedule. To see when the next backups will run:
systemctl list-timers 'fdcommander-backup*'
You should see two timers, fdcommander-backup-db.timer and fdcommander-backup.timer, each with its next run time. If the list is empty, run the --install-schedule command again and look for an error in its output.
To turn the schedule off, run sudo /var/www/fd-commander/backup.sh --remove-schedule. Backups that already exist stay where they are.
The timers catch up on missed runs, so a Pi stored in a closet between events will take a backup shortly after it boots. Each run is logged to /var/log/fd-commander-backup.log.
Cleanup goes by file age. If the Pi stays off for months, the first backup after you power it on will delete everything older than --keep-days, including last Field Day's backups. Copy the backups off before you put the Pi away (see below).
The schedule option is for native installs only. On a Docker host, run backup.sh --docker from cron instead. Create a file named /etc/cron.d/fd-commander with these two lines, changing /opt/fd-commander to the folder that holds your docker-compose.yml:
0 * * * * root cd /opt/fd-commander && ./backup.sh --docker --db-only
30 2 * * * root cd /opt/fd-commander && ./backup.sh --docker
That's a database backup on the hour and a full backup at 02:30, the same as the native timers. Docker backups go to a backups folder next to docker-compose.yml. If the path in the cron file is wrong, the jobs fail quietly. After the top of the next hour, check that a new fdc-db-* file has appeared in backups.
The log will show a mysqldump warning about using a password on the command line. That's expected, and the backup still completes.
The schedule runs on the clock, not on what's happening at your site. Take a full backup by hand before an update, right after the event ends, and before you shut the server down to pack it up. If an update goes wrong, a backup from five minutes earlier is much better than one from last night.
# Native install sudo /var/www/fd-commander/backup.sh # Docker, from the folder with docker-compose.yml sudo ./backup.sh --docker
You'll see a Wrote line for each file with its size, and then a line like Backup complete: /var/backups/fd-commander (stamp 20260628-180512). Note the stamp. You'll need it to copy or restore. Add --db-only to skip the photos and env file, which is quicker. Add --dest to write somewhere other than the default folder.
The backup folder belongs to root, so list it with sudo:
sudo ls -lh /var/backups/fd-commander
Hourly backups don't include photos or the env file. Only the nightly run and a backup by hand without --db-only write all three files.
A backup on the server's SD card or disk is lost if that card fails. Before you leave the site, copy the backups to a laptop or a USB drive.
scp copies files over SSH, but pointed at the backup folder it will fail with "Permission denied". The folder is readable by root only, and scp logs in as you. Instead, bundle the backups into your home folder with sudo, make the bundle yours, and copy that.
1 In an SSH session on the server, bundle the backups and make the bundle yours:
sudo tar -czf ~/fdc-backups.tar.gz -C /var/backups/fd-commander --exclude='pre-restore-*' . sudo chown "$USER" ~/fdc-backups.tar.gz
On a Docker host, use the backups folder next to your docker-compose.yml instead of /var/backups/fd-commander. The --exclude leaves out the pre-restore-* folders, which you won't need on the laptop.
2 On your laptop (not in the SSH session), copy the bundle down:
scp your-username@fd-commander.local:fdc-backups.tar.gz .
Open a new terminal window for this. You'll see a progress line reach 100%, and fdc-backups.tar.gz will be in the folder you ran it from.
3 Back on the server, delete the bundle so your passwords don't stay in your home folder:
rm ~/fdc-backups.tar.gz
PowerShell on Windows has scp and tar built in. To unpack the bundle, run tar -xzf fdc-backups.tar.gz in an empty folder.
To have backups go straight to a USB drive, plug it into the server and point the schedule at it with --dest, for example --dest /media/usb/fdc-backups. Format the drive as ext4, because the script sets Linux file permissions on the folder. If the drive isn't mounted when a timer runs, the backup will go to an ordinary folder on the SD card at that path.
The fdc-env-* files contain your APP_KEY, database password, and mail password. Keep your copies somewhere only club officers can reach, not in a shared club folder.
Backups that only live on the server won't help if the server is lost or its storage fails. Keep at least one copy on another device, and automate it if you can. Any of the options below will work, and you can combine them. On a Docker host, use the backups folder next to your docker-compose.yml in place of /var/backups/fd-commander.
Point the schedule at the drive with --dest (see above), or keep the schedule on the server and copy to the drive whenever it's plugged in:
sudo rsync -a /var/backups/fd-commander/ /media/usb/fdc-backups/
You can run it as often as you like, since rsync only copies what changed. Store the drive somewhere other than with the server.
If your club has a home server or NAS you can reach over SSH, rsync can copy new backups to it on a schedule. The backup folder is readable by root only, so the copy runs as root with root's own SSH key.
1 Create a key for root and authorize it on the other computer. Accept the default file and leave the passphrase empty, so the copy can run unattended:
sudo ssh-keygen -t ed25519 sudo ssh-copy-id backup@nas.local
2 Run a copy by hand to test it. You should see no errors, and the files should appear in fdc-backups on the other computer:
sudo rsync -a /var/backups/fd-commander/ backup@nas.local:fdc-backups/
3 Schedule it by creating /etc/cron.d/fdc-offsite with this line:
15 * * * * root rsync -a /var/backups/fd-commander/ backup@nas.local:fdc-backups/
This copies at a quarter past every hour, after the hourly backup. When the other computer can't be reached, such as at a site with no internet, the copy will fail and the next one will catch up.
The rsync manual explains the archive and deletion options. Leave out --delete. Without it, files that get wiped from the server stay on the other computer. The other side won't clean up old files on its own, so check its free space now and then.
restic keeps encrypted, versioned snapshots and only stores what changed, so months of history take little space. Because everything is encrypted, it's also a safe way to keep the env file's passwords off the server. It can write to a USB drive, another computer over SFTP, or cloud storage such as Backblaze B2 or Amazon S3.
1 Install restic and create a password file for it. On Rocky or AlmaLinux, restic comes from EPEL.
sudo apt install restic sudo sh -c 'openssl rand -base64 32 > /root/.restic-password && chmod 600 /root/.restic-password'
Save a copy of that password somewhere safe off the server. Without it, nobody can read the snapshots, including you.
2 Create the repository. This example uses the other computer over SFTP with root's SSH key from the rsync steps above. For a USB drive, use a path like /media/usb/restic instead.
sudo restic -r sftp:backup@nas.local:/srv/restic/fd-commander --password-file /root/.restic-password init
3 Schedule a nightly snapshot by creating /etc/cron.d/fdc-restic:
RESTIC_REPOSITORY=sftp:backup@nas.local:/srv/restic/fd-commander RESTIC_PASSWORD_FILE=/root/.restic-password 30 3 * * * root restic backup /var/backups/fd-commander && restic forget --keep-daily 14 --keep-weekly 8 --prune
This runs at 03:30, after the nightly full backup. It keeps two weeks of daily snapshots and eight weekly ones. See restic’s retention-policy documentation for how daily and weekly retention select snapshots.
To get files back, restore a snapshot to a folder, then use restore.sh on the files as described below:
sudo restic -r sftp:backup@nas.local:/srv/restic/fd-commander --password-file /root/.restic-password restore latest --target /root/fdc-restore
The restic restore documentation covers latest and --target. restic recreates the full path, so the files land in /root/fdc-restore/var/backups/fd-commander. Point restore.sh at the database file there. The matching files and env backups are next to it.
Pick the most recent good backup from before the problem occurred. List the files with sudo ls -lh and compare their timestamps with when things went wrong.
Point restore.sh at the database file. For a full restore, it finds the uploaded-files archive and settings backup by their matching timestamp. Keep all three files in the same folder.
A full restore replaces the database and uploaded files with the backup contents. Contacts logged and files uploaded after that backup will no longer be in the restored system. Settings handling differs between a same-server restore and a move to new hardware; see Moving to a New Server for the latter.
# Native install sudo /var/www/fd-commander/restore.sh /var/backups/fd-commander/fdc-db-20260628-023000.sql.gz # Docker, from the folder with docker-compose.yml sudo ./restore.sh backups/fdc-db-20260628-023000.sql.gz --docker
To restore an hourly backup, add --db-only. Without it, the script stops and tells you the files archive is missing. Photos and other uploads on the server stay as they are.
Before it changes anything, the script checks that the backup files are intact and that the database name matches this install. It then shows what it will restore and asks you to type yes. Read that summary before you answer. Anything else cancels the restore. Next it backs up the current data so the restore can be undone, stops Field Day Commander, loads the backup, runs any database updates, and starts everything back up. Nobody can log while that happens, so do it during a lull.
When it finishes, you'll see Field Day Commander Restore Complete! and the path to the pre-restore backup. The full output is saved to /var/log/fd-commander-restore.log.
Then sign in and check the log. The contact count and the last few QSOs should match the backup's time stamp.
You can restore an older backup onto a newer version of Field Day Commander, because the database updates run after the backup is loaded. The reverse doesn't work, so update the server first if the backup came from a newer release.
If the backup's APP_KEY doesn't match the server's, the script warns you that users with two-factor authentication will be locked out. On the same server, this usually means the .env file was rebuilt since the backup. Follow Moving to a New Server to bring the backup's key across.
Every restore saves the data it replaced in a pre-restore-YYYYMMDD-HHMMSS folder inside the backup folder. To undo a restore, restore the database file from that folder. Use sudo ls to find its name, since the folder is readable by root only:
sudo ls /var/backups/fd-commander/pre-restore-20260628-191544/ fdc-db-20260628-191544.sql.gz fdc-env-20260628-191544 fdc-files-20260628-191544.tar.gz sudo /var/www/fd-commander/restore.sh /var/backups/fd-commander/pre-restore-20260628-191544/fdc-db-20260628-191544.sql.gz
On Docker, the folder is in backups/ next to docker-compose.yml, and the command takes --docker. If you restored with --new-server, undo with --new-server too, so the old APP_KEY goes back.
If a restore fails partway, the script stops, lists the steps that finished, and prints the exact command to undo it. Run that command before you try any fixes by hand.
The same scripts handle a move to new hardware, such as an upgraded Pi or a replacement for a dead SD card. Install Field Day Commander on the new server first. You don't need to finish the setup wizard, since the restore replaces everything.
1 Install Field Day Commander on the new server with deploy.sh, as described in the Installation guide. Use the same release as the old server or a newer one. If the old server used a custom --db-name, use the same name here. The restore stops if the names don't match.
2 Copy all three files from one backup set to your home folder on the new server:
scp fdc-*-20260628-023000* your-username@fd-commander.local:~/
Pick a nightly or hand-made set. --new-server needs the env file, and hourly backups don't have one.
3 Restore with --new-server:
sudo /var/www/fd-commander/restore.sh ~/fdc-db-20260628-023000.sql.gz --new-server
This copies APP_KEY and the MAIL_* settings from the backup into the new server's .env, so two-factor sign-in and email keep working. The new server keeps its own database password. You'll get the usual yes prompt.
4 Sign in with your usual account. If you use two-factor authentication, your existing code should work. That means the key came across. Once you've checked the log, delete the backup files from your home folder.
--new-server is for native installs only. On Docker you have to copy the key yourself.
1 Set up the new host as described in the Docker section of the docs: clone the repository, run bash docker/setup.sh, and start the stack with docker compose up -d. The database container must be running for the restore to work.
2 Copy the three backup files into the backups folder next to docker-compose.yml, and restore:
sudo ./restore.sh backups/fdc-db-20260628-023000.sql.gz --docker
3 Open backups/fdc-env-20260628-023000 and copy the APP_KEY line, plus any MAIL_* lines, into the new host's .env. Leave DB_PASSWORD and DB_ROOT_PASSWORD alone. The new database volume was created with the new passwords and won't accept the old ones.
4 Run docker compose up -d so the app picks up the new key, then sign in and check the log. If two-factor codes are rejected, the APP_KEY line didn't make it into .env. Fix it and run the command again.
The scripts weren't tested for moving between a native install and Docker. The native install uses MariaDB and Docker uses MySQL, so if you try it, keep the old server until you've checked the result.
The --keep-days cleanup only removes backups at the top of the backup folder. The pre-restore-* folders are never deleted automatically, since they're your way back from a restore. Once you're happy with a restore, remove its folder by hand. Check the name first, because rm -r doesn't ask before it deletes:
sudo ls /var/backups/fd-commander sudo rm -r /var/backups/fd-commander/pre-restore-20260628-191544
With the default 7 days, you'll have about 168 hourly database backups plus 7 full sets. Field Day data is small, so this rarely matters. On a small SD card, check free space now and then with df -h.
Commands are for a native install. On Docker, run ./backup.sh and ./restore.sh from the folder with docker-compose.yml and add --docker.
| Task | Command |
|---|---|
| Turn on hourly and nightly backups | sudo /var/www/fd-commander/backup.sh --install-schedule |
| Check the schedule | systemctl list-timers 'fdcommander-backup*' |
| Turn off the schedule | sudo /var/www/fd-commander/backup.sh --remove-schedule |
| Full backup now | sudo /var/www/fd-commander/backup.sh |
| Database-only backup now | sudo /var/www/fd-commander/backup.sh --db-only |
| List backups | sudo ls -lh /var/backups/fd-commander |
| Restore a full backup | sudo /var/www/fd-commander/restore.sh /var/backups/fd-commander/fdc-db-STAMP.sql.gz |
| Restore an hourly backup | Same as above, plus --db-only |
| Restore onto a new server | Same as above, plus --new-server |
| Skip the confirmation prompt | Add --yes to restore.sh |
| Backup log | /var/log/fd-commander-backup.log |
| Restore log | /var/log/fd-commander-restore.log |
Sunday afternoon, after the last contact: take a full backup by hand, copy it to a laptop, and check that the laptop copy has all three files. Then shut the Pi down.