.. _set-up-incus:

=========================
Set up Incus for Debusine
=========================

We recommend using `Incus <https://linuxcontainers.org/incus/>`_ for
Debusine development, to make it easy to install our dependencies and run
tests without disturbing your host system.

Install Incus
=============

Incus is a recent fork from LXD.
You can find the package in Debian 13 (Trixie) and newer.
If it is not available on your host system, you can instead `use the
upstream packages <https://github.com/zabbly/incus>`_.

You can install incus with:

.. code-block:: console

    $ sudo apt install incus

Initialize Incus
================

Incus needs some basic configuration. See the `upstream docs
<https://linuxcontainers.org/incus/docs/main/howto/initialize/>`_ for
more details.

First give yourself administrative powers in Incus:

.. code-block:: console

    $ sudo adduser $(whoami) incus-admin
    $ newgrp incus-admin

Then initialize Incus:

.. code-block:: console

    $ sudo incus admin init
    Would you like to use clustering? (yes/no) [default=no]:
    Do you want to configure a new storage pool? (yes/no) [default=yes]:
    Name of the new storage pool [default=default]:
    Would you like to create a new local network bridge? (yes/no) [default=yes]:
    What should the new bridge be called? [default=incusbr0]: debusinebr0
    What IPv4 address should be used? (CIDR subnet notation, “auto” or “none”) [default=auto]:
    What IPv6 address should be used? (CIDR subnet notation, “auto” or “none”) [default=auto]:

    We detected that you are running inside an unprivileged container.
    This means that unless you manually configured your host otherwise,
    you will not have enough uids and gids to allocate to your containers.

    Your container's own allocation can be reused to avoid the problem.
    Doing so makes your nested containers slightly less safe as they could
    in theory attack their parent container and gain more privileges than
    they otherwise would.

    Would you like to have your containers share their parent's allocation? (yes/no) [default=yes]: no
    Would you like the server to be available over the network? (yes/no) [default=no]:
    Would you like stale cached images to be updated automatically? (yes/no) [default=yes]:
    Would you like a YAML "init" preseed to be printed? (yes/no) [default=no]:

Verify Virtualization
=====================

Test that you can launch containers and VMs:

.. code-block:: console

    $ incus launch images:debian/trixie/amd64 test-container
    $ incus exec test-container ping 8.8.8.8
    $ incus delete --force test-container
    $ incus launch --vm images:debian/trixie/amd64 test-vm
    $ # wait for the VM to come up ...
    $ incus exec test-vm ping 8.8.8.8
    $ incus delete --force test-vm

If an instance fails to launch, you can see the errors with:

.. code-block:: console

    $ incus info test-container --show-log
