From 0205748db82d88939505873724a620a2858a258e Mon Sep 17 00:00:00 2001 From: Dan Helfman Date: Mon, 4 Sep 2023 16:25:10 -0700 Subject: [PATCH] Update documentation to recommend installing/upgrading borgmatic with pipx instead of pip. --- NEWS | 4 ++ docs/how-to/develop-on-borgmatic.md | 35 +++++++------ docs/how-to/set-up-backups.md | 68 +++++++------------------ docs/how-to/upgrade.md | 77 ++++++++++------------------- 4 files changed, 65 insertions(+), 119 deletions(-) diff --git a/NEWS b/NEWS index fe07f8d4..b52cfeae 100644 --- a/NEWS +++ b/NEWS @@ -2,6 +2,10 @@ * #743: Add a monitoring hook for sending backup status and logs to to Grafana Loki. See the documentation for more information: https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#loki-hook + * Update documentation to recommend installing/upgrading borgmatic with pipx instead of pip. See the + documentation for more information: + https://torsion.org/borgmatic/docs/how-to/set-up-backups/#installation + https://torsion.org/borgmatic/docs/how-to/upgrade/#upgrading-borgmatic 1.8.2 * #345: Add "key export" action to export a copy of the repository key for safekeeping in case diff --git a/docs/how-to/develop-on-borgmatic.md b/docs/how-to/develop-on-borgmatic.md index 761b9240..d71cdb85 100644 --- a/docs/how-to/develop-on-borgmatic.md +++ b/docs/how-to/develop-on-borgmatic.md @@ -7,7 +7,12 @@ eleventyNavigation: --- ## Source code -To get set up to develop on borgmatic, first clone it via HTTPS or SSH: +To get set up to develop on borgmatic, first [`install +pipx`](https://torsion.org/borgmatic/docs/how-to/set-up-backups/#installation) +to make managing your borgmatic environment easy without impacting other +Python applications on your system. + +Then, clone borgmatic via HTTPS or SSH: ```bash git clone https://projects.torsion.org/borgmatic-collective/borgmatic.git @@ -19,39 +24,33 @@ Or: git clone ssh://git@projects.torsion.org:3022/borgmatic-collective/borgmatic.git ``` -Then, install borgmatic -"[editable](https://pip.pypa.io/en/stable/cli/pip_install/#editable-installs)" +Finally, install borgmatic +"[editable](https://pip.pypa.io/en/stable/topics/local-project-installs/#editable-installs)" so that you can run borgmatic actions during development to make sure your -changes work. +changes work: ```bash cd borgmatic -pip3 install --user --editable . +pipx install --editable . ``` -Note that this will typically install the borgmatic commands into -`~/.local/bin`, which may or may not be on your PATH. There are other ways to -install borgmatic editable as well, for instance into the system Python -install (so without `--user`, as root), or even into a -[virtualenv](https://virtualenv.pypa.io/en/stable/). How or where you install -borgmatic is up to you, but generally an editable install makes development -and testing easier. - To get oriented with the borgmatic source code, have a look at the [source code reference](https://torsion.org/borgmatic/docs/reference/source-code/). ## Automated tests -Assuming you've cloned the borgmatic source code as described above, and -you're in the `borgmatic/` working copy, install tox, which is used for -setting up testing environments: +Assuming you've cloned the borgmatic source code as described above and you're +in the `borgmatic/` working copy, install tox, which is used for setting up +testing environments. You can either install a system package of tox (likely +called `tox` or `python-tox`) or you can install tox with pipx: ```bash -pip3 install --user tox +pipx install tox ``` -Finally, to actually run tests, run: +Finally, to actually run tests, run tox from inside the borgmatic +sourcedirectory: ```bash tox diff --git a/docs/how-to/set-up-backups.md b/docs/how-to/set-up-backups.md index 45fa9442..aa8176df 100644 --- a/docs/how-to/set-up-backups.md +++ b/docs/how-to/set-up-backups.md @@ -7,43 +7,30 @@ eleventyNavigation: --- ## Installation -Many users need to backup system files that require privileged access, so -these instructions install and run borgmatic as root. If you don't need to -backup such files, then you are welcome to install and run borgmatic as a -non-root user. - -First, manually [install +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, download and install borgmatic as a [user site -installation](https://packaging.python.org/tutorials/installing-packages/#installing-to-the-user-site) -by running the following command: +Then, [install pipx](https://pypa.github.io/pipx/installation/) as the root +user (with `sudo`) to make installing borgmatic easy 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 pip3 install --user --upgrade borgmatic +``` +sudo apt update +sudo apt install pipx +sudo pipx ensurepath ``` -This installs borgmatic and its commands at the `/root/.local/bin` path. - -Your pip binary may have a different name than "pip3". Make sure you're using -Python 3.7+, as borgmatic does not support older versions of Python. - -The next step is to ensure that borgmatic's commands available are on your -system `PATH`, so that you can run borgmatic: +Finally, install borgmatic with pipx by running the following command: ```bash -echo export 'PATH="$PATH:/root/.local/bin"' >> ~/.bashrc -source ~/.bashrc +sudo pipx install borgmatic ``` -This adds `/root/.local/bin` to your non-root user's system `PATH`. - -If you're using a command shell other than Bash, you may need to use different -commands here. - -You can check whether all of this worked with: +Check whether all of this worked with: ```bash sudo borgmatic --version @@ -51,30 +38,11 @@ sudo borgmatic --version If borgmatic is properly installed, that should output your borgmatic version. -As an alternative to adding the path to `~/.bashrc` file, if you're using sudo -to run borgmatic, you can configure [sudo's -`secure_path` option](https://man.archlinux.org/man/sudoers.5) to include -borgmatic's path. - - -### Global install option - -If you try the user site installation above and have problems making borgmatic -commands runnable on your system `PATH`, an alternate approach is to install -borgmatic globally. - -The following uninstalls borgmatic and then reinstalls it such that borgmatic -commands are on the default system `PATH`: - -```bash -sudo pip3 uninstall borgmatic -sudo pip3 install --upgrade borgmatic -``` - -The main downside of a global install is that borgmatic is less cleanly -separated from the rest of your Python software, and there's the theoretical -possibility of library conflicts. But if you're okay with that, for instance -on a relatively dedicated system, then a global install can work out fine. +Many users need to backup system files that require privileged access, so +these instructions install and run borgmatic as the root user. But if you +don't need to backup such files, you're welcome to install and run borgmatic +as a non-root user. To do that, run the `pipx` and `borgmatic` commands +above without `sudo`. ### Other ways to install diff --git a/docs/how-to/upgrade.md b/docs/how-to/upgrade.md index ff9f109b..d053f21c 100644 --- a/docs/how-to/upgrade.md +++ b/docs/how-to/upgrade.md @@ -7,26 +7,36 @@ eleventyNavigation: --- ## Upgrading borgmatic -In general, all you should need to do to upgrade borgmatic is run the -following: +In general, all you should need to do to upgrade borgmatic if you've +[installed it with +pipx](https://torsion.org/borgmatic/docs/how-to/set-up-backups/#installation) +is to run the following: ```bash -sudo pip3 install --user --upgrade borgmatic +sudo pipx upgrade borgmatic ``` -See below about special cases with old versions of borgmatic. Additionally, if -you installed borgmatic [without using `pip3 install ---user`](https://torsion.org/borgmatic/docs/how-to/set-up-backups/#other-ways-to-install), -then your upgrade process may be different. +(Or without `sudo` if you installed borgmatic as a non-root user.) + +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/docs/how-to/set-up-backups/#installation), +which should better isolate borgmatic from your other Python applications. + +But if you [installed borgmatic without pipx or +pip3](https://torsion.org/borgmatic/docs/how-to/set-up-backups/#other-ways-to-install), +then your upgrade method may be different. + ### Upgrading your configuration -The borgmatic configuration file format is almost always backwards-compatible -from release to release without any changes, but you may still want to update -your configuration file when you upgrade to take advantage of new -configuration options. This is completely optional. If you prefer, you can add -new configuration options manually. +The borgmatic configuration file format is usually backwards-compatible from +release to release without any changes, but you may still want to update your +configuration file when you upgrade to take advantage of new configuration +options or avoid old configuration from eventually becoming unsupported. If +you prefer, you can add new configuration options manually. If you do want to upgrade your configuration file to include new options, use the `borgmatic config generate` action with its optional `--source` flag that @@ -64,45 +74,10 @@ and, if desired, replace your original configuration file with it. borgmatic changed its configuration file format in version 1.1.0 from INI-style to YAML. This better supports validation and has a more natural way -to express lists of values. To upgrade your existing configuration, first -upgrade to the last version of borgmatic to support converting configuration: -borgmatic 1.7.14. - -As of version 1.1.0, borgmatic no longer supports Python 2. If you were -already running borgmatic with Python 3, then you can upgrade borgmatic -in-place: - -```bash -sudo pip3 install --user --upgrade borgmatic==1.7.14 -``` - -But if you were running borgmatic with Python 2, uninstall and reinstall instead: - -```bash -sudo pip uninstall borgmatic -sudo pip3 install --user borgmatic==1.7.14 -``` - -The pip binary names for different versions of Python can differ, so the above -commands may need some tweaking to work on your machine. - - -Once borgmatic is upgraded, run: - -```bash -sudo upgrade-borgmatic-config -``` - -That will generate a new YAML configuration file at /etc/borgmatic/config.yaml -(by default) using the values from both your existing configuration and -excludes files. The new version of borgmatic will consume the YAML -configuration file instead of the old one. - -Now you can upgrade to a newer version of borgmatic: - -```bash -sudo pip3 install --user borgmatic -``` +to express lists of values. Modern versions of borgmatic no longer include +support for upgrading configuration files this old, but feel free to [file a +ticket](https://torsion.org/borgmatic/#issues) for help with upgrading any old +INI-style configuration files you may have. ## Upgrading Borg