Backups

Introduction

Backups are a critical part of any system. They are the main defense against data loss. In the event of a catastrophic failure, backups are the only way to recover your data. It is important to have a backup strategy in place to ensure that your data is safe and secure.

Cosmos includes an entire backup system that allows you to easily create and manage backups of your data. This system is designed to be flexible and easy to use, allowing you to create backups on a schedule or manually. The backups are also encrypted for your security.

It uses Restic under the hood, allowing you more control, even if you were to stop using Cosmos.

Getting Started

To get started with backups, navigate to the Backups tab on the left-hand side of the Cosmos interface. This will take you to the backups page, where you can view and manage your backups.

This screen allows you to create backups (1), edit backups (by clicking the 3 dots on the right (2)) or view more details/restore your backup by clicking on the backup itself inside the table (3).

Creating a Backup

When you click the new backup button, you will see a modal pop up

Fill in the form to create a new backup:

• Name: The name of the backup, must be unique.
• Source: The folder source of the backup, aka. what folder you want to backup. If you are seeking to backup Docker volumes, use /var/lib/docker/volumes/{name}/_data. If you are ensure, you can open a container's details, go to storage, and backup the volume directly from there.
• Repository: The destination of the backup, aka. where you want to store the backup. This can be a local folder, a remote folder, or a cloud storage service. it is recommended that you store multiple backups in the same location, as Restic will deduplicate the data, meaning if multiple backups backs up the same file, it will only store it once.
• Cron Backup Schedule: The schedule of the backup. This is a cron expression that determines when the backup will run. It uses the 6 fields of a cron expression: second minute hour day month day-of-week. For example, 0 0 * * * * will run the backup every day at midnight.
• Cron Forget Schedule: The schedule of the forget operation. This is a cron expression that determines when the forget operation will run. This operation will prune old backups according to the retention policy.
• Retention Policy: The retention policy of the backup. This determines how long the backup will be kept. You can specify the number of backups to keep, or the duration to keep the backups for. For example, 7 will keep the last 7 backups, while 1w will keep the backups for 1 week.
• Automatically stop containers: If enabled, Cosmos will stop the containers that are using the folder/volume before backing it up. This is useful if you want to ensure that the data is in a consistent state before backing it up. It is recommended to enable this option if you are backing up Docker volumes, database data folders, config folders, etc... But if you are backing up large media storage, it is not required, as the data does not change often, also because the backup will be longer, and will keep your containers down for a longer time.

Managing a Backup

Clicking a backup in the table will get you to your backup details page. Here you can see the details of the backup, and restore it if needed.

Get to the restore tab to start restoring, or you can also restore from a recent snapshot by clicking the open button next to the snapshot you want to restore.

in this screen you will see

• (1) The list of snapshots. A snapshot is a backup at a specific time. You can restore from any snapshot. Select the snapshot you want to restore from, and the folder explorer will show you the files in that snapshot.
• (2) The restore button
• (3) The files explorer showing the files in the snapshot

You can either restore the entire snapshot, or select specific files to restore. Once you have made your choice, click Restore All (or Restore Selected) and it will ask you where you want to restore the files to. By default, it will show you the path of the original backup, to overwrite the current files. You can change this path to restore the files to a different location. It will not remove extra files that are not in the snapshot, if you want to clean up the folder completely, you will need to manually delete the folder's content before restoring it (or rather than deleting, move it to a different location, so you can revert the operation it if needed).

You can go to the snapshots tab in order to delete snapshots, and the event tab will show you the history of the backup, in term of successful (or not) operations.

Finally, you can see all the Backup jobs in the Scheduler tab on the left, you can manage, start/stop, and debug the backup operations from there as well.

Rclone

Cosmos integrates both Restic and Rclone together to allow you to backup your files to a remote location. The operation is quite seamless. Once you have connected a remote location in the storage > external storage tab, it will appear in the folder picker.

If you select it, the repository location will look like this: rclone:dropbox:/backups. This will backup the files to the Dropbox folder in the backups folder. Everything else will be exactly the same as a local backup in terms of configuration.

Manually use Restic

If you ever need to use Restic manually, in order to manage your backups (ex. if you leave Cosmos) you can do so with this command construction:

RESTIC_PASSWORD={{PASSWORD}} ./restic {{OPERATION}} -o rclone.program="./cosmos" -o rclone args="rclone serve --config=/var/lib/cosmos/rclone.conf restic --stdio --b2-hard-delete --verbose" --repo "/path/to/repo"

where {{OPERATION}} is the operation you want to do, like backup, restore, snapshots, forget, and {{PASSWORD}} is the repo password that you can find in the cosmos config file.