Attempted to clarify install documentation

I've just worked my way through the install process and tried to
clarify/explain anything that wasn't obvious or that I thought might not be
obvious to someone new trying to use this software.

Having encountered all the same problems as @vchoi in issue #5 I've attempted
to update the documentation to clarify the requirements.

Other than that its 'misc' really: some confusion with things like
local_settings.py being missing, changed the headings and shuffled things
around for clarity, expanded on the required django commands etc.
This commit is contained in:
Karl Goetz 2016-01-02 09:46:04 +11:00 committed by Karl Goetz
parent 8b34e7e4ae
commit 49b7559e86
1 changed files with 41 additions and 13 deletions

View File

@ -7,9 +7,25 @@ A Django web application for viewing and editing BIND DNS zone records.
Binder supports adding and deleting DNS records (and eventually editing in place). TSIG-authenticated transfers and updates are supported. Binder supports adding and deleting DNS records (and eventually editing in place). TSIG-authenticated transfers and updates are supported.
## Requirements ## The Binder repository is housed in a [Github](http://github.com/jforman/binder) repository. The repo containts all the Django code and example configuration data for running Binder both in development and production.
Packages: ## Installation ##
There are some build dependencies for the Python mondules, on apt based systems these can be installed with
apt-get install python-dev libxml2-dev libxslt-dev git
Initial checkout has to be performed with git
git clone https://github.com/jforman/binder.git
### Requirements ###
Once the git repository has been cloned these can be installed with one command
pip install -r requirements.txt
Packages installed:
* [Django](http://www.djangoproject.com) * [Django](http://www.djangoproject.com)
* Python Modules * Python Modules
@ -17,32 +33,42 @@ Packages:
* Beautifulsoup4: This library is included as a dependency of pybindmlx when you when you install pybindxml. * Beautifulsoup4: This library is included as a dependency of pybindmlx when you when you install pybindxml.
* [python-dnspython](http://www.dnspython.org/) * [python-dnspython](http://www.dnspython.org/)
* [python-sqlite](http://docs.python.org/2/library/sqlite3.html) (If you will be using Sqlite for server and key storage) * [python-sqlite](http://docs.python.org/2/library/sqlite3.html) (If you will be using Sqlite for server and key storage)
* [Bind DNS Server](http://www.isc.org/software/bind). At least version 9.5.x, which provides instrumentation for gathering process and zone statistics remotely.
## Installation & Configuration ## Elsewhere you will need a [Bind DNS Server](http://www.isc.org/software/bind) running (at least version 9.5.x, which provides instrumentation for gathering process and zone statistics remotely).
The Binder repository is housed in a [Github](http://github.com/jforman/binder) repository. The repo containts all the Django code and example configuration data for running Binder both in development and production.
To verify that required and optional dependencies are installed, execute [check-dependencies.py](https://github.com/jforman/binder/blob/master/check-dependencies.py). This script checks that various Python modules will import correctly. To verify that required and optional dependencies are installed, execute [check-dependencies.py](https://github.com/jforman/binder/blob/master/check-dependencies.py). This script checks that various Python modules will import correctly.
Binder is intended to be installed into the /opt directory in /opt/binder. Forthcoming deb packages will provide for this easy installation and upgrades. Binder is intended to be installed into the /opt directory in /opt/binder. Forthcoming deb packages will provide for this easy installation and upgrades.
Provided under the config directory are various example configurations for runing Binder: ## Configuration ##
config/ ### binder/ ###
If you wish to override anything from settings.py it should be done in a new file
* local_settings.py: Local settings called by Binder templates for TTL choices, record types handled, etc.
### config/ ###
Provided under the config directory are various example configurations for runing Binder:
* binder-apache.conf.dist: Name-based virtual host configuration for running Binder under Apache. * binder-apache.conf.dist: Name-based virtual host configuration for running Binder under Apache.
* django.wsgi: WSGI configuration file called by Apache to run Binder. * django.wsgi: WSGI configuration file called by Apache to run Binder.
* binder-nginx.conf.dist: Name-based virtual host configuration for running Binder under Nginx using fcgi. * binder-nginx.conf.dist: Name-based virtual host configuration for running Binder under Nginx using fcgi.
* binder-upstart.conf.dist: Ubuntu Upstart configuration file for starting Binder upon machine startup. * binder-upstart.conf.dist: Ubuntu Upstart configuration file for starting Binder upon machine startup.
binder/ These are not necesary for development but are useful once moving to production.
* local_settings.py: Local settings called by Binder templates for TTL choices, record types handled, etc. ### Admin user ###
It is necesary to create an administrative user
python manage.py createsuperuser
## Running Binder ##
The development server is run as most Django dev servers are run. The development server is run as most Django dev servers are run.
/opt/binder/manage.py syncdb /opt/binder/manage.py migrate
/opt/binder/manage.py runserver /opt/binder/manage.py runserver
Once you have the Django server up and running, you will want to configure at least one BIND server in the Django Admin app. This includes a hostname, TCP statistics port and a default TSIG transfer key to be used when doing AXFR actions (if necessary). Once you have the Django server up and running, you will want to configure at least one BIND server in the Django Admin app. This includes a hostname, TCP statistics port and a default TSIG transfer key to be used when doing AXFR actions (if necessary).
@ -51,9 +77,9 @@ Keys should also be created, if needed. The name of the key should match the con
Once these two pieces of configuration are done, open up [http://yourserver:port/](http://yourserver:port) to access Binder and begin DNS zone management. Once these two pieces of configuration are done, open up [http://yourserver:port/](http://yourserver:port) to access Binder and begin DNS zone management.
### BIND DNS Server ### ## BIND DNS Server ##
When Binder accesses your BIND DNS server, it first queries the statistics port to gather various zone information. This data includes zone name, view, and serial number. This is all configured by some of the following configuration examples. When Binder accesses your BIND DNS server, it first queries the statistics port to gather zone information. This includes zone name, view, and serial number. This is all configured by some of the following configuration examples.
#### named.conf #### #### named.conf ####
@ -92,6 +118,8 @@ Below are the entire contents of the dynzone.key file. This specifies the name,
referenced as 'dynzone-key' in named.conf referenced as 'dynzone-key' in named.conf
For information on TSIG see http://www.cyberciti.biz/faq/unix-linux-bind-named-configuring-tsig/ .
### Related Configuration ### ### Related Configuration ###
#### Apache HTTPD #### #### Apache HTTPD ####