Skip to content

10-Minute Tutorial

This page is the quickest path from zero to a working suisave setup.

The point is not to explain every option in the schema. The point is to get one local backup and one remote sync command running so the rest of the docs have some concrete context.

What you will do

In about ten minutes, you will:

  1. install suisave
  2. create a minimal local backup config
  3. run one local backup job
  4. create a minimal remote sync config
  5. run one remote push job

If you only care about one side, you can stop halfway through.

1. Install suisave

From PyPI:

pip install suisave

Then confirm the command exists:

suisave --version

You also need:

  • Linux
  • rsync
  • lsblk for the interactive drive helper

For the remote section later, make sure normal SSH access to the target machine already works.

2. Create a local backup config

Create the config directory:

mkdir -p ~/.config/suisave

Then create ~/.config/suisave/comet.toml:

[drives.MYDRIVE]
uuid = "PUT-YOUR-DRIVE-UUID-HERE"

[[jobs.backup]]
name = "documents"
sources = ["/home/YOURUSER/Documents"]
drives = ["MYDRIVE"]

If you do not know the UUID yet, list block devices:

lsblk -o NAME,LABEL,UUID,MOUNTPOINT

Pick the UUID of the mounted backup drive you want to use.

3. Run the local backup

With the drive mounted, run:

suisave run

If the config is correct, suisave will:

  • load ~/.config/suisave/comet.toml
  • resolve the drive mountpoint from the UUID
  • build the destination path
  • execute rsync

That is the core local-disk case working end to end.

4. Create a remote sync config

Move to a project directory:

cd /path/to/your/project

Create suisave.remote.toml:

[global]
default_rsync_flags = ["-azvh"]
default_remote_base = "backups"
default_mode = "push"

[connection]
host = "your-server.example.com"
user = "your-user"
port = 22
identity_file = "./.secrets/suisave_ed25519"

[[jobs.sync]]
name = "project"
sources = ["./"]
target_base = "projects/my-project"

This config says:

  • connect to the remote machine over SSH
  • treat the current directory as the source
  • sync it into backups/projects/my-project/... on the remote side

5. Run the remote sync

Push the project to the remote host:

suisave remote sync --config ./suisave.remote.toml --push

This makes the local side authoritative for the run.

If you later want to restore from the remote copy instead, use:

suisave remote sync --config ./suisave.remote.toml --pull

6. Understand the three direction modes

Remote sync is directional. That is the most important thing to understand before you rely on it.

  • --push: local wins
  • --pull: remote wins
  • --most-recent: suisave compares mtimes and chooses

If you are unsure, prefer --push or --pull explicitly. --most-recent is useful, but it is still a heuristic rather than true conflict resolution.

If the local example worked, continue with:

If the remote example worked, continue with:

Common first mistakes

  • using an unmounted drive in the local config
  • typing the wrong UUID
  • forgetting that remote sync always requires --config
  • assuming remote sync is bidirectional by default
  • expecting --most-recent to resolve ties automatically

If something goes wrong, check Troubleshooting.