..
    Copyright 2013 Rackspace Hosting

    Licensed under the Apache License, Version 2.0 (the "License"); you may
    not use this file except in compliance with the License. You may obtain
    a copy of the License at

        http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
    License for the specific language governing permissions and limitations
    under the License.

.. _getting-started:

========================
Getting Started
========================

Designate is comprised of three designate components :ref:`designate-api`, :ref:`designate-central` and :ref:`designate-sink`, supported by a few standard open source components. For more information see :doc:`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 :doc:`architecture` and :doc:`production-architecture`.

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

- `Fedora 19 Notes`_

.. _Development Environment:

Development Environment
+++++++++++++++++++++++

Installing Designate
====================

.. index::
   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
===================

.. index::
   double: configure; designate

::

  $ editor designate.conf

Copy or mirror the configuration from this sample file here:

.. literalinclude:: examples/basic-config-sample.conf
   :language: ini

Initialize & Start the Central Service
======================================

.. index::
   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
==================================

.. index::
   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 :doc:`rest`

.. _Designate REST Documentation:

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

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/

Fedora 19 Notes
===============

Most of the above instructions under `Installing Designate`_ should work.  There are a few differences when working with Fedora 19:

The basic Fedora packages are **python-pip python-virtualenv python-pbr rabbitmq-server**

::

   $ yum install python-pip python-virtualenv python-pbr rabbitmq-server

Use **/var/lib/designate** as the root path for databases and other variable state files, not /root/designate

::

   $ mkdir -p /var/lib/designate

The PowerDNS Fedora packages are **pdns pdns-backend-sqlite**

::

   $ yum install pdns pdns-backend-sqlite

Fedora 19 does not use /etc/powerdns/pdns.d.  Instead, edit **/etc/pdns/pdns.conf** - change the launch option, and add a gsqlite3-database option

::

   ...
   setuid=pdns
   setgid=pdns
   launch=gsqlite3
   gsqlite3-database=/var/lib/designate/pdns.sqlite
   ...

Fedora uses **systemctl**, not service

::

   $ systemctl [start|restart|stop|status] pdns.service
   $ systemctl [start|restart|stop|status] rabbitmq-server.service

The rabbitmq service must be running before doing

::

   $ rabbitmqctl change_password guest guest

RabbitMQ may fail to start due to SELinux.  Use *journalctl -xn|cat* to find the error.  You will likely have to do something like this until it is added to the SELinux base policy

::

   $ yum install /usr/bin/checkpolicy
   $ grep beam /var/log/audit/audit.log|audit2allow -M mypol
   $ semodule -i mypol.pp
   $ systemctl start rabbitmq-server.service

The rabbitmq log files are in **/var/log/rabbitmq**
