Update the outdated install document

Change-Id: Ie2227b9034d7613b641d5e93c664ffcb1a7e45be

doc/source/architecture.rst

@@ -35,3 +35,10 @@ Brief overview
 
     :term:`api` standard OpenStack alike REST api service that communicates via
     :term:`mq` to do actions like adding records and so on.
+
+    :term:`sink` is a service which listens for notications from Nova/Quantum,
+    and takes action based on the event, and the configured plugins.
+
+    :term:`storage`s are drivers for a particular SQL/NoSQL server.
+
+    :term:`backend`s are drivers for a particular DNS server.

doc/source/install.rst

@@ -27,9 +27,6 @@ see :doc:`architecture`.
    yet been tested with ZeroMQ. We recommend using RabbitMQ for now.
 
 
-From Packages
-+++++++++++++
-
 From Source / GIT
 +++++++++++++++++
 
@@ -45,7 +42,7 @@ Common Steps
 1. Install system package dependencies (Ubuntu)::
 
    $ apt-get install python-pip python-virtualenv
-   $ apt-get install rabbitmq-server bind9
+   $ apt-get install rabbitmq-server
    $ apt-get build-dep python-lxml
 
 2. Clone the Designate repo off of Stackforge::
@@ -64,32 +61,67 @@ Common Steps
 4. Install Designate and it's dependencies::
 
    $ cd designate
-   $ pip install -rtools/setup-requires -rtools/pip-requires -rtools/pip-options
+   $ pip install -r requirements.txt -r test-requirements.txt
    $ python setup.py develop
 
-   Copy sample configs to usable ones, inside the `etc` folder do::
+   Copy sample config files::
 
+   $ cd etc/designate
    $ ls *.sample | while read f; do cp $f $(echo $f | sed "s/.sample$//g"); done
 
-5. Configure Bind or other if needed::
+5. Install a DNS server::
 
-   $ vi /etc/bind/named.conf
+   1. PowerDNS (recommended)::
 
-   Add the following line to the file::
+      Install PowerDNS::
 
-   include "$CHECKOUT_PATH/bind9/zones.config"
+      $ DEBIAN_FRONTEND=noninteractive apt-get install pdns-server pdns-backend-sqlite3
 
-6. Restart bind::
+      Update path to SQLite database to `$CHECKOUT_PATH/powerdns.sqlite`::
 
-   $ sudo service bind9 restart
+      $ editor /etc/powerdns/pdns.d/pdns.local.gsqlite3
 
-7. If you intend to run Designate as a non-root user, then permissions and other
+      Restart PowerDNS::
-   things needs to be fixed up::
 
-   $ MUSER=username
+      $ service pdns restart
-   $ echo "$MUSER ALL=(ALL) NOPASSWD:ALL" | sudo tee -a /etc/sudoers.d/90-designate-$MUSER
-   $ sudo chmod 0440 /etc/sudoers.d/90-designate-$MUSER
 
+   2. BIND9::
+
+      Install BIND9::
+
+      $ apt-get install bind9
+
+      Include the Designate managed zones::
+
+      $ editor /etc/bind/named.conf
+
+      Add the following line to the file::
+
+        include "$CHECKOUT_PATH/bind9/zones.config"
+
+      Disable AppArmor for BIND9::
+
+      $ touch /etc/apparmor.d/disable/usr.sbin.named
+      $ service apparmor reload
+
+      Restart BIND9::
+
+      $ service bind9 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. Configure the common settings::
+
+   Change the necessary configuration settings in the DEFAULT section, the file
+   is in the `etc/designate` folder::
+
+   $ editor designate.conf
+
+   Refer to :doc:`configuration` details on configuring the service.
 
 Note on running processes
 =========================
@@ -98,8 +130,8 @@ You can start each of the processes mentioned below in for example a screen
 session to view output
 
 
-Installing the Central
+Installing the Central Service
-======================
+==============================
 
 .. index::
    double: installing; central
@@ -108,37 +140,58 @@ Installing the Central
 
 2. Configure the :term:`central` service::
 
-   Change the wanted configuration settings to match your environment, the file
+   Change the necessary configuration settings in the service:central,
-   is in the `etc` folder::
+   storage:sqlalchemy sections and, optionally the backend:powerdns section::
 
-   $ vi designate-central.conf
+   $ editor designate.conf
 
    Refer to :doc:`configuration` details on configuring the service.
 
-3. Initialize and sync the :term:`central`::
+   .. note::
+      Pay particular attention to the "backend_driver" setting, along with the
+      two sql_connection strings for service:central, and backend:powerdns.
+
+      These *must* point at different databases.
+
+3. Initialize and sync the Designate database::
 
    $ designate-manage database-init
    $ designate-manage database-sync
 
-4. Start the central service::
+4. Initialize and sync the PowerDNS database, if necessay::
+
+   $ designate-manage powerdns database-init
+   $ designate-manage powerdns database-sync
+
+5. Start the central service::
 
    $ designate-central
 
 
-Installing the Agent
+Installing the Agent Service
-====================
+============================
 
 .. index::
    double: installing; agent
 
+.. note::
+   The agent service is only required when zone configuration must be "manually"
+   propagated to multiple servers. For example, remote BIND9 instances needs to,
+   at the very least, know about all of the zones it is responsible for.
+
+   For the purposes of a single BIND9 quickstart.. You can skip this service.
+
+   If you use PowerDNS, this service can always be skipped.
+
+
 1. See `Common Steps`_ before proceeding.
 
 2. Configure the :term:`agent` service::
 
-   Change the wanted configuration settings to match your environment, the file
+   Change the necessary configuration settings in the service:agent,
-   is in the `etc` folder::
+   and backend:bind9 sections::
 
-   $ vi designate-agent.conf
+   $ editor designate.conf
 
    Refer to :doc:`configuration` details on configuring the service.
 
@@ -147,8 +200,8 @@ Installing the Agent
    $ designate-agent
 
 
-Installing the API
+Installing the API Service
-====================
+==========================
 
 .. index::
    double: installing; api
@@ -161,11 +214,18 @@ Installing the API
 
 2. Configure the :term:`api` service::
 
-   Change the wanted configuration settings to match your environment, the file
+   Change the necessary configuration settings in the service:api section::
-   is in the `etc` folder::
 
-   $ vi designate-api.conf
+   $ editor designate.conf
-   $ vi designate-api-paste.ini
+
+   .. note::
+      Pay particular attention to the "auth_strategy" setting, "noauth" disables
+      all authentication, and keystone requires setup in the api-paste.
+
+   If using the keystone auth_strategy, change the necessary configuration
+   settings in the paste deploy config::
+
+   $ editor api-paste.conf
 
    Refer to :doc:`configuration` details on configuring the service.