162 lines
5 KiB
ReStructuredText
162 lines
5 KiB
ReStructuredText
|
|
.. highlight:: sh
|
|
|
|
==============
|
|
Installation
|
|
==============
|
|
|
|
As usual there is more than one way to go about this. You basically
|
|
have these 2 options out of the gate:
|
|
|
|
* manual install
|
|
* scripted install via Fabric
|
|
|
|
Choice is yours. If you are interested in Fabric, see
|
|
:doc:`/deploy/index` and the ``rattail_fabric2.backup`` module for
|
|
more info. That (rattail-fabric2) package is available on PyPI, or
|
|
can peek at the `module source`_.
|
|
|
|
.. _module source: https://forgejo.wuttaproject.org/rattail/rattail-fabric2/src/branch/master/rattail_fabric2/backup.py
|
|
|
|
Here we will only describe the manual installation.
|
|
|
|
The following links offer more background should you want it. But
|
|
we'll provide the basic commands you need, further below.
|
|
|
|
* :doc:`/base/reqs`
|
|
* :doc:`/base/venv`
|
|
* :doc:`/base/install/index`
|
|
|
|
Note also, the steps below are "established convention" so to speak,
|
|
but only in the Rattail world. If you follow along exactly then
|
|
things should work, but you of course can tweak as needed.
|
|
|
|
|
|
Virtual Environment
|
|
===================
|
|
|
|
If you don't already have one, make a home for virtual environments.
|
|
|
|
Note that we assume this folder should be owned by the ``rattail``
|
|
user account. If you don't have that, specify a different owner::
|
|
|
|
sudo mkdir -p /srv/envs
|
|
sudo chown rattail: /srv/envs
|
|
|
|
Then make your ``backup`` virtual environment::
|
|
|
|
sudo -u rattail python3 -m venv /srv/envs/backup
|
|
|
|
|
|
Backup App
|
|
==========
|
|
|
|
Install the Rattail package to the virtual environment. Note that we
|
|
specify ``rattail[backup]`` which causes it to also install Borg::
|
|
|
|
cd /srv/envs/backup
|
|
sudo -u rattail bin/pip install rattail[backup]
|
|
|
|
You can just use ``pip install rattail`` instead if you do not want Borg.
|
|
|
|
We then invoke Rattail to create our ``app`` folder, which is where
|
|
config will live::
|
|
|
|
cd /srv/envs/backup
|
|
sudo -u rattail bin/rattail make-appdir
|
|
|
|
And that's it for the software, unless you also want ``rsync``::
|
|
|
|
sudo apt install rsync
|
|
|
|
|
|
Backup Scripts
|
|
==============
|
|
|
|
It is suggested that you also create the following scripts, for
|
|
convenience.
|
|
|
|
Note that these scripts will *not* work properly until you add config
|
|
files; see :doc:`config`. But it's fine to get the scripts in place
|
|
first since they probably won't need to change later on.
|
|
|
|
Note also that these scripts are designed to be ran only by the
|
|
``root`` user. They will warn and not take action, when ran by anyone
|
|
else.
|
|
|
|
|
|
Script: ``rattail-backup``
|
|
--------------------------
|
|
|
|
The purpose of this script is simply to wrap the underlying ``rattail
|
|
backup`` command, specifying the appropriate config file etc. Any
|
|
arguments you pass to it will be passed on to the command.
|
|
|
|
Instead of listing the contents of this file here, we will direct you
|
|
to the "official" copy which can be deployed via Fabric:
|
|
|
|
`<https://forgejo.wuttaproject.org/rattail/rattail-fabric2/src/branch/master/rattail_fabric2/deploy/backup/rattail-backup.mako>`_
|
|
|
|
You will need to (globally) replace the text ``${envname}`` with
|
|
``backup`` but otherwise that can be used as-is.
|
|
|
|
Place this file at ``/usr/local/bin/rattail-backup`` and make it
|
|
executable::
|
|
|
|
sudo chmod 0755 /usr/local/bin/rattail-backup
|
|
|
|
Run it like so; note that ``--help`` is not interpreted by the script
|
|
but rather is passed on to the underlying command::
|
|
|
|
sudo -H rattail-backup --help
|
|
|
|
If you were to run the "same" command but without the wrapper script,
|
|
it would look like::
|
|
|
|
cd /srv/envs/backup
|
|
sudo -H bin/rattail -c app/rattail.conf backup --help
|
|
|
|
|
|
Script: ``backup-everything``
|
|
-----------------------------
|
|
|
|
The purpose of this script is to give the admin user a single "entry
|
|
point" for running backups on "all" machines regardless of their
|
|
configuration details.
|
|
|
|
Really the ``rattail-backup`` script could be used for this too, but
|
|
``backup-everything`` just has a more authoritative sound to it.
|
|
|
|
Again instead of listing the file contents we will direct you to the
|
|
"official" copy which can be deployed via Fabric:
|
|
|
|
`<https://forgejo.wuttaproject.org/rattail/rattail-fabric2/src/branch/master/rattail_fabric2/deploy/backup/backup-everything.mako>`_
|
|
|
|
Again you will need to (globally) replace the text ``${envname}`` with
|
|
``backup`` but you also should comment-out the line which tries to
|
|
invoke ``app/upgrade.sh`` (unless you have that and want to use it).
|
|
|
|
Place this file at ``/usr/local/bin/backup-everything`` and make it
|
|
executable::
|
|
|
|
sudo chmod 0755 /usr/local/bin/backup-everything
|
|
|
|
This script also wraps the underlying ``rattail backup`` command.
|
|
Note that it does *not* wrap the ``rattail-backup`` script (from
|
|
previous section).
|
|
|
|
Really unless you modify this script, it will *just* run the ``rattail
|
|
backup`` command, again with the appropriate config file, but without
|
|
any other arguments, so any extra ones you specify will *not* be
|
|
passed on to the underlying command.
|
|
|
|
Run it like so; note that it only takes one optional argument,
|
|
``--verbose``::
|
|
|
|
sudo -H backup-everything [--verbose]
|
|
|
|
If you were to run the "same" command but without the wrapper script,
|
|
it would look like::
|
|
|
|
cd /srv/envs/backup
|
|
sudo -H bin/rattail -c app/rattail.conf backup
|