Update documentation to recommend installing/upgrading borgmatic with pipx instead of pip.
This commit is contained in:
Dan Helfman
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
|
||||
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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in a new issue