amprolla
========

amprolla is a tool that will merge a number of different APT-based
repositories into one, while giving control over (not) including given
packages, architectures, or any specific package metadata. Upon
completing the merge, amprolla will generate and optionally create GnuPG
signatures of the according `Release` files.

amprolla is able to run on any system supporting Python3, rsync, and
GnuPG.

To configure amprolla, a default configuration file is provided in
`lib/config.def.py`. Copy the file to `lib/config.py` and edit it to
what is needed. The configuration file contains all the information
needed to properly merge the required repositories. The default
configuration also works, as long as a valid GPG fingerprint is provided
to sign the Release files.

The `*dir` variables in the configuration file are the directories where
the files that are being merged are kept, and the merges itself are
done. They can be either absolute or relative paths to the root amprolla
directory. The preferred way is to actually have absolute paths.

`banpkgs` is a set of package names that amprolla will refuse to merge
if they are found either in the dependencies of a package or if they are
the package itself.

`repo_order` is a list that holds what is ordered in the priority the
packages are preferred. The preference is ordered first to last. The
dict `repos` holds their required information.

To avoid unnecessary duplication, further documentation is available in
amprolla's source code.


Usage
-----

After setup, it is needed to perform an initial full download and full
merge. First run `amprolla_init.py`, which is going to download the
necessary directory structures (as defined through the config file) we
will merge afterwards. When the download is done, it is time to perform
the full initial merge of these repositories. This will provide us with
a complete merged repository and we will then be able to easily perform
incremental updates.

After the initial merge has been performed, it is advisable to run a
script called `populate_aliases.sh` found in the `contrib` directory.
Make sure it's properly edited and configured.

To merge `Contents` files, run `amprolla_merge_contents.py`. This module
does not do incremental updates and should not be ran often due to its
heavy IO/RAM requirements.

Incremental updates are performed through `amprolla_update.py`, however,
for more stable performance and uptime, the incremental updating is
being orchestrated by a shell script called `orchestrate.sh`. This shell
script holds the logic to have near-atomic switching of repositories to
minimize repo downtime during performed merges. Not doing this could
result in users downloading corrupted repository files if they are
requested during an ongoing merge.

In a terminal session, simply execute the `orchestrate.sh` script and it
will start looping and doing incremental updates in a specific
timeframe. If prefered, this script can be used with cron as well.

To actually serve the merged directory over HTTP(S), a basic nginx
configuration is provided as `contrib/nginx.conf`, and a lighttpd conf
is provided in `contrib/lighttpd.conf`.