psw/borgmatic
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Update documentation to recommend installing/upgrading borgmatic with pipx instead of pip.

Browse source
This commit is contained in:
Dan Helfman 2023-09-04 16:25:10 -07:00
parent d0a8251ad2
commit 0205748db8
4 changed files with 65 additions and 119 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
NEWS
View file

@ -2,6 +2,10 @@
* #743: Add a monitoring hook for sending backup status and logs to to Grafana Loki. See the * #743: Add a monitoring hook for sending backup status and logs to to Grafana Loki. See the
documentation for more information: documentation for more information:
https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#loki-hook 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 1.8.2
* #345: Add "key export" action to export a copy of the repository key for safekeeping in case * #345: Add "key export" action to export a copy of the repository key for safekeeping in case

35
docs/how-to/develop-on-borgmatic.md
View file

@ -7,7 +7,12 @@ eleventyNavigation:
--- ---
## Source code ## 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 ```bash
git clone https://projects.torsion.org/borgmatic-collective/borgmatic.git 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 git clone ssh://git@projects.torsion.org:3022/borgmatic-collective/borgmatic.git
``` ```
Then, install borgmatic Finally, install borgmatic
"[editable](https://pip.pypa.io/en/stable/cli/pip_install/#editable-installs)" "[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 so that you can run borgmatic actions during development to make sure your
changes work. changes work:
```bash ```bash
cd borgmatic 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 To get oriented with the borgmatic source code, have a look at the [source
code reference](https://torsion.org/borgmatic/docs/reference/source-code/). code reference](https://torsion.org/borgmatic/docs/reference/source-code/).
## Automated tests ## Automated tests
Assuming you've cloned the borgmatic source code as described above, and Assuming you've cloned the borgmatic source code as described above and you're
you're in the `borgmatic/` working copy, install tox, which is used for in the `borgmatic/` working copy, install tox, which is used for setting up
setting up testing environments: 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 ```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 ```bash
tox tox

68
docs/how-to/set-up-backups.md
View file

@ -7,43 +7,30 @@ eleventyNavigation:
--- ---
## Installation ## Installation
Many users need to backup system files that require privileged access, so First, [install
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
Borg](https://borgbackup.readthedocs.io/en/stable/installation.html), at least Borg](https://borgbackup.readthedocs.io/en/stable/installation.html), at least
version 1.1. borgmatic does not install Borg automatically so as to avoid version 1.1. borgmatic does not install Borg automatically so as to avoid
conflicts with existing Borg installations. conflicts with existing Borg installations.
Then, download and install borgmatic as a [user site Then, [install pipx](https://pypa.github.io/pipx/installation/) as the root
installation](https://packaging.python.org/tutorials/installing-packages/#installing-to-the-user-site) user (with `sudo`) to make installing borgmatic easy without impacting other
by running the following command: 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. Finally, install borgmatic with pipx by running the following command:
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:
```bash ```bash
echo export 'PATH="$PATH:/root/.local/bin"' >> ~/.bashrc sudo pipx install borgmatic
source ~/.bashrc
``` ```
This adds `/root/.local/bin` to your non-root user's system `PATH`. Check whether all of this worked with:
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:
```bash ```bash
sudo borgmatic --version sudo borgmatic --version
@ -51,30 +38,11 @@ sudo borgmatic --version
If borgmatic is properly installed, that should output your 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 Many users need to backup system files that require privileged access, so
to run borgmatic, you can configure [sudo's these instructions install and run borgmatic as the root user. But if you
`secure_path` option](https://man.archlinux.org/man/sudoers.5) to include don't need to backup such files, you're welcome to install and run borgmatic
borgmatic's path. as a non-root user. To do that, run the `pipx` and `borgmatic` commands
above without `sudo`.
### 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.
### Other ways to install ### Other ways to install

77
docs/how-to/upgrade.md
View file

@ -7,26 +7,36 @@ eleventyNavigation:
--- ---
## Upgrading borgmatic ## Upgrading borgmatic
In general, all you should need to do to upgrade borgmatic is run the In general, all you should need to do to upgrade borgmatic if you've
following: [installed it with
pipx](https://torsion.org/borgmatic/docs/how-to/set-up-backups/#installation)
is to run the following:
```bash ```bash
sudo pip3 install --user --upgrade borgmatic sudo pipx upgrade borgmatic
``` ```
See below about special cases with old versions of borgmatic. Additionally, if (Or without `sudo` if you installed borgmatic as a non-root user.)
you installed borgmatic [without using `pip3 install
--user`](https://torsion.org/borgmatic/docs/how-to/set-up-backups/#other-ways-to-install), If you originally installed borgmatic with `sudo pip3 install --user`, you can
then your upgrade process may be different. 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 ### Upgrading your configuration
The borgmatic configuration file format is almost always backwards-compatible The borgmatic configuration file format is usually backwards-compatible from
from release to release without any changes, but you may still want to update release to release without any changes, but you may still want to update your
your configuration file when you upgrade to take advantage of new configuration file when you upgrade to take advantage of new configuration
configuration options. This is completely optional. If you prefer, you can add options or avoid old configuration from eventually becoming unsupported. If
new configuration options manually. you prefer, you can add new configuration options manually.
If you do want to upgrade your configuration file to include new options, use 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 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 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 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 to express lists of values. Modern versions of borgmatic no longer include
upgrade to the last version of borgmatic to support converting configuration: support for upgrading configuration files this old, but feel free to [file a
borgmatic 1.7.14. ticket](https://torsion.org/borgmatic/#issues) for help with upgrading any old
INI-style configuration files you may have.
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
```
## Upgrading Borg ## Upgrading Borg