Installation
============

ZoneControl is a `Python <https://www.python.org/>`__ `Django
<https://www.djangoproject.com/>`__ application and is typically installed
through our official Ansible packages.

PowerDNS will provide an `Ansible <https://ansible.com>`_ role to install
ZoneControl and set up an initial user. This role comes with a ``README``
file that describes all variables for the role.


Manual Installation
~~~~~~~~~~~~~~~~~~~

To install ZoneControl without access to professional services or an Ansible
role, configure your package manager with the relevant repository URL and
credentials provided with your valid license/subscription:

.. note::
   All instances of ``zonecontrol-18`` appearing in the examples below refer to
   the 1.8.* version train. Other minor and major versions will have different
   repo names.

RHEL, CentOS, and Derivatives
-----------------------------

Create the repository file ``/etc/yum.repos.d/powerdns-zonecontrol.repo``,
substituting ``<REPO_ID>``, ``<USERNAME>``, and ``<PASSWORD>`` with the values
supplied with your subscription:

::

    [zonecontrol-18]
    name=PowerDNS ZoneControl
    baseurl=https://repo-private.powerdns.com/<REPO_ID>/$basearch/$releasever/zonecontrol-18
    gpgkey=https://repo-private.powerdns.com/792BEDEFA9256188C33742D9F507A8D0C15B9053-pub.asc
    gpgcheck=1
    enabled=1
    includepkgs=zonecontrol*

    username=<USERNAME>
    password=<PASSWORD>

Then, install the ZoneControl package:

::

    $ sudo dnf install zonecontrol

Replace ``dnf`` with ``yum`` in the above example if applicable.

Debian and Ubuntu
-----------------

Import the repository signing key:

::

    $ curl https://repo-private.powerdns.com/792BEDEFA9256188C33742D9F507A8D0C15B9053-pub.asc \
      | sudo tee /etc/apt/trusted.gpg.d/powerdns-zonecontrol.asc > /dev/null

Store your credentials in ``/etc/apt/auth.conf.d/powerdns.conf``:

::

    machine repo-private.powerdns.com login <USERNAME> password <PASSWORD>

Add the repository, replacing ``<DIST>`` with your distribution codename +
distribution name (for example ``noble-ubuntu`` for Ubuntu 24.04 or
``bookworm-debian`` for Debian 12):

::

    $ echo "deb [arch=amd64] https://repo-private.powerdns.com/<REPO_ID>/debian <DIST>-zonecontrol-18 main" \
      | sudo tee /etc/apt/sources.list.d/powerdns-zonecontrol.list

Then, update the package index and install the package:

::

    $ sudo apt-get update
    $ sudo apt-get install zonecontrol


Post-installation
~~~~~~~~~~~~~~~~~

After the initial installation, ZoneControl needs to be configured. See
the `Configuration <#configuration>`__ section on how to configure.

After configuration, the database needs to be populated, run:

::

    $ zonecontrol-manage migrate

Now create a superuser (if required):

::

    $ zonecontrol-manage createsuperuser
