Consumer's Manual
=================

This manual should be sufficient for people merely consuming the APT
repositories, plus maybe some repository maintenance like migration --
i.e., everything but actually developing Debian packages.

For example: system administrators, quality assurance personnel.

Installation
------------

No custom package installations are required; just access the provided
service via some web browser, and standard Debian tools should be
enough.

However, it's still *recommended* to install the ``mini-buildd-utils`` package:

.. code:: bash
	 :class: root-code

	 apt install mini-buildd-utils

This toolbox will (among other things) allow you to access the *API*
and *events system* from the command line. Also, this manual might
just silently assume it's installed.


Setup
-----

APT Bootstrap
~~~~~~~~~~~~~

To use mini-buildd's repository (or any, really), its APT key must be
known/trusted by your system. ``mini-buildd`` conveniently provides
that key in a Debian package -- but in that very not-yet-trusted repository.

To "TOFU bootstrap" your system's APT, you may just run:

.. code:: bash
	 :class: root-code

	 mini-buildd-apt-bootstrap <URL>

That tool finds the current codename and the archive ID automatically,
and also has some bells and whistles built-in to work for older
releases.

.. tip:: How do I verify mini-buildd's APT key?

	You may compare the key's fingerprint (``apt-key finger``)
	with the one on mini-buildd's `home`_. There might also be other
	means set up by the local administrator to cross-verify the key.

Alternative: Download archive-keyring.deb and install via dpkg
..............................................................

Find and download the correct deb via :mbdpage:`repositories-dir`, then install it via ``dpkg -i``.

For ``jessie`` or older, you will need an extra ``apt-key add /etc/apt/trusted.gpg.d/mini-buildd-foo.asc`` call.

Will yield the same end result (i.e., keyring package installed) as the recommended method.

Alternative: Doing 'insecure' apt update and install
....................................................

Let's say you have your sources list configured manually, but
mini-buildd's key is not yet trusted.

For anything ``stretch`` or newer, you can run:

.. code:: bash
	 :class: root-code

	 apt --allow-insecure-repositories update
	 apt --allow-unauthenticated install <ARCHIVE>-archive-keyring

For ``jessie`` or older, this should still work just omitting any ``--allow*`` options apt may not yet know about.

Will yield the same end result (i.e., keyring package installed) as the recommended method.

.. error:: squeeze or older only: apt secure problems after initial (unauthorized) install of the archive-key package!

	 - aptitude always shows <NULL> archive

	 You can verify this problem via::

		 # aptitude -v show YOURID-archive-keyring | grep ^Archive
		 Archive: <NULL>, now

	 - BADSIG when verifying the archive keyring package's signature

	 Both might be variants of :debbug:`657561` (known to occur
	 for <= squeeze). For both, check if this::

		 # rm -rf /var/lib/apt/lists/*
		 # apt-get update

	 fixes it.


Alternative: Manually install the APT key file
..............................................

Download the key via :apicall:`pub_key`, then install it under
``/etc/apt/trusted.gpg.d/foo.asc``.

For ``jessie`` or older, you will need an extra ``apt-key add foo.asc`` call.

Different end result than the recommended method -- you now have an
extra local configuration file to maintain.

Sources Lists
~~~~~~~~~~~~~

You can retrieve any apt line(s) via the :apicall:`sources_list`.

Here is an example on how to do it on the shell (requires :debpkg:`mini-buildd-utils`):

.. code:: bash

	 mini-buildd-api sources_list <ENDPOINT> --codenames sid --suites stable

Just add lines to ``/etc/apt/sources.list`` or individual files in ``/etc/apt/sources.list.d/``.

Symlinks to keyring package
...........................

The resp. archive's *keyring package* also provides a library of
predefined sources list files you can just symlink to:

.. code:: bash
	 :class: root-code

	 cd /etc/apt/sources.list.d
	 ln -s /usr/share/<ARCHIVE>-archive-keyring/sources.list.d/<CODENAME>/foo.list .
	 apt-get update


User
~~~~

To be able **use advanced functionality** (for example, create
package subscriptions, access restricted API calls, or upload
your GnuPG public key, migrate packages), create a *user account*:

#. `Register a user account </accounts/register/>`_.
#. `Setup your profile </accounts/profile/>`_ (package subscriptions, GnuPG key upload).


Advanced Topics
---------------

.. tip:: How to can I upgrade after Debian main release version fix?

	Since Debian ``wheezy``, Debian uses only one number as main release
	version. I.e., squeeze main version was ``6.0``, while wheezy's main
	version is just ``7``.

	(Assuming repo ``test`` for the following, replace as needed.)

	So, the new default version appendix in mini-buildd is now just
	something like ``~test7`` (wheezy) or ``~test11`` (bullseye),
	analogous to what Debian does with ``bpo``.

	On a production system, the admin may/should decide at some point
	(i.e., when a new codename is introduced) to switch to the new
	scheme.

	Let's say the admin decided to do the change with the introduction of
	buster. Then ``~test90`` (stretch, oldstyle) would be bigger than
	``~test10`` (buster, new style). To be able to upgrade the packages,
	use an apt preference like this:

	.. code-block::
		:caption: /etc/apt/preferences.d/mbd-buster-upgrade.pref

			Package: *
			Pin: release a=buster-test-*
			Pin-Priority: 1001


API and Events
~~~~~~~~~~~~~~

Documentation of all ``API`` calls is in-code only; on mini-buildd's
web interface, you find a summary on :mbdpage:`api` (there is also
a convenience menu in this manual in the left sidebar).

On the web interface, API calls are embedded where context deems wise
-- just click the little rascals. Running events are displayed on
`home`_, all events on :mbdpage:`events`.

Access via Shell
................

Access from the shell via :mbdcommand:`mini-buildd-api` or
:mbdcommand:`mini-buildd-events`, respectively.

To get started, try:

.. code:: bash

	 mini-buildd-api --help
	 mini-buildd-events --help

.. error:: I can't get credentials to work from the shell!

	API credentials are handled via ``python3-keyring``, which *should
	just work* -- i.e., choose the right backend for you automatically.

	If not, you might need to configure the desired backend manually.

	.. seealso:: `python keyring bug <https://github.com/jaraco/keyring/issues/391>`_


Access via Python
.................

Python documentation is `here
<code/mini_buildd/mini_buildd.client.html>`_ (or maybe that is still
just where it *should be eventually* ;). At least you get the
definitions, and you still have the source...)

To get started, look at:

.. literalinclude:: ../examples/mini-buildd-utils/python-client
	 :caption: /usr/share/doc/mini-buildd-utils/examples/python-client

``python`` code might be more suitable for elaborated scripts; for
simple tasks, rather use :mbdcommand:`mini-buildd-api`.


Default Layout
~~~~~~~~~~~~~~

==================== ========= =================== ========================== ========================= ============================ =======================
  The Default Layout's Suites and Semantics Overview
------------------------------------------------------------------------------------------------------------------------------------------------------------
Suite                Flags     Version restriction Example(``test/bullseye``) Repository                Semantic                     Consumer
==================== ========= =================== ========================== ========================= ============================ =======================
*experimental*       U E 6R    ``~<R><C>+0``       ``~test11+0``              No auto                   *Use at will*                Developer.
snapshot             U E 12R   ``~<R><C>+0``       ``~test11+0``              No auto, but upgrades     *Continuous integration*     Developer, beta tester.
``unstable``         U M 9R    ``~<R><C>+[1-9]``   ``~test11+3``              No auto, but upgrades     *Proposed for live*          Developer, beta tester.
``testing``          M 3R      ``~<R><C>+[1-9]``   ``~test11+2``              No auto, but upgrades     *QA testing*                 Quality Assurance.
``hotfix``           U M 4R    ``~<R><C>+[1-9]``   ``~test11+2+hotfix1``      No auto, but upgrades     *Hotfix proposed for live*   Quality Assurance.
``stable``           6R        ``~<R><C>+[1-9]``   ``~test11+1``              No auto, but upgrades     *Live*                       End customer.
==================== ========= =================== ========================== ========================= ============================ =======================

``U``: Uploadable ``M``: Migrates ``E``: Experimental ``NR``: keeps N Rollback versions ``<R>``: Repository Identity ``<C>``: Codename version.

.. tip:: What's the ``hotfix`` suite good for?

	The ``hotfix`` suite fills the kludge in a situation when a new
	version is in ``unstable/testing`` (but no yet ready for
	``stable``), but you need but to do important bug fixes to what is
	in ``stable`` immediately (it does migrate to ``stable`` directly).

Release2PinPrio Map
...................

============  ====================   ============
NotAutomatic  ButAutomaticUpgrades   APT Pin Prio
============  ====================   ============
no            no                     500
yes           no                     1
no            yes                    n/a
yes           yes                    100
============  ====================   ============

.. note:: Feb 2022: Copied from local docs. Needs verification, maybe update.

Aptitude Setup
~~~~~~~~~~~~~~

In case you use *aptitude*: By default, it does not show distribution
or origin of packages -- but this might be very helpful.

To show the **distribution** of packages, just add ``%t`` to the
package display format (:debbug:`484011`). For example, I do prefer
this setting for the *Package-Display-Format*::

	aptitude::UI::Package-Display-Format "%c%a%M%S %p %t %i %Z %v# %V#";

The origin cannot be shown in the package display format
(:debbug:`248561`). However, you may change the grouping to categorize
with "origin". For example, I do prefer this setting for the
*Default-Grouping*::

	aptitude::UI::Default-Grouping "task,status,pattern(~S~i~O, ?true ||),pattern(~S~i~A, ?true ||),section(subdirs,passthrough),section(topdir)";

This will group installed packages into an *Origin->Archive*
hierarchy.

Additionally to aptitude's default "Obsolete and locally installed"
top level category (which only shows packages not in any apt archive),
this grouping also more conveniently shows installed package
_versions_ which are not currently in any repository (check "Installed
Packages/now").

Multiple versions of packages in one distribution
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This is not really a problem, but a uncommon situation that may lead
to confusion.

Generally, reprepro does allow exactly only one version of a package
in a distribution; the only exception is when installed in *different
components* (f.e., ``main`` vs. ``non-free``).

This usually happens when the 'Section' changes in the corresponding
'debian/control' file of the source package, or if packages were
installed manually using "-C" with reprepro.

Check with the "ls" command if this is the case, i.e., s.th. like:

.. code:: bash

	 mini-buildd-api ls ENDPOINT my-package

you may see multiple entries for one distribution with different components.

mini-buildd handles this gracefully; the :apicall:`remove`, the
:apicall:`migrate` and the :apicall:`port` all include an optional
'version' parameter to be able to select a specific version.

In the automated rollback handling, all versions of a source package
are shifted.
