This guide shows how to install and configure the bpkg-util-publish script to
update and publish an archive-based bpkg repository that is stored in a git
repository. Normally the bpkg repository is signed and synchronized to a
remote host. Both of these operations usually requires authentication so here
we assume that you have arranged for the password-less repository signing and
ssh authentication (for example, using unlocked private keys, ssh-agent and
openssl-agent, etc).

See also the documentation at the beginning of bpkg-util-publish for details
on the script's operation.


1. Create 'bpub' User

This user will be used to run the bpkg-util-publish script. We will also use
its home directory to build and install bpkg-util package, clone the git
repository, create the logs directory, etc.

We create this user with a disabled password so only root will be able to
operate as bpub. Because of this restriction we will allow bpub to run sudo
without a password:

# adduser --disabled-password bpub
# echo "bpub ALL=(ALL) NOPASSWD:ALL" >/etc/sudoers.d/bpub
# chmod 0440 /etc/sudoers.d/bpub

In the rest of this guide commands that start with the $ shell prompt are
expected to be executed as the bpub user and in its home directory (those
that start with # as above are run as root). To change to the bpub user
from root, do:

# su -l bpub


2. Install Prerequisites

a) Install a C++ compiler and git using your distribution's packages.

b) Unless you already have the build2 toolchain, install it by following
   instructions on https://build2.org/install.xhtml.


3. Build and Install bpkg-util.

$ mkdir bpkg-util
$ cd bpkg-util

$ bpkg create                          \
    cc                                 \
    config.bin.rpath=$HOME/install/lib \
    config.install.root=$HOME/install

$ bpkg build bpkg-util,bpkg@https://pkg.cppget.org/1/alpha
$ bpkg install -a

$ cd .. # Back to bpub home.


4. Configure the repository update and synchronization.

Pre-clone the git repository containing the bpkg repository and create the log
directory:

$ git clone https://git.example.org/foo.git
$ mkdir foo.log

Note that the bpkg repository contents are expected to be in the foo/1/
subdirectory (see bpkg-util-publish for details).

Perform the initial publication to test the setup and make the subsequent
synchronizations incremental. Here you may need to pass additionall
bpkg-rep-create(1) and rsync(1) options to the bpkg-util-publish script.

$ install/bin/bpkg-util-publish -d example.org:/var/bpkg/1/foo foo ...

Setup publishing as a cron job (every 5 minutes in this example):

$ crontab -l
MAILTO=publish@example.org
PATH=/usr/local/bin:/bin:/usr/bin
0/5 * * * * $HOME/install/bin/bpkg-util-publish -d example.org:/var/bpkg/1/foo --log-dir $HOME/foo.log --lock-timeout 600 $HOME/foo ...