Quickstart

Note

It’s recommended to read this Quickstart on the mini-buildd instance in question itself, else some of the links here will not work as-is.

As a convention, we write code you should run as root like:

# apt-get install FOO

and code you should run as user like:

? mini-buildd-tool HOST status

In code snippets, names written all-capital (FOO, HOST) are not meant literal but placeholders for customized values.

Administrator’s Quickstart

Goal: Initial fully working setup with the sandbox repository test.

Install

Prepare to set your admin password when installing, otherwise just stick to the defaults:

# apt-get install mini-buildd

Configure

Note

In case you are both, extraordinary hasty and adventurous, you may just run this:

? /usr/share/doc/mini-buildd/examples/auto-setup

This will basically try to run this whole section non-interactively, with all defaults. If you really just want a quick test-drive, this might be for you. All others should just read on.

Note

Read Setup below: Run the full prepare, check and activate treat (ugh!) from model’s list view to make them green.

Note

Using the wizards is mostly harmless; calling them is idempotent, and they will never touch any existing setup.

  1. Enter the web application’s configuration section and login as superuser admin.

  2. Setup the Daemon (-> Manual).
    1. Edit the one Daemon instance. Get the identity and the gnupg template right, changing these later will call for trouble.
    2. Setup the Daemon instance.

    Daemon green? Go on.

    Note

    Daemon prepare will generate your instance ID (read: GnuPG key); you may need to generate some entropy (install haveged maybe) on the system if this stalls.

    Note

    The Daemon identity will hereafter be referred to as ARCHIVE.

  3. Setup Sources (-> Manual).
    1. Call at least one wizard for each: Archives, Sources, PrioritySources.
    2. Setup all the Sources you want to use.

    All wanted sources green? Go on.

    Note

    Setup of Sources will implicitly pull in architectures and components, and also implicitly sets up the apt keys associated to them. Purists may want to re-check them manually.

  4. Setup Repositories (-> Manual).
    1. Call these wizards, in this order: Layouts:Defaults, Distributions:Defaults, and finally Repositories:Sandbox.
    2. Setup the sandbox repository test.

    test repository green? Go on.

  5. Setup Chroots (-> Manual).
    1. Call the DirChroot:Defaults wizard.
    2. Setup all the Chroots you want to use.

    All wanted chroots green? Done!

    Note

    Preparing chroots may take a while; if you cancel the HTTP request in your browser, preparation will continue anyway.

Note

Don’t add or delete Uploader instances manually; these are bound to users, and come automatically when new users are created. The administrator only changes these instances to grant rights.

Start and test

  1. Enter web application’s home (stay logged-in as admin).

  2. Start the daemon.

  3. Build keyring packages.

    Note

    Just reload the home page to update the packager and builder status.

  4. Migrate the keyring packages up all staged suites (i.e. ->testing->stable).

    Note

    Just show “Last packages”, and click on the keyring’s source package name to get to the package’s overview where you can migrate (also see the User’s Quickstart).

  5. Optionally build the internal test packages.

Epilogue

Going real (beyond the test repository)

When your are confident with the test repository setup, just create a new Repository instance with the actual ID you want to use for production.

Think about how you want to do upload authorization for that production repository; see authorization below.

User’s Quickstart

Goal: Walk through the most important use cases.

“Bootstrap” a system’s APT for a mini-buildd archive

The resp. archive’s keyring package includes both, the APT key as well as a “library” of all sources available (for easy integration via /etc/apt/sources.list.d/).

However, the keyring package also is in the archive, so we need some initial fiddling to get it installed in the first place.

1st, on mini-buildd’s home, jump to the repository overview page (if there are more than one, use the repository you intend to actually use on the system later). Select the stable suite of your base distribution’s (i.e., squeeze, wheezy, jessie,...) APT line, and then:

# echo "APT_LINE" >/etc/apt/sources.list.d/tmp.list
# apt-get update
# apt-get --allow-unauthenticated install ARCHIVE-archive-keyring
# rm /etc/apt/sources.list.d/tmp.list

Note

You may also get the resp. APT line via mini-buildd-tool via the getsourceslist API call in case you have it installed already.

Note

You may compare the key’ 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.

2nd, re-add the stable sources.list back in via “sources.list library”, somewhat like:

# cd /etc/apt/sources.list.d
# ln -s /usr/share/mini-buildd/sources.list.d/CODENAME_ARCHIVE_REPO_stable.list .
# apt-get update

Now you can opt in or out other sources from the archive just by adding or removing symlinks.

Install the command line tool

Access API calls from the command line via mini-buildd-tool:

# apt-get install python-mini-buildd

The remaining Quickstart will just use mini-buildd-tool as example, however the API could also just be accessed via the web interface.

Setup your user account

A user account may be needed to, for example, create package subscriptions, access restricted API calls, or upload your GnuPG public key.

  1. Register a user account.
  2. Setup your profile (package subscriptions, GnuPG key upload).

Setup dput

Install dput, and setup your ~/.dput.cf:

# apt-get install dput
? mini-buildd-tool HOST getdputconf >>~/.dput.cf

Authorize yourself to do package uploads

Upload authorization works via a GnuPG allowed keyring.

Note

For the administrator: See /usr/share/doc/mini-buildd/examples/ssh-uploader-command should you be interested in manually setting up a ssh-based authorization wrapper.

As this depends on the setup of the mini-buildd instance and/or repository your are using, this cannot be answered generically.

You will be able to upload to a repository when

  1. the repository you upload for has authorization disabled completely (like in the sandbox repository test).
  2. your key is included in the per-repository predefined GnuPG keyrings.
  3. your django user account profile has your GnuPG key uploaded, and your account was approved and enabled for the repository.

For the latter, the workflow is roughly:

Workflow: Upload authorization via django user

  1. Create a new user account; either
    1. the user does it itself via the web application’s account manager, or
    2. the administrator creates the user via the web application’s configuration section.
  2. A GPG key is added to the user’s Uploader instance; either
    1. the user uploads his GnuPG key via the user’s profile, or
    2. the administrator inserts the GnuPG key to the user’s Uploader instance via the web application’s configuration section.
  3. The administrator (via web application’s configuration section)
    • verifies and approves the user’s GnuPG key by activating the user’s Uploader instance.
    • allows upload to specific repositories by changing the user’s Uploader instance.

Upload packages to mini-buildd

Just like always, via dput. For the default configuration you get via getdputconf it’s something like:

? dput mini-buildd-ARCHIVE FOO.changes

Control your package build results

  • Per notify (read: Email): A notification mail is sent to
    • the uploader (unless the repository is not configured to do so, or the mail address does not match the allowed list),
    • any subscriber or
    • your Email is configured by the administrator to always be notified for that repository.
  • Per web on mini-buildd’s home: You will always find the packages currently being build displayed here, plus a list of the last N packages build, and of course appropriate links to build logs, changes, etc.

Manage packages

You can search for (binary and source) package names via API:list, using shell-like patterns:

? mini-buildd-tool HOST list '*-archive-keyring'

You can view a source package overview via the API:show call (put in your actual daemon identity):

? mini-buildd-tool HOST show ARCHIVE-archive-keyring

You will find more options to manage packages like API::migrate, API::remove, API::port in this web page overview.

Porting packages (“automatic no-changes ports”)

You can automatically port packages already in the repository (API::port) as well as arbitrary external source packages (API::portext).

For internal ports, checkout the options you have in the source package view; for external ports, go to mini-buildd’s home and check the options for the repositories.

Note

Internal ports may also be triggered automatically on uploads via a ‘magic lines’ in the Debian changelog, see (-> Manual).