diff --git a/NEWS b/NEWS index ff50e284..4422c172 100644 --- a/NEWS +++ b/NEWS @@ -1,3 +1,6 @@ +2.1.4.dev0 + * Split out borgmatic installation documentation to its own page, so it's easier to find. + 2.1.3 * #1175: Add a "files_changed" option for customizing Borg's file modification detection. * #1175: Add a "msgpack_version_check" option to prevent Borg from validating msgpack's version. diff --git a/docs/how-to/install-borgmatic.md b/docs/how-to/install-borgmatic.md new file mode 100644 index 00000000..3d1a719e --- /dev/null +++ b/docs/how-to/install-borgmatic.md @@ -0,0 +1,105 @@ +--- +title: 📥 How to install borgmatic +eleventyNavigation: + key: 📥 How to install borgmatic + parent: How-to guides + order: -1 +--- + +To install borgmatic, first [install +Borg](https://borgbackup.readthedocs.io/en/stable/installation.html), at least +version 1.1. (borgmatic does not install Borg automatically so as to avoid +conflicts with existing Borg installations.) + +Then, [install pipx](https://pypa.github.io/pipx/installation/) as the root +user (with `sudo`) to make installing borgmatic easier without impacting other +Python applications on your system. If you have trouble installing pipx with +pip, then you can install a system package instead. E.g. on Ubuntu or Debian, +run: + +```bash +sudo apt update +sudo apt install pipx +``` + +### Root install + +If you want to run borgmatic on a schedule with privileged access to your +files, then you should install borgmatic as the root user by running the +following commands: + +```bash +sudo pipx ensurepath +sudo pipx install borgmatic +``` + +Check whether this worked with: + +```bash +sudo su - +borgmatic --version +``` + +If borgmatic is properly installed, that should output your borgmatic version. +And if you'd also like `sudo borgmatic` to work, keep reading! + + +### Non-root install + +If you only want to run borgmatic as a non-root user (without privileged file +access) *or* you want to make `sudo borgmatic` work so borgmatic runs as root, +then install borgmatic as a non-root user by running the following commands as +that user: + +```bash +pipx ensurepath +pipx install borgmatic +``` + +This should work even if you've also installed borgmatic as the root user. + +Check whether this worked with: + +```bash +borgmatic --version +``` + +If borgmatic is properly installed, that should output your borgmatic version. +You can also try `sudo borgmatic --version` if you intend to run borgmatic +with `sudo`. If that doesn't work, you may need to update your [sudoers +`secure_path` option](https://wiki.archlinux.org/title/Sudo). + + +### Other ways to install + +Besides the approaches described above, there are several other options for +installing borgmatic: + +#### Docker / Podman + + * [container image with scheduled backups](https://github.com/borgmatic-collective/docker-borgmatic) (+ Docker Compose files) + * [container image with multi-arch and Docker CLI support](https://github.com/modem7/docker-borgmatic) + +#### Operating system packages + + * [Debian](https://tracker.debian.org/pkg/borgmatic) + * [Ubuntu](https://launchpad.net/ubuntu/+source/borgmatic) + * [Fedora](https://bodhi.fedoraproject.org/updates/?search=borgmatic) + * [Gentoo](https://packages.gentoo.org/packages/app-backup/borgmatic) + * [Arch Linux](https://archlinux.org/packages/extra/any/borgmatic/) + * [Alpine Linux](https://pkgs.alpinelinux.org/packages?name=borgmatic) + * [OpenBSD](https://openports.pl/path/sysutils/borgmatic) + * [openSUSE](https://software.opensuse.org/package/borgmatic) + * [macOS (via Homebrew)](https://formulae.brew.sh/formula/borgmatic) + * [macOS (via MacPorts)](https://ports.macports.org/port/borgmatic/) + * [NixOS](https://search.nixos.org/packages?channel=unstable&show=borgmatic&query=borgmatic) + +#### Etc. + + * [Ansible role](https://github.com/borgbase/ansible-role-borgbackup) + * [uv tool install](https://docs.astral.sh/uv/) + + +## Next steps + +* [Set up backups](https://torsion.org/borgmatic/how-to/set-up-backups/) diff --git a/docs/how-to/set-up-backups.md b/docs/how-to/set-up-backups.md index fc26c3e4..1ea5ba42 100644 --- a/docs/how-to/set-up-backups.md +++ b/docs/how-to/set-up-backups.md @@ -1,104 +1,14 @@ --- -title: 📥 How to set up backups +title: 📋 How to set up backups eleventyNavigation: - key: 📥 Set up backups + key: 📋 Set up backups parent: How-to guides order: 0 --- -To install borgmatic, first [install -Borg](https://borgbackup.readthedocs.io/en/stable/installation.html), at least -version 1.1. (borgmatic does not install Borg automatically so as to avoid -conflicts with existing Borg installations.) - -Then, [install pipx](https://pypa.github.io/pipx/installation/) as the root -user (with `sudo`) to make installing borgmatic easier without impacting other -Python applications on your system. If you have trouble installing pipx with -pip, then you can install a system package instead. E.g. on Ubuntu or Debian, -run: - -```bash -sudo apt update -sudo apt install pipx -``` - -### Root install - -If you want to run borgmatic on a schedule with privileged access to your -files, then you should install borgmatic as the root user by running the -following commands: - -```bash -sudo pipx ensurepath -sudo pipx install borgmatic -``` - -Check whether this worked with: - -```bash -sudo su - -borgmatic --version -``` - -If borgmatic is properly installed, that should output your borgmatic version. -And if you'd also like `sudo borgmatic` to work, keep reading! - - -### Non-root install - -If you only want to run borgmatic as a non-root user (without privileged file -access) *or* you want to make `sudo borgmatic` work so borgmatic runs as root, -then install borgmatic as a non-root user by running the following commands as -that user: - -```bash -pipx ensurepath -pipx install borgmatic -``` - -This should work even if you've also installed borgmatic as the root user. - -Check whether this worked with: - -```bash -borgmatic --version -``` - -If borgmatic is properly installed, that should output your borgmatic version. -You can also try `sudo borgmatic --version` if you intend to run borgmatic -with `sudo`. If that doesn't work, you may need to update your [sudoers -`secure_path` option](https://wiki.archlinux.org/title/Sudo). - - -### Other ways to install - -Besides the approaches described above, there are several other options for -installing borgmatic: - -#### Docker / Podman - - * [container image with scheduled backups](https://github.com/borgmatic-collective/docker-borgmatic) (+ Docker Compose files) - * [container image with multi-arch and Docker CLI support](https://github.com/modem7/docker-borgmatic) - -#### Operating system packages - - * [Debian](https://tracker.debian.org/pkg/borgmatic) - * [Ubuntu](https://launchpad.net/ubuntu/+source/borgmatic) - * [Fedora](https://bodhi.fedoraproject.org/updates/?search=borgmatic) - * [Gentoo](https://packages.gentoo.org/packages/app-backup/borgmatic) - * [Arch Linux](https://archlinux.org/packages/extra/any/borgmatic/) - * [Alpine Linux](https://pkgs.alpinelinux.org/packages?name=borgmatic) - * [OpenBSD](https://openports.pl/path/sysutils/borgmatic) - * [openSUSE](https://software.opensuse.org/package/borgmatic) - * [macOS (via Homebrew)](https://formulae.brew.sh/formula/borgmatic) - * [macOS (via MacPorts)](https://ports.macports.org/port/borgmatic/) - * [NixOS](https://search.nixos.org/packages?channel=unstable&show=borgmatic&query=borgmatic) - -#### Etc. - - * [Ansible role](https://github.com/borgbase/ansible-role-borgbackup) - * [uv tool install](https://docs.astral.sh/uv/) - +Start by [installing +borgmatic](https://torsion.org/borgmatic/how-to/install-borgmatic/) if you haven't +already. ## Hosting providers @@ -322,7 +232,7 @@ If you're using systemd instead of cron to run jobs, you can still configure borgmatic to run automatically. (If you installed borgmatic from [Other ways to -install](https://torsion.org/borgmatic/how-to/set-up-backups/#other-ways-to-install), +install](https://torsion.org/borgmatic/how-to/install-borgmatic/#other-ways-to-install), you may already have borgmatic systemd service and timer files. If so, you may be able to skip some of the steps below.) diff --git a/docs/how-to/upgrade.md b/docs/how-to/upgrade.md index b6cc82da..9d3c8539 100644 --- a/docs/how-to/upgrade.md +++ b/docs/how-to/upgrade.md @@ -7,7 +7,7 @@ eleventyNavigation: --- In general, all you should need to do to upgrade borgmatic if you've [installed it with -pipx](https://torsion.org/borgmatic/how-to/set-up-backups/#installation) +pipx](https://torsion.org/borgmatic/how-to/install-borgmatic/) is to run the following: ```bash @@ -21,11 +21,11 @@ upgrade each installation independently. If you originally installed borgmatic with `sudo pip3 install --user`, you can uninstall it first with `sudo pip3 uninstall borgmatic` and then [install it again with -pipx](https://torsion.org/borgmatic/how-to/set-up-backups/#installation), +pipx](https://torsion.org/borgmatic/how-to/install-borgmatic/), which should better isolate borgmatic from your other Python applications. But if you [installed borgmatic without pipx or -pip3](https://torsion.org/borgmatic/how-to/set-up-backups/#other-ways-to-install), +pip3](https://torsion.org/borgmatic/how-to/install-borgmatic/#other-ways-to-install), then your upgrade method may be different. diff --git a/docs/reference/configuration/monitoring/apprise.md b/docs/reference/configuration/monitoring/apprise.md index 24feb62d..17f68965 100644 --- a/docs/reference/configuration/monitoring/apprise.md +++ b/docs/reference/configuration/monitoring/apprise.md @@ -12,7 +12,7 @@ us today such as: Telegram, Discord, Slack, Amazon SNS, Gotify, etc." Depending on how you installed borgmatic, it may not have come with Apprise. For instance, if you originally [installed borgmatic with -pipx](https://torsion.org/borgmatic/how-to/set-up-backups/), +pipx](https://torsion.org/borgmatic/how-to/install-borgmatic/), run the following to install Apprise so borgmatic can use it: ```bash diff --git a/pyproject.toml b/pyproject.toml index 14c88071..a909d1ac 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "borgmatic" -version = "2.1.3" +version = "2.1.4.dev0" authors = [ { name="Dan Helfman", email="witten@torsion.org" }, ]