diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..2518ca8 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,56 @@ +# This workflow will build a golang project +# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-go + +name: Docs + +on: + push: + branches: ["main"] + workflow_dispatch: + +jobs: + jobs: + build: + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v3 + + - name: Set up NodeJS + uses: actions/setup-node@v2 + with: + node-version: "20" + + - name: Install dependencies + run: npm install --prefix ./docs + + - name: Build + run: npm run generate --prefix ./docs + + - name: Fix permissions + run: | + chmod -c -R +rX "./docs/dist/" | while read line; do + echo "::warning title=Invalid file permissions automatically fixed::$line" + done + + - name: Upload Pages artifact + uses: actions/upload-pages-artifact@v2 + with: + path: ./docs/dist + + deploy: + needs: build + + permissions: + pages: write + id-token: write + + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + + runs-on: ubuntu-latest + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/docs/.eslintrc.cjs b/docs/.eslintrc.cjs new file mode 100644 index 0000000..f0dc02b --- /dev/null +++ b/docs/.eslintrc.cjs @@ -0,0 +1,14 @@ +module.exports = { + root: true, + extends: ['@nuxt/eslint-config'], + ignorePatterns: [ + 'dist', + 'node_modules', + '.output', + '.nuxt' + ], + rules: { + 'vue/max-attributes-per-line': 'off', + 'vue/multi-word-component-names': 'off' + } +} \ No newline at end of file diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100755 index 0000000..69f6b69 --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1,12 @@ +node_modules +*.iml +.idea +*.log* +.nuxt +.vscode +.DS_Store +coverage +dist +sw.* +.env +.output diff --git a/docs/.npmrc b/docs/.npmrc new file mode 100644 index 0000000..cf04042 --- /dev/null +++ b/docs/.npmrc @@ -0,0 +1,2 @@ +shamefully-hoist=true +strict-peer-dependencies=false diff --git a/docs/app.config.ts b/docs/app.config.ts new file mode 100644 index 0000000..7076eda --- /dev/null +++ b/docs/app.config.ts @@ -0,0 +1,33 @@ +// https://github.com/nuxt-themes/docus/blob/main/nuxt.schema.ts +export default defineAppConfig({ + docus: { + title: 'Backrest', + description: 'Backrest is a web UI and orchestrator for restic backup.', + // image: 'https://user-images.githubusercontent.com/904724/185365452-87b7ca7b-6030-4813-a2db-5e65c785bf88.png', + socials: { + github: 'garethgeorge/backrest', + }, + github: { + dir: 'docs', + branch: 'main', + repo: 'backrest', + owner: 'garethgeorge', + edit: true + }, + aside: { + level: 0, + collapsed: false, + exclude: [] + }, + main: { + padded: true, + fluid: true + }, + header: { + logo: false, + showLinkIcon: true, + exclude: [], + fluid: true, + } + } +}) diff --git a/docs/content/0.index.md b/docs/content/0.index.md new file mode 100644 index 0000000..4b40cb4 --- /dev/null +++ b/docs/content/0.index.md @@ -0,0 +1,73 @@ +--- +title: Home +navigation: false +layout: page +main: + fluid: false +--- + +:ellipsis{right=0px width=75% blur=150px} + +::block-hero +--- +cta: + - Get started + - /introduction/getting-started +secondary: + - Open on GitHub → + - https://github.com/garethgeorge/backrest +--- + +#title +Web UI and orchestrator for [Restic](https://restic.net) backup. + +#description + +Backrest is a web-accessible backup solution built on top of [restic](https://restic.net/) and providing a WebUI which wraps the restic CLI and makes it easy to create repos, browse snapshots, and restore files. Additionally, Backrest can run in the background and take an opinionated approach to scheduling snapshots and orchestrating repo health operations. + + +#extra + ::list + - Import your existing restic repositories + - Cron scheduled backups and health operations (e.g. prune and forget) + - UI for browing and restoring files from snapshots + - Configurable backup notifications (e.g. Discord, Slack, Shoutrrr, Gotify) + - Add shell command hooks to run before and after backup operations. + - Compatible with rclone remotes + - Cross-platform support (Linux, MacOS, Windows, FreeBSD, [Docker](https://hub.docker.com/r/garethgeorge/backrest)) + - Backup to any restic supported storage (e.g. S3, B2, Azure, GCS, local, SFTP, and all [rclone remotes](https://rclone.org/)) + :: + +#support +::code-group +```bash [MacOS] +brew tap garethgeorge/homebrew-backrest-tap +brew install backrest +``` +```bash [Arch Linux] +paru -Sy backrest +sudo systemctl enable --now backreset@$USER.service +``` +```yaml [docker-compose] +version: "3.2" +services: + backrest: + image: garethgeorge/backrest + container_name: backrest + hostname: backrest + volumes: + - ./backrest/data:/data + - ./backrest/config:/config + - ./backrest/cache:/cache + - /MY-BACKUP-DATA:/userdata # mount your directories to backup somewhere in the filesystem + - /MY-REPOS:/repos # (optional) mount your restic repositories somewhere in the filesystem. + environment: + - BACKREST_DATA=/data # path for backrest data. restic binary and the database are placed here. + - BACKREST_CONFIG=/config/config.json # path for the backrest config file. + - XDG_CACHE_HOME=/cache # path for the restic cache which greatly improves performance. + restart: unless-stopped + ports: + - 9898:9898 +``` +:: +:: diff --git a/docs/content/1.introduction/1.getting-started.md b/docs/content/1.introduction/1.getting-started.md new file mode 100644 index 0000000..28ca830 --- /dev/null +++ b/docs/content/1.introduction/1.getting-started.md @@ -0,0 +1,87 @@ +# Getting Started + +This guide will walk you through the basic steps to setup a new [Backrest](https://github.com/garethgeorge/backrest) instance. + +## Installation + +See the Github README for installation instructions for your platform. + +## Terminology + + * **Restic Repo** Backrest uses [restic](https://restic.net) under-the-hood to manage backups. A restic repo is a location where restic will store your backup data, this detail is typically abstracted away from the user by Backrest but is important to understand as it means you have the option to use the restic CLI to interact with snapshots created by Backrest directly if you wish. + * **Repo** A Backrest repo (called a Repo from here on) is configuration data which identifies a location where your backup data will be stored (forwarded to restic), the credentials that will encrypt your backup data, hooks, and any options needed by backrest to orchestrate your backups. + * **Plan** A Backrest plan (called a Plan from here on) is configuration data that describes a schedule for taking snapshots, forgetting old snapshots, and running prune operations. Multiple plans can write data to the same Backrest repo. + * **Operations** + * A **Backup** creates a restic snapshot and send it to a repo. + * A **Forget** operation marks old snapshots for deletion but does not remove data from storage. + * A **Prune** operation removes data from storage that is no longer referenced by any snapshot (see [restic docs on forget and prune](https://restic.readthedocs.io/en/latest/060_forget.html)). + * A **Restore** operation retrieves files from a snapshot and writes them to a location on disk. + +## Configuration + +::alert{type="info"} +Once backrest is installed, you can access the web interface at `http://localhost:9898` (or the port you configured). Backrest will immediately prompt you to configure a default user and password (or you may disable authentication if you prefer). Once this is done, you can go on to configure your installation. +:: + +#### Add a new repository + +A Backrest repository is implemented as a restic repository under-the-hood (more on this later). A Repo is a configuration object which identifies a storage location and the credentials that will be used to encrypt snapshots sent to that storage. You can either add an existing repo that you created on the restic CLI or create a new one in the Backrest UI. In either case, click the "Add Repo" button in the UI to configure Backrest to use your backup location. + +The primary properties of a repository are: + + * **Repo Name** A human-readable name for the repository. This is used to identify the repository in the UI and is immutable after creation. + + * **Repo URI** identifies the location where the repo's data is stored. This corresponds to the URI used by restic. See [the restic docs](https://restic.readthedocs.io/en/stable/030_preparing_a_new_repo.html) for the repo types that restic supports. For common storage providers this looks like: + + * Backblaze: `b2:yourbucket` or `b2:yourbucket/pathprefix` + * AWS S3 (or S3 compatible storage): `s3:yourbucket` or `s3:yourbucket/pathprefix` + * Local path: `/mnt/backupdisk/repo1`. + * Rclone remote: `rclone:remote:path`. See the [rclone docs](https://rclone.org/docs/) for more information. To use rclone remotes, you must first install and configure rclone and ensure that the rclone config (e.g. `~/.config/rclone/rclone.conf`) is available to the backrest process. + + * **Environment Variables** environment variables provide additional configuration to restic (typically related to credentials for the storage provider). Common examples are + + * For S3 storage set: `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` + * For B2 storage set: `B2_ACCOUNT_ID` and `B2_ACCOUNT_KEY` + + * **Flags** additional flags to provide to restic. At the moment only presence flags are supported. Common usage might include: + + * `-o sftp.ssh_argument="-i /path/to/key"` will pass an SSH key to restic for use with SFTP repositories. + * `--force` will force rereading all files on each backup rather than relying on metadata (e.g. last modified time). This can be much slower. + * `--one-file-system` will prevent restic crossing filesystem boundaries. + * **Hooks** are actions triggered by backup lifecycle events, repo hooks will apply to actions run by any plan that writes to the repo. Hooks can also be configured at the plan level. See the [hooks documentation](/docs/hooks) for more information. + +::alert{type="info"} +Once you've added your repo you're ready to import snapshots (click Index Snapshots) if you have existing data. Go on to configure a backup plan to start creating new snapshots. +:: + +#### Configure a backup plan + +A Backrest plan is a configuration object which describes a schedule for taking snapshots, retention of old snapshots, and running prune operations. Multiple plans can write data to the same Backrest repo. To create a new plan, click the "Add Plan" button in the UI and populate the plan configuration: + +The primary properties of a plan are: + + * **Plan Name** the plan name is immutable after creation, choose carefully. Organizationally it can help to choose a name that includes the type of storage or a short form of the name of the repo that will be used. E.g. to backup "Documents" directory to "b2storage" you might create a plan named "b2-documents" or similar. + + * **Repository** the repository that this plan will operate on. This is immutable after creation. + + * **Paths** a list of paths to include in backups. + + * **Excludes** a list of paths to exclude from backup operations. These can be fully qualified paths (e.g. /foo/bar/baz) or wildcard paths (e.g. `*node_modules*`). See the [restic docs](https://restic.readthedocs.io/en/latest/040_backup.html#excluding-files) on excluding files for more details. Files listed in excludes map to restic's `--excludes` flag. + + * **Schedule** the schedule on which backups will run. This is expressed in cron format (configurable visually in the webui). + + * **Retention Policy** the duration that snapshots are retained for. This is enforced by running `restic forget` after each backup operation if a retention policy is specified. This can be set to none for append only repos or if you'd like to manage your own retention (e.g. run forget manually). Setting some retention policy is recommended to avoid the snapshot history growing without bound. Retention may be configured either based on count or bucketed by time period. See [the restic docs](https://restic.readthedocs.io/en/latest/060_forget.html#removing-snapshots-according-to-a-policy) to understand more about these policy options. Supported modes are: + + * **By Count** - keeps a fixed number of snapshots. E.g. keep the last 7 snapshots. + * **By Time Period** - keeps snapshots in a time-based bucket. E.g. keep 1 snapshot per day for the last 7 days, 1 snapshot per week for the last 4 weeks, and 1 snapshot per month for the last 12 months. + * **None** - no retention policy is enforced. This is useful for append-only repos or if you'd like to manage retention manually e.g. in an external script. Note that care should be taken not to allow snapshots to grow without bound (though Backrest will typically scale and perform well with hundreds to thousands of snapshots). + + * **Hooks** hooks are actions that can be configured in response to backup lifecycle events. See the hooks page of the wiki for more details. + +::alert{type="success"} +Success! Now that Backrest is configured you can sit back and let it manage your backups. You can monitor the status of your backups in the UI and restore files from snapshots as needed. +:: + +::alert{type="warning"} +Make sure that you save a copy of your repo credentials and any encryption keys (e.g. the password) in a safe place. If you lose these you will not be able to restore your data. It can be a good idea to store your entire Backrest config (typically located at `~/.config/backrest/config.json`) in a secure location e.g. a password manager or encrypted storage. +:: \ No newline at end of file diff --git a/docs/content/1.introduction/_dir.yml b/docs/content/1.introduction/_dir.yml new file mode 100644 index 0000000..ff0894d --- /dev/null +++ b/docs/content/1.introduction/_dir.yml @@ -0,0 +1,2 @@ +icon: ph:star-duotone +navigation.redirect: /introduction/getting-started diff --git a/docs/content/2.advanced/1.operations.md b/docs/content/2.advanced/1.operations.md new file mode 100644 index 0000000..224ccff --- /dev/null +++ b/docs/content/2.advanced/1.operations.md @@ -0,0 +1,60 @@ +# Operation Details + +This section describes the operations that Backrest can be configured to perform on your behalf in detail. + +## Overview + + +Backrest executes commands by forking the [restic][https://restic.net] binary. Each Backrest version is validated against a specific version of restic. On startup Backrest searches for a versioned restic in it's data directory (typically `~/.local/share/backrest`), followed by `/bin/`. The restic binary must be named `restic-{VERSION}`. You can overriderestic command by setting `BACKREST_RESTIC_COMMAND` env variable when starting Backrest. Otherwise, if no binary is found Backrest will download and install a recent version of restic from [restic's github releases](https://github.com/restic/restic/releases/tag/v0.16.4). When downloading a restic binary, the download is verified by checking the sha256sum of the downloaded binary against the sha256sum provided by restic and signed by the restic maintainers GPG key. + +When running restic commands, Backrest injects the environment variables configured in the repo into the environment of the restic process and it appends the flags configured in the repo to the command line arguments of the restic process. Logs are collected for each command. In the case of an error, Backrest captures the last ~500 bytes of output and displays this directly in the error message (the first and last 250 bytes are shown if the output is longer than 500 bytes). Logs of the command are typically also available by clicking \[View Logs\] next to an operation, these logs are truncated to 32KB (with the first and last 16KB shown if the log is longer than 32KB). + +## Types of Operations + +#### Backup + +[Restic docs on backup](https://restic.readthedocs.io/en/latest/040_backup.html) + +A backup operation creates a snapshot of your data and sends it to a repository. The snapshot is created using the `restic backup` command. + +As the backup runs Backrest will display the progress of the backup operation in the UI. The progress information is parsed from the JSON output of the `restic backup` command. + +The backup flow is as follows + + * Hook trigger: `CONDITION_SNAPSHOT_START`, if any hooks are configured for this event they will run. + * If any hook exits with a non-zero status, the hook's failure policy will be applied (e.g. cancelling or failing the backup operation). + * The `restic backup` command is run. The newly craeted snapshot is tagged with the ID of the plan creating it e.g. `plan:{PLAN_ID}`. + * The summary event is parsed from the backup and is stored in the operation's metadata. This includes: files added, files changed, files unmodified, total files processed, bytes added, bytes processed, and most importantly the snapshot ID. + * If an error occurred: hook trigger `CONDITION_SNAPSHOT_ERROR`, if any hooks are configured for this event they will run. + * Hook trigger: `CONDITION_SNAPSHOT_END`, if any hooks are configured for this event they will run. This condition is always triggered even if the backup failed. + +If the backup completed successfully, Backrest triggers followup operations + + * If a retention policy is set (e.g. not `None`) a forget operation is triggered for the backup plan. + * If a prune policy is set (e.g. not `None`) a prune operation is triggered for the backup plan if it has been long enough since the last prune operation. + +#### Forget + +[Restic docs on forget](https://restic.readthedocs.io/en/latest/060_forget.html) + +A forget operation marks old snapshots for deletion but does not remove data from storage until a prune runs. The forget operation is run using the `restic forget --tag plan:{PLAN_ID}` command. + +Retention policies are mapped to forget arguments: + + * **By Count** maps to `--keep-last {COUNT}` + * **By Time Period** maps to the `--keep-{hourly,daily,weekly,monthly,yearly} {COUNT}` flags + +Note that forget will never run for a plan if the forget policy is set to `None`. + +#### Prune + +[Restic docs on prune](https://restic.readthedocs.io/en/latest/060_forget.html) + +A prune operation removes data from storage that is no longer referenced by any snapshot. The prune operation is run using the `restic prune` command. Prune operations apply to the entire repo (e.g. are not scoped to data unreferenced by a specific plan). + +Prunes are run in compliance with a prune policy which specifies: + + * **Max Frequency Days** - the minimum time in days between prune operations. A prune is skipped following a backup if the last prune was less than this many days ago. This is to prevent excessive pruning which can be slow and is bandwidth intensive as prunes may read and rewrite portions of the repository. + * **Max Unused Percent** - the maximum percentage of the repository that may be left unused after a prune operation runs. Prune operations will try to repack blobs in the repository if more than this percentage of their is unused (e.g. formerly held data belonging to forgotten snapshots). + +Prune operations do not support json output so the logs of a prune operation are not parsed for progress information, they are instead displayed as raw text in the Backrest UI as they are received from the restic process. diff --git a/docs/content/2.advanced/2.hooks.md b/docs/content/2.advanced/2.hooks.md new file mode 100644 index 0000000..22c0fa0 --- /dev/null +++ b/docs/content/2.advanced/2.hooks.md @@ -0,0 +1,86 @@ +# Hook Details + +## Hook Types + +Backrest supports hooks in response to operation lifecycle events e.g. in response to the commands it runs on your behalf. + +Available event types are + + * `CONDITION_ANY_ERROR` any operation has failed. + * `CONDITION_SNAPSHOT_START` the start of a backup operation (e.g. corresponds to a call to `restic backup`) + * `CONDITION_SNAPSHOT_END` the end of a backup operation (e.g. corresponds to `restic backup` completing). Note that Snapshot End will still be called if a backup failed. + * `CONDITION_SNAPSHOT_ERROR` an error occurred during a backup operation (e.g. `restic backup` returned a non-zero exit code OR invalid output). + +Available notification services are + + * Discord webhook + * Gotify + * Shoutrrr destinations https://containrrr.dev/shoutrrr/v0.8/ + * Command (e.g. execute a shell script) + +## Notification Services + +| Service | Docs | +| -------- | ------------------------------------------------------------------------- | +| Discord | https://support.discord.com/hc/en-us/articles/228383668-Intro-to-Webhooks | +| Slack | https://api.slack.com/messaging/webhooks | +| Gotify | https://github.com/gotify/server | +| Shoutrrr | https://containrrr.dev/shoutrrr/v0.8/ | +| Command | See command cookbook | + +## Using Templates + +Most hooks will generate either a notification or execute a script. The script / notification is typically formatted as a Go template. The https://pkg.go.dev/text/template docs provide a very technical overview of Go template capabilities. See below for info about the available variables and for some examples. + +Variables + + * `Event:v1.Hook_Condition` - the event that triggered the backup. This is an enum. Values are one of: Hook_CONDITION_SNAPSHOT_START, Hook_CONDITION_SNAPSHOT_END, Hook_CONDITION_ANY_ERROR, Hook_CONDITION_SNAPSHOT_ERROR . + * `Task:string` - the name of the task that triggered the hook (e.g. `one time backup for plan "foo"` + * `Repo:v1.Repo` - the repo that triggered the backup. This is a struct. Access the name as `{{ .Repo.Id }}` + * `Plan:v1.Plan` - the plan that triggered the backup. This is a struct. Access the name as `{{ .Plan.Id }}` + * `SnapshotId:string` - the snapshot ID associated with the operation or empty string if none is associated. + * `SnapshotStats:restic.BackupProgressEntry` - summary of the current backup operation. This is a struct. See examples below for details. + * `CurTime:time.Time` - the current time. This is a struct. Format as `{{ .FormatTime .CurTime }}`. + * `Error:string` - the error message if an error occurred, or empty string if successful. + +Functions + + * `.Summary` - prints a default summary of the current event. + * `.FormatTime