Update documentation to recommend installing/upgrading borgmatic with pipx instead of pip.
This commit is contained in:
parent
d0a8251ad2
commit
0205748db8
4 changed files with 65 additions and 119 deletions
4
NEWS
4
NEWS
|
@ -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
|
||||||
|
|
|
@ -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
|
||||||
|
|
|
@ -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
|
||||||
|
|
|
@ -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
|
||||||
|
|
Loading…
Reference in a new issue