# Development Environment on Ubuntu

Designate is comprised of four main components Designate API, Designate Central, designate-mdns, and designate-pool-manager, supported by a few standard open source components. For more information see Architecture.

There are many different options for customizing Designate, and two of these options have a major impact on the installation process:

- The storage backend used (SQLite or MySQL)

- The DNS backend used (PowerDNS or BIND9)

This guide will walk you through setting up a typical development environment for Designate, using BIND9 as the DNS backend and MySQL as the storage backend. For a more complete discussion on installation & configuration options, please see Architecture.

For this guide you will need access to an Ubuntu Server (16.04).

## Development Environment

### Installing Designate

1. Install system package dependencies (Ubuntu)

    $ sudo apt update
    $ sudo apt install python-pip python-virtualenv libssl-dev libffi-dev git
    $ sudo apt build-dep python-lxml

2. Clone the Designate repo

    $ mkdir openstack
    $ cd openstack
    $ git clone https://opendev.org/openstack/designate.git
    $ cd designate

3. Setup a virtualenv

Note

This step is necessary to allow the installation of an up-to-date pip, independent of the version packaged for Ubuntu. it is also useful in isolating the remainder of Designate’s dependencies from the rest of the system.

    $ virtualenv .venv
    $ . .venv/bin/activate

4. Install an up-to-date pip

    $ pip install -U pip

5. Install Designate and its dependencies

    $ pip install -e .

6. Change directories to the etc/designate folder.

Note

Everything from here on out should take place in or below your etc/designate folder

    $ cd etc/designate

7. Create Designate’s config files by copying the sample config files

    $ cp -a rootwrap.conf.sample rootwrap.conf

8. Make the directory for Designate’s state files

    $ mkdir -p ../../state

### Configuring Designate

Refer to Designate Configuration Guide for a sample configuration options.

### Installing RabbitMQ

Install the RabbitMQ package

    $ sudo apt install rabbitmq-server

Create a user:

    $ sudo rabbitmqctl add_user designate designate

Give the user access to the / vhost:

    $ sudo rabbitmqctl set_permissions -p "/" designate ".*" ".*" ".*"

### Installing MySQL

Install the MySQL server package

    $ sudo apt install mysql-server

If you do not have MySQL previously installed, you will be prompted to change the root password. By default, the MySQL root password for Designate is “password”. You can:

- Change the root password to “password”

- If you want your own password, edit the designate.conf file and change any instance of “mysql+pymysql://root:password@127.0.0.1/designate?charset=utf8” to “mysql+pymysql://root:YOUR_PASSWORD@127.0.0.1/designate?charset=utf8”

You can change your MySQL password anytime with the following command:

    $ mysqladmin -u root -p password NEW_PASSWORD
    Enter password <enter your old password>

Create the Designate tables

    $ mysql -u root -p
    Enter password: <enter your password here>

    mysql> CREATE DATABASE `designate` CHARACTER SET utf8 COLLATE utf8_general_ci;
    mysql> exit;

Install additional packages

    $ sudo apt install libmysqlclient-dev
    $ pip install pymysql

### Installing BIND9

Install the DNS server, BIND9

    $ sudo apt install bind9

Update the BIND9 Configuration

    $ sudo editor /etc/bind/named.conf.options

Change the corresponding lines in the config file:

    options {
      directory "/var/cache/bind";
      dnssec-validation auto;
      auth-nxdomain no; # conform to RFC1035
      listen-on-v6 { any; };
      allow-new-zones yes;
      request-ixfr no;
      recursion no;
    };

Disable AppArmor for BIND9

    $ sudo touch /etc/apparmor.d/disable/usr.sbin.named
    $ sudo systemctl reload apparmor

Restart BIND9:

    $ sudo systemctl restart bind9

### Create and Import pools.yaml File

Create the pools.yaml file

    $ editor pools.yaml

Copy or mirror the configuration from this sample file here:

    - name: default
      # The name is immutable. There will be no option to change the name after
      # creation and the only way will to change it will be to delete it
      # (and all zones associated with it) and recreate it.
      description: Default BIND9 Pool

      attributes: {}

      # List out the NS records for zones hosted within this pool
      ns_records:
        - hostname: ns1-1.example.org.
          priority: 1

      # List out the nameservers for this pool. These are the actual BIND servers.
      # We use these to verify changes have propagated to all nameservers.
      nameservers:
        - host: 127.0.0.1
          port: 53

      # List out the targets for this pool. For BIND, most often, there will be one
      # entry for each BIND server.
      targets:
        - type: bind9
          description: BIND9 Server 1

          # List out the designate-mdns servers from which BIND servers should
          # request zone transfers (AXFRs) from.
          masters:
            - host: 127.0.0.1
              port: 5354

          # BIND Configuration options
          options:
            host: 127.0.0.1
            port: 53
            rndc_host: 127.0.0.1
            rndc_port: 953
            rndc_key_file: /etc/bind/rndc.key

      # Optional list of additional IP/Port's for which designate-mdns will send
      # DNS NOTIFY packets to
      # also_notifies:
      #  - host: 192.0.2.4
      #    port: 53

### Initialize the Database

Sync the Designate database.

    $ designate-manage database sync

### Start the Central Service

Start the central service.

    $ designate-central

You’ll now be seeing the log from the central service.

### Initialize Pools Information

Import the pools.yaml file into Designate. It is important that `designate-central` is started before invoking this command

    $ designate-manage pool update --file pools.yaml

### Start the other Services

Open up some new ssh windows and log in to your server (or open some new screen/tmux sessions).

    $ cd openstack/designate
    $ . .venv/bin/activate

Start the other services

    $ designate-api
    $ designate-mdns
    $ designate-worker
    $ designate-producer

You’ll now be seeing the logs from the other services.

### Exercising the API

Note

If you have a firewall enabled, make sure to open port 53, as well as Designate’s default port (9001).

Using a web browser, curl statement, or a REST client, calls can be made to the Designate API. You can find the various API calls on the api-ref document.

For example:

    $ curl 127.0.0.1:9001/v2/zones -H 'Content-Type: application/json' --data '
      {
        "name": "example.com.",
        "email": "example@example.com"
      }'

    {"status": "PENDING",.....
    $ curl 127.0.0.1:9001/v2/zones
    {"zones": [{"status": "ACTIVE",.....

The `ACTIVE` status shows that the zone propagated. So you should be able to perform a DNS query and see it:

    $ dig @127.0.0.1 example.com SOA +short
    ns1-1.example.org. example.example.com. 1487884120 3531 600 86400 3600

You can find the IP Address of your server by running

    ip addr show eth0 | grep "inet\b" | awk '{print $2}' | cut -d/ -f1

If you have Keystone set up, you can use it by configuring the `[keystone_authtoken]` section and changing the `auth_strategy = keystone` in the `service:api` section. This will make it easier to use clients like the `openstack` CLI that expect Keystone.

this page last updated: 2026-08-19 02:25:39

Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.

found an error? report a bug