Add 'Getting Started' Doc

Add a 'Getting Started' page to the Documentation under
doc/source/gettingstarted.rst. Added a sample configuration file
that's referenced in the file under doc/examples.

Bug: 1201490
Change-Id: I3d307568230f61d105908540ae809d583b347e56

doc/examples/basic-config-sample.conf

@@ -0,0 +1,156 @@
+[DEFAULT]
+########################
+## General Configuration
+########################
+# Show more verbose log output (sets INFO log level output)
+verbose = True
+
+# Show debugging output in logs (sets DEBUG log level output)
+debug = True
+
+# Top-level directory for maintaining designate's state
+state_path = /root/designate
+
+# Log directory #Make sure and create this directory, or set it to some other directory that exists
+logdir = /var/log/designate
+
+# Driver used for issuing notifications
+notification_driver = designate.openstack.common.notifier.rabbit_notifier
+
+# Use "sudo designate-rootwrap /etc/designate/rootwrap.conf" to use the real
+# root filter facility.
+# Change to "sudo" to skip the filtering and just run the comand directly
+root_helper = sudo
+
+# There has to be a better way to set these defaults
+allowed_rpc_exception_modules = designate.exceptions, designate.openstack.common.exception
+default_log_levels = amqplib=WARN, sqlalchemy=WARN, boto=WARN, suds=INFO, keystone=INFO, eventlet.wsgi.server=WARN, stevedore=WARN, keystoneclient.middleware.auth_token=INFO
+
+########################
+## Service Configuration
+########################
+#-----------------------
+# Central Service
+#-----------------------
+[service:central]
+# Driver used for backend communication (e.g. fake, rpc, bind9, powerdns)
+backend_driver = powerdns
+
+# List of blacklist domain name regexes
+#domain_name_blacklist = \.arpa\.$, \.novalocal\.$, \.localhost\.$, \.localdomain\.$, \.local\.$
+
+# Accepted TLD list - http://data.iana.org/TLD/tlds-alpha-by-domain.txt
+accepted_tld_list = COM, NET
+
+# Maximum domain name length
+max_domain_name_len = 255
+
+# Maximum record name length
+max_record_name_len = 255
+
+#-----------------------
+# API Service
+#-----------------------
+[service:api]
+# Address to bind the API server
+api_host = 0.0.0.0
+
+# Port the bind the API server to
+api_port = 9001
+
+# Authentication strategy to use - can be either "noauth" or "keystone"
+auth_strategy = noauth
+
+# Enabled API Version 1 extensions
+enabled_extensions_v1 = diagnostics, sync, import, export, reports
+
+#-----------------------
+# Agent Service
+#-----------------------
+[service:agent]
+# Driver used for backend communication (e.g. bind9, powerdns)
+#backend_driver = bind9
+
+#-----------------------
+# Sink Service
+#-----------------------
+[service:sink]
+# List of notification handlers to enable, configuration of these needs to
+# correspond to a [handler:my_driver] section below or else in the config
+#enabled_notification_handlers = nova_fixed
+
+########################
+## Storage Configuration
+########################
+#-----------------------
+# SQLAlchemy Storage
+#-----------------------
+[storage:sqlalchemy]
+# Database connection string - to configure options for a given implementation
+# like sqlalchemy or other see below
+database_connection = sqlite:///$state_path/designate.sqlite
+connection_debug = 100
+connection_trace = True
+sqlite_synchronous = True
+idle_timeout = 3600
+max_retries = 10
+retry_interval = 10
+
+########################
+## Handler Configuration
+########################
+#-----------------------
+# Nova Fixed Handler
+#-----------------------
+[handler:nova_fixed]
+#domain_id = <random uuid>
+#notification_topics = monitor
+#control_exchange = 'nova'
+#format = '%(octet0)s-%(octet1)s-%(octet2)s-%(octet3)s.%(domain)s'
+
+#------------------------
+# Quantum Floating Handler
+#------------------------
+[handler:quantum_floating]
+#domain_id = <random uuid>
+#notification_topics = monitor
+#control_exchange = 'quantum'
+#format = '%(octet0)s-%(octet1)s-%(octet2)s-%(octet3)s.%(domain)s'
+
+
+########################
+## Backend Configuration
+########################
+#-----------------------
+# Bind9 Backend
+#-----------------------
+[backend:bind9]
+#rndc_host = 127.0.0.1
+#rndc_port = 953
+#rndc_config_file = /etc/rndc.conf
+#rndc_key_file = /etc/rndc.key
+
+#-----------------------
+# Bind9+MySQL Backend
+#-----------------------
+[backend:mysqlbind9]
+#database_connection = mysql://user:password@host/schema
+#rndc_host = 127.0.0.1
+#rndc_port = 953
+#rndc_config_file = /etc/rndc.conf
+#rndc_key_file = /etc/rndc.key
+#write_database = True
+#dns_server_type = master
+
+#-----------------------
+# PowerDNS Backend
+#-----------------------
+[backend:powerdns]
+#database_connection = mysql://root:password@localhost/pdns
+database_connection = sqlite:///$state_path/pdns.sqlite
+connection_debug = 100
+connection_trace = True
+sqlite_synchronous = True
+idle_timeout = 3600
+max_retries = 10
+retry_interval = 10

doc/source/gettingstarted.rst

@@ -0,0 +1,196 @@
+..
+    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.
+
+.. _gettingstarted:
+
+========================
+Getting Started
+========================
+
+Designate provides DNS As A Service (DNSaaS) for OpenStack:
+
+- REST API for domain/record management
+- Multi-tenant
+- Integrated with Keystone for authentication
+- Framework in place to integrate with Nova and Quantum notifications (for auto-generated records)
+
+- Support for PowerDNS and Bind9 out of the box
+
+Designate is comprised of three components. For more info see :doc:`architecture`.
+
+This guide will show how to install a simple development environment for Designate, with a PowerDNS backend.
+You will be able to see Designate in action, although not to its full potential.
+
+For this guide you will need access to an Ubuntu Server (12.04).
+
+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/powerdns.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/powerdns.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
+
+
+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
+
+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
+   #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 Designate Documentation_.
+
+.. _Documentation: http://designate.readthedocs.org/en/latest/rest.html
+
+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/
+

doc/source/index.rst

@@ -12,6 +12,7 @@ Contents:
    :maxdepth: 2
 
    architecture
+   gettingstarted
    install
    configuration
    rest