On this page

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 sudo on 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
  1. When you select Back up the server now, Starboard creates an empty file in requests. It is named backup, or backup-with-prompt when Include a rebuild prompt is active.
  2. Your job notices the file, removes it and makes the backup.
  3. While it works and when it finishes, the job writes backup.json (or backup-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

  1. Make the folders. This example uses /srv/starboard-jobs and /srv/backups:
sudo mkdir -p /srv/starboard-jobs/requests /srv/backups
  1. Give your user the requests folder, so Starboard, which runs as your user, can write to it:
sudo chown "$USER" /srv/starboard-jobs/requests
  1. 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
  1. 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
  1. 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
  1. Activate the path unit:
sudo systemctl daemon-reload
sudo systemctl enable --now starboard-backup.path
  1. 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
  1. Open the .env file in the same folder and set the two folders as paths inside Starboard:
STARBOARD_JOBS_DIR=/jobs
STARBOARD_BACKUP_DIR=/backups
  1. Start Starboard again so it reads the changes:

    docker compose up -d
  2. 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.md next 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_DIR set, the page lists the backups but cannot start one.
  • Your job can also write included and unreadable (lists of what went in and what could not be read), exit (its exit code) and runs (earlier results). Starboard shows them when they are there.
  • The same requests folder can run other jobs, such as a server check. Read Run a server job.
  • If you installed from the ready-made image, add the volumes lines and the two settings to compose.image.yaml instead. Write each setting in its environment list 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 requests line in compose.override.yaml does 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.