Files

The files type backs up a directory that the agent can read: uploads, application data, configuration, a Nextcloud data folder, and so on. No database driver is involved: the agent reads the files directly, so the directory must be mounted in the agent container.

Choose a methodCopy Anchor Link

Each source uses one of three methods. The method is chosen when the source is created and cannot be changed afterwards: to switch, create a new source.

• Archive is the simplest choice for small directories, and each backup is a self-contained file.
• Snapshots suits large directories that change little: each run only uploads what changed, and every snapshot can be restored.
• Sync keeps a browsable copy of the latest state on your storage. It is not a backup history.

ConfigurationCopy Anchor Link

Exclude patternsCopy Anchor Link

• A pattern without a leading / matches at any depth: node_modules excludes every node_modules folder.
• A pattern with a leading / is relative to the source path: /cache only excludes <path>/cache.
• * does not cross /; use ** to match across folders.
• Brace alternation (*.{log,tmp}) is not supported by Snapshots: list each pattern separately (*.log, *.tmp).

Excluded paths are not backed up and are left untouched by a restore. With Sync, files that match a pattern are deleted from the replica on the next run.

Mount the directoryCopy Anchor Link

The agent only sees the directories mounted in its container. Mount the directory read-write: restores write into it.

services:
  agent:
    image: portabase/agent:latest
    volumes:
      - ./databases.json:/config/config.json
      # Host directory -> path used for the source
      - /srv/uploads:/data/uploads
    environment:
      TZ: "Europe/Paris"
      EDGE_KEY: "..."

RestoreCopy Anchor Link

Archive and Snapshots restores make the directory match the backup:

1. The agent checks the backup first. A corrupt or truncated archive is rejected and nothing is changed.
2. Files that are not in the backup are removed, except excluded paths.
3. The backup content is written into the directory. When the agent runs as root, file ownership is restored too.

Sync sources cannot be restored from Portabase. The replica is a plain copy stored under <folder>/sync/<generated_id>/current on each storage: copy it back with your storage tools or rclone if needed.

Good to knowCopy Anchor Link

• Unreadable files fail the run. If a file cannot be read (permissions), an Archive or Snapshots run fails instead of producing a partial backup, because restoring it would delete that file. Fix the permissions or exclude the path.
• Empty source. A Sync run refuses to start when the directory is empty, so an unmounted volume cannot wipe the replica.
• Encryption. Archive backups are encrypted like any other backup when encryption is enabled, and can be decrypted with the CLI. Snapshots are always encrypted by restic, with a key derived from the agent key. The Sync replica is stored as plain files.
• Storages. Snapshots and Sync work with every storage provider. An Azure Blob storage needs an account key: connection strings that only hold a SAS token are not supported.
• Disk space on the agent. Archive builds the archive in the agent's temp directory (TMPDIR, /tmp by default), so it needs about the size of the directory free there, as for Docker volumes. Snapshots and Sync upload directly; Snapshots keeps a restic cache in the agent data folder.
• Retention. Snapshots follow the retention policy like other backups: removed backups are forgotten from the restic repository. Sync keeps a single state, so retention does not apply.