.. _create-package-repository:

===============================
Create a new package repository
===============================

Debusine can host package repositories, allowing you to upload to them using
`dput-ng <https://dput.readthedocs.io/en/latest/>`__ and allowing your users
to download from them using APT and other standard Debian tools.

Initial setup
-------------

You must have at least ``debusine-client`` version 0.14.1 for the ``debusine
archive suite create`` command.

Follow :ref:`set-up-debusine-client` to configure the Debusine client for
the appropriate Debusine server.

Create a workspace
------------------

Repositories live within :ref:`workspaces <explanation-workspaces>`, and may
contain multiple :collection:`suites <debian:suite>`.  Each suite typically
corresponds to a different base version of the operating system: so if you
were publishing similar packages for a given topic for both Debian 12
(bookworm) and Debian 13 (trixie), you might have ``bookworm-mytopic`` and
``trixie-mytopic`` suites.

Start by creating a suitable workspace.  If you have direct access to the
Debusine server you're using, then you can create one using
:ref:`debusine-admin workspace define <debusine-admin-cli-workspace>`.
Otherwise, you will normally need to use a
:workflow:`create_child_workspace <create_child_workspace>`
workflow as configured by the owner of a workspace you have access to: for
example, Debian developers may start the ``create-experiment`` workflow on
debusine.debian.net (see https://wiki.debian.org/DebusineDebianNet for more
details).

Create a suite
--------------

For each suite you intend to publish, create it in your workspace, as
follows:

.. code-block:: console

    $ debusine --server SERVER archive suite create --workspace WORKSPACE \
               --architecture all --architecture amd64 \
               --base-workflow-template TEMPLATE SUITE

The base workflow template is the name of an existing
:workflow:`debian_pipeline` template describing how to build and test
packages for a similar base suite, normally including things like
environment and backend configuration.  This command will create a copy of
that template called ``publish-to-{suite}`` (substituting the name of the
new suite), adjusting its parameters to publish packages to the new suite.

If you omit the ``--base-workflow-template`` option, then no workflow
template will be created; you can create one yourself using :ref:`debusine
workflow-template create <tutorial-set-up-workflow-templates>`.

Packages in the new suite will only be built and tested on the architectures
you specify.

If you need to edit any of this configuration later, you can do so using
``debusine collection manage`` and ``debusine workflow-template edit``.

For example, if you have created a ``developers-myuser_experiment``
workspace on debusine.debian.net, you can create a ``sid-experiment`` suite
in it as follows:

.. code-block:: console

    $ debusine --server debian archive suite create \
               --workspace developers-myuser_experiment \
               --architecture all --architecture amd64 \
               --base-workflow-template upload-to-unstable \
               sid-experiment

Configure dput-ng
-----------------

You may already have a suitable :ref:`profile <dput-ng-profiles>` for
uploading to the Debusine server in question.  If you do, you can override
the workspace and workflow using the ``-O debusine_workspace=WORKSPACE`` and
``-O debusine_workflow=WORKFLOW`` options to ``dput`` (in the example above,
this would be ``-O debusine_workspace=developers_myuser-experiment -O
debusine_workflow=sid-experiment``).

This can get rather verbose, so you may prefer to create your own profile
and store it under ``~/.dput.d/profiles/`` (e.g.
``~/.dput.d/profiles/myuser_experiment.json``).  Start with the minimal
profile in :ref:`dput-ng-profiles` and set ``fqdn``, ``debusine_scope``,
``debusine_workspace``, and either ``debusine_workflow`` or
``debusine_workflows_by_distribution`` to match your repository.  For the
example above:

.. code-block:: json

    {
        "allow_unsigned_uploads": true,
        "debusine_scope": "debian",
        "debusine_workflows_by_distribution": {
            "sid": "sid-experiment"
        },
        "debusine_workflow_data": {
            "source_artifact": "@UPLOAD@"
        },
        "debusine_workspace": "developers-myuser_experiment",
        "fqdn": "debusine.debian.net",
        "incoming": "/",
        "meta": "debusine",
        "method": "debusine"
    }

Access the repository
---------------------

APT configuration for each suite will look something like this::

    Types: deb deb-src
    URIs: https://deb.debusine.debian.net/debian/developers-myuser_experiment
    Suites: sid-experiment
    Components: main

See :ref:`package-repositories` for more details and examples.