designate/doc/source/getting-started.rst

Getting Started

Designate is comprised of three designate components designate-api, designate-central and designate-sink, supported by a few standard open source components. For more info see architecture.

This guide will walk you through setting up a development environment for Designate, using PowerDNS as the DNS backend, where possible the simplest options have been chosen for you. For a more complete discussion on installation & configuration options, please see architecture and production-architecture.

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

Development Environment

Installing Designate

double: install; designate

1. Install system package dependencies (Ubuntu)

$ apt-get install python-pip python-virtualenv
$ apt-get install rabbitmq-server
$ apt-get build-dep python-lxml

2. Clone the Designate repo off of Stackforge

$ git clone https://github.com/stackforge/designate.git
$ cd designate

3. Setup virtualenv

Note

This is to not interfere with system packages etc.

$ virtualenv --no-site-packages .venv
$ . .venv/bin/activate

4. Install Designate and its dependencies

$ pip install -r requirements.txt -r test-requirements.txt
$ python setup.py develop

Note

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

5. Copy sample config files to edit

$ cd etc/designate
$ ls *.sample | while read f; do cp $f $(echo $f | sed "s/.sample$//g"); done

6. Install the DNS server, PowerDNS

$ DEBIAN_FRONTEND=noninteractive apt-get install pdns-server pdns-backend-sqlite3
#Update path to SQLite database to /root/designate/pdns.sqlite or wherever your top level designate directory resides
$ editor /etc/powerdns/pdns.d/pdns.local.gsqlite3
#Change the corresponding line in the config file to mirror:
gsqlite3-database=/root/designate/pdns.sqlite
#Restart PowerDNS:
$ service pdns restart

7. If you intend to run Designate as a non-root user, then sudo permissions need to be granted

$ echo "designate ALL=(ALL) NOPASSWD:ALL" | sudo tee -a /etc/sudoers.d/90-designate
$ sudo chmod 0440 /etc/sudoers.d/90-designate

8. Make the directory for Designate’s log files

$ mkdir /var/log/designate

Configure Designate

double: configure; designate

$ editor designate.conf

Copy or mirror the configuration from this sample file here:

examples/basic-config-sample.conf

Initialize & Start the Central Service

double: install; central

#Initialize and sync the Designate database:
$ designate-manage database-init
$ designate-manage database-sync
#Initialize and sync the PowerDNS database:
$ designate-manage powerdns database-init
$ designate-manage powerdns database-sync
#Restart PowerDNS
$ service pdns restart
#Start the central service:
$ designate-central

Note

If you get an error of the form: ERROR [designate.openstack.common.rpc.common] AMQP server on localhost:5672 is unreachable: Socket closed

Run the following command:

$ rabbitmqctl change_password guest guest
#Then try starting the service again
$ designate-central

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

Initialize & Start the API Service

double: install; api

Open up a new ssh window and log in to your server (or however you’re communicating with your server).

$ cd root/designate
#Make sure your virtualenv is sourced
$ . .venv/bin/activate
$ cd etc/designate
#Start the API Service
$ designate-api
#You may have to run root/designate/bin/designate-api

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

Exercising the API

Using a web browser, curl statement, or a REST client calls can be made to the Designate API using the following format where “command” is any of the commands listed in the rest

http://IP.Address:9001/v1/command

You can find the IP Address of your server by running

wget http://ipecho.net/plain -O - -q ; echo

If you’d like to see an instance in action, go here: http://166.78.183.212:9001/

A couple of notes on the API:

• Before Domains are created, you must create a server.
• On GET requests for domains, servers, records, etc be sure not to append a ‘/’ to the end of the request. For example …:9001/v1/servers/