How-to
Back up the whole server
Starboard can start a backup of your whole server and list the files it made, on Settings, General, Backup and restore. A job you set up on the server makes the backup, so Starboard never reads the server's files.
You write a small script, set up a systemd service and change Docker's settings. If that is new to you, start with Back up and restore Starboard's settings, which needs none of it.
Before you begin
- You installed Starboard with the installer, and you can use
sudoon the server. - You know what you want to back up, such as each app's settings folder, and where to keep the backups.
- You know the basics in What Docker is and The terminal: entering commands.
How it works
Starboard and the job talk through two folders on the server:
| Setting | What the folder is for | Path inside Starboard |
|---|---|---|
STARBOARD_JOBS_DIR |
Holds a requests folder and the job's result files |
Read-only, except requests, which it can write to |
STARBOARD_BACKUP_DIR |
Where the job saves its backup files | Read-only |
- When you select Back up the server now, Starboard creates an empty file in
requests. It is namedbackup, orbackup-with-promptwhen Include a rebuild prompt is active. - Your job notices the file, removes it and makes the backup.
- While it works and when it finishes, the job writes
backup.json(orbackup-with-prompt.json) in the jobs folder. Starboard reads it to show the result.
The result file is JSON (a text format for data) with these fields:
| Field | What to put in it |
|---|---|
status |
running, done or failed |
started |
When the backup started, in seconds since 1 January 1970 (the output of date +%s) |
finished |
When it finished, in the same form |
summary |
One sentence about the result, shown on the page |
Starboard lists the files in the backup folder that end in .zip, .tar, .tar.gz, .tgz, .gz, .7z,
.dump, .sql or .md, newest first.
Steps
- Make the folders. This example uses
/srv/starboard-jobsand/srv/backups:
sudo mkdir -p /srv/starboard-jobs/requests /srv/backups
- Give your user the
requestsfolder, so Starboard, which runs as your user, can write to it:
sudo chown "$USER" /srv/starboard-jobs/requests
- Write the job's script. This command opens a new file in a text editor:
sudo nano /usr/local/bin/starboard-backup.sh
Paste this example, and change the folders after tar -czf to the ones you want to back up:
#!/usr/bin/env bash
# An example to start from: one archive of the folders listed after tar -czf.
set -u
JOBS=/srv/starboard-jobs
OUT=/srv/backups
for name in backup backup-with-prompt; do
[ -f "$JOBS/requests/$name" ] || continue
rm -f "$JOBS/requests/$name"
started=$(date +%s)
printf '{"status": "running", "started": %s}\n' "$started" > "$JOBS/$name.json"
if tar -czf "$OUT/server-$(date +%Y-%m-%d-%H%M).tar.gz" /etc /srv/appdata; then
status=done; summary="Saved /etc and /srv/appdata"
else
status=failed; summary="tar stopped with an error"
fi
printf '{"status": "%s", "started": %s, "finished": %s, "summary": "%s"}\n' \
"$status" "$started" "$(date +%s)" "$summary" > "$JOBS/$name.json"
done
Save the file: press Ctrl+O, then Enter, then Ctrl+X. 4. Let the script run:
sudo chmod +x /usr/local/bin/starboard-backup.sh
- Make a systemd service that runs the script. Open a new file:
sudo nano /etc/systemd/system/starboard-backup.service
Paste this and save:
[Unit]
Description=Starboard server backup
[Service]
Type=oneshot
ExecStart=/usr/local/bin/starboard-backup.sh
- Make a systemd path unit, which starts the service when a request file appears. Open a new file:
sudo nano /etc/systemd/system/starboard-backup.path
Paste this and save:
[Unit]
Description=Start the Starboard server backup when asked
[Path]
PathExists=/srv/starboard-jobs/requests/backup
PathExists=/srv/starboard-jobs/requests/backup-with-prompt
[Install]
WantedBy=multi-user.target
- Activate the path unit:
sudo systemctl daemon-reload
sudo systemctl enable --now starboard-backup.path
- Show the folders to Starboard. In the Starboard folder, open
compose.override.yaml(create it if it is not there):
nano compose.override.yaml
Add these lines. If the file already has a volumes list, add only the three lines that start with -:
services:
starboard:
volumes:
- /srv/starboard-jobs:/jobs:ro
- /srv/starboard-jobs/requests:/jobs/requests
- /srv/backups:/backups:ro
- Open the
.envfile in the same folder and set the two folders as paths inside Starboard:
STARBOARD_JOBS_DIR=/jobs
STARBOARD_BACKUP_DIR=/backups
-
Start Starboard again so it reads the changes:
docker compose up -d -
Go to Settings, then General, then Backup and restore, and select Back up the server now.
The status shows Starting, then Backing up now, then Complete or Failed. The server picks up the request within a minute. The new file then appears in the list of server backups.
Things to note
- Starboard cannot restore the whole server. To restore, copy the files back on the server yourself, or follow the rebuild prompt.
- With Include a rebuild prompt active, your job can also save
REBUILD-PROMPT.mdnext to the backup: steps an AI assistant with a shell can follow to rebuild the server. The example script does not write one. - Select a backup in the list to open its details, then Download to save it. Starboard asks for your password first, because a server backup can hold API keys and private files.
- The backups are on the same server. If its disk fails, they go with it, so copy the newest one to another disk or computer.
- With only
STARBOARD_BACKUP_DIRset, the page lists the backups but cannot start one. - Your job can also write
includedandunreadable(lists of what went in and what could not be read),exit(its exit code) andruns(earlier results). Starboard shows them when they are there. - The same
requestsfolder can run other jobs, such as a server check. Read Run a server job. - If you installed from the ready-made image, add the
volumeslines and the two settings tocompose.image.yamlinstead. Write each setting in itsenvironmentlist as- STARBOARD_JOBS_DIR=/jobs.
If it does not work
- The page says "No server backup job is set up": Starboard did not get the two settings. Check
.env, then repeat step 10. - "the requests folder is not writable": repeat step 2, and check the
requestsline incompose.override.yamldoes not end in:ro. - The status stays on Starting: the path unit is not running. Check it with this command:
systemctl status starboard-backup.path
- The status shows Failed: read the job's own messages with this command:
journalctl -u starboard-backup.service
Find out more
This page on GitHub, where the help is written.