Commits

George Notaras committed d4cca7f

Updated documentation and added a HTML version of the HTML document.

  • Participants
  • Parent commits 275b7d2

Comments (0)

Files changed (5)

 This file contains detailed information on how to configure and use
 ``django-postgresql-manager``.
 
-How to read this document
--------------------------
-This document is written in ``reStructuredText`` (*rst*). Although reStructuredText
-is an easy-to-read plain text markup format, it is recommended to convert it
-to *HTML* for a better reading experience.
 
-In order to convert this document to *HTML* you need ``docutils``, which you can
-install in your system using ``pip``::
+PostgreSQL Administrator Role
+=============================
+This application requires that you create a PostgreSQL (refered to as *Pg*
+hereafter) role which will be used for the role and database management.
 
-    pip install docutils
+While in the Pg shell as a superuser, create the *administrator* role::
 
-Or ``easy_install``::
+    CREATE ROLE administrator WITH LOGIN CREATEDB CREATEROLE PASSWORD '1234';
 
-    easy_install docutils
-
-Once ``docutils`` is installed, you can use the ``rst2html.py`` utility to
-do the conversion::
-
-    rst2html.py HELP help.html
-
-Then use any web browser to view the exported ``help.html`` file.
 
 
 Configuration
 =============
-DATABASES = {
-    'default': {
-        'ENGINE': 'django.db.backends.mysql', # Add 'postgresql_psycopg2', 'postgresql', 'mysql', 'sqlite3' or 'oracle'.
-        'NAME': 'primarypanel',                      # Or path to database file if using sqlite3.
-        'USER': 'panel-user',                      # Not used with sqlite3.
-        'PASSWORD': 'XXXXXXXXX',                  # Not used with sqlite3.
-        'HOST': 'localhost',                      # Set to empty string for localhost. Not used with sqlite3.
-        'PORT': '',                      # Set to empty string for default. Not used with sqlite3.
-    },
-    # Database settings for pgmanager
-    'pgmanager_conn': {
-        'ENGINE': 'django.db.backends.postgresql_psycopg2', # Add 'postgresql_psycopg2', 'postgresql', 'mysql', 'sqlite3' or 'oracle'.
-        'NAME': 'postgres',                      # Or path to database file if using sqlite3.
-        'USER': 'administrator',                      # Not used with sqlite3.
-        'PASSWORD': 'XXXXXXX',                  # Not used with sqlite3.
-        'HOST': '',                      # Set to empty string for localhost. Not used with sqlite3.
-        'PORT': '',                      # Set to empty string for default. Not used with sqlite3.
-        'OPTIONS': {
-            'autocommit': True,
+This section outlines the configuration options that need to be set in your
+Django project's ``settings.py`` file.
+
+Add an extra database connection, named ``PostgreSQL_manager_conn``,
+which will be used to connect to the PostgreSQL cluster using the
+``administrator`` role::
+
+    DATABASES = {
+        ...
+        # Database connection settings for PostgreSQL_manager
+        'PostgreSQL_manager_conn': {
+            'ENGINE': 'django.db.backends.postgresql_psycopg2',
+            'NAME': 'postgres',
+            'USER': 'administrator',
+            'PASSWORD': '1234',
+            'HOST': 'localhost',
+            'PORT': '5432',
+            'OPTIONS': {
+                'autocommit': True,
+            },
         },
-    },
-}
+        ...
+    }
 
+**Important Note**: It should be noted that the ``PostgreSQL_manager_conn``
+database connection is only used to perform role and database management
+on the PostgreSQL Cluster. No extra databases or tables will be created.
+The ``PostgreSQL_manager`` application specific tables will be created in
+the Django project's default database, which may exist in any database
+backend.
 
-INSTALLED_APPS = (
-    # My apps here
-    'staticfiles',
-    'PrimaryPanel.unixauth',
-    'PrimaryPanel.dbmanagement',
-    'PostgreSQL_manager',
-    'PrimaryPanel.hosting',
-    'PrimaryPanel.mailadmin',
-    'PrimaryPanel.spamassassin',
+Add the ``PostgreSQL_manager`` app in the ``INSTALLED_APPS`` setting::
 
-)
+    INSTALLED_APPS = (
+        ...
+        'PostgreSQL_manager',
+        ...
+    )
 
-python manage.py syncdb
+Optional Configuration Settings
+-------------------------------
+``PostgreSQL_manager`` supports the following configuration settings:
 
+**PGMANAGER_FORBIDDEN_USER_NAMES**
+    A list of role names that should not be used. By default, the following role
+    names are forbidden: postgres, postgresql, pg, admin, administrator, root,
+    sys, system.
+**PGMANAGER_FORBIDDEN_DATABASE_NAMES**
+    A list of database names that should not be used. By default, the following
+    names are forbidden: postgres, template0, template1.
+
+
+Synchronize the Django Project database
+---------------------------------------
+Finally synchronize your project database::
+
+    python manage.py syncdb
+
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<meta name="generator" content="Docutils 0.7: http://docutils.sourceforge.net/" />
+<title></title>
+<style type="text/css">
+
+/*
+:Author: David Goodger (goodger@python.org)
+:Id: $Id: html4css1.css 6253 2010-03-02 00:24:53Z milde $
+:Copyright: This stylesheet has been placed in the public domain.
+
+Default cascading style sheet for the HTML output of Docutils.
+
+See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
+customize this style sheet.
+*/
+
+/* used to remove borders from tables and images */
+.borderless, table.borderless td, table.borderless th {
+  border: 0 }
+
+table.borderless td, table.borderless th {
+  /* Override padding for "table.docutils td" with "! important".
+     The right padding separates the table cells. */
+  padding: 0 0.5em 0 0 ! important }
+
+.first {
+  /* Override more specific margin styles with "! important". */
+  margin-top: 0 ! important }
+
+.last, .with-subtitle {
+  margin-bottom: 0 ! important }
+
+.hidden {
+  display: none }
+
+a.toc-backref {
+  text-decoration: none ;
+  color: black }
+
+blockquote.epigraph {
+  margin: 2em 5em ; }
+
+dl.docutils dd {
+  margin-bottom: 0.5em }
+
+/* Uncomment (and remove this text!) to get bold-faced definition list terms
+dl.docutils dt {
+  font-weight: bold }
+*/
+
+div.abstract {
+  margin: 2em 5em }
+
+div.abstract p.topic-title {
+  font-weight: bold ;
+  text-align: center }
+
+div.admonition, div.attention, div.caution, div.danger, div.error,
+div.hint, div.important, div.note, div.tip, div.warning {
+  margin: 2em ;
+  border: medium outset ;
+  padding: 1em }
+
+div.admonition p.admonition-title, div.hint p.admonition-title,
+div.important p.admonition-title, div.note p.admonition-title,
+div.tip p.admonition-title {
+  font-weight: bold ;
+  font-family: sans-serif }
+
+div.attention p.admonition-title, div.caution p.admonition-title,
+div.danger p.admonition-title, div.error p.admonition-title,
+div.warning p.admonition-title {
+  color: red ;
+  font-weight: bold ;
+  font-family: sans-serif }
+
+/* Uncomment (and remove this text!) to get reduced vertical space in
+   compound paragraphs.
+div.compound .compound-first, div.compound .compound-middle {
+  margin-bottom: 0.5em }
+
+div.compound .compound-last, div.compound .compound-middle {
+  margin-top: 0.5em }
+*/
+
+div.dedication {
+  margin: 2em 5em ;
+  text-align: center ;
+  font-style: italic }
+
+div.dedication p.topic-title {
+  font-weight: bold ;
+  font-style: normal }
+
+div.figure {
+  margin-left: 2em ;
+  margin-right: 2em }
+
+div.footer, div.header {
+  clear: both;
+  font-size: smaller }
+
+div.line-block {
+  display: block ;
+  margin-top: 1em ;
+  margin-bottom: 1em }
+
+div.line-block div.line-block {
+  margin-top: 0 ;
+  margin-bottom: 0 ;
+  margin-left: 1.5em }
+
+div.sidebar {
+  margin: 0 0 0.5em 1em ;
+  border: medium outset ;
+  padding: 1em ;
+  background-color: #ffffee ;
+  width: 40% ;
+  float: right ;
+  clear: right }
+
+div.sidebar p.rubric {
+  font-family: sans-serif ;
+  font-size: medium }
+
+div.system-messages {
+  margin: 5em }
+
+div.system-messages h1 {
+  color: red }
+
+div.system-message {
+  border: medium outset ;
+  padding: 1em }
+
+div.system-message p.system-message-title {
+  color: red ;
+  font-weight: bold }
+
+div.topic {
+  margin: 2em }
+
+h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
+h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
+  margin-top: 0.4em }
+
+h1.title {
+  text-align: center }
+
+h2.subtitle {
+  text-align: center }
+
+hr.docutils {
+  width: 75% }
+
+img.align-left, .figure.align-left, object.align-left {
+  clear: left ;
+  float: left ;
+  margin-right: 1em }
+
+img.align-right, .figure.align-right, object.align-right {
+  clear: right ;
+  float: right ;
+  margin-left: 1em }
+
+img.align-center, .figure.align-center, object.align-center {
+  display: block;
+  margin-left: auto;
+  margin-right: auto;
+}
+
+.align-left {
+  text-align: left }
+
+.align-center {
+  clear: both ;
+  text-align: center }
+
+.align-right {
+  text-align: right }
+
+/* reset inner alignment in figures */
+div.align-right {
+  text-align: left }
+
+/* div.align-center * { */
+/*   text-align: left } */
+
+ol.simple, ul.simple {
+  margin-bottom: 1em }
+
+ol.arabic {
+  list-style: decimal }
+
+ol.loweralpha {
+  list-style: lower-alpha }
+
+ol.upperalpha {
+  list-style: upper-alpha }
+
+ol.lowerroman {
+  list-style: lower-roman }
+
+ol.upperroman {
+  list-style: upper-roman }
+
+p.attribution {
+  text-align: right ;
+  margin-left: 50% }
+
+p.caption {
+  font-style: italic }
+
+p.credits {
+  font-style: italic ;
+  font-size: smaller }
+
+p.label {
+  white-space: nowrap }
+
+p.rubric {
+  font-weight: bold ;
+  font-size: larger ;
+  color: maroon ;
+  text-align: center }
+
+p.sidebar-title {
+  font-family: sans-serif ;
+  font-weight: bold ;
+  font-size: larger }
+
+p.sidebar-subtitle {
+  font-family: sans-serif ;
+  font-weight: bold }
+
+p.topic-title {
+  font-weight: bold }
+
+pre.address {
+  margin-bottom: 0 ;
+  margin-top: 0 ;
+  font: inherit }
+
+pre.literal-block, pre.doctest-block {
+  margin-left: 2em ;
+  margin-right: 2em }
+
+span.classifier {
+  font-family: sans-serif ;
+  font-style: oblique }
+
+span.classifier-delimiter {
+  font-family: sans-serif ;
+  font-weight: bold }
+
+span.interpreted {
+  font-family: sans-serif }
+
+span.option {
+  white-space: nowrap }
+
+span.pre {
+  white-space: pre }
+
+span.problematic {
+  color: red }
+
+span.section-subtitle {
+  /* font-size relative to parent (h1..h6 element) */
+  font-size: 80% }
+
+table.citation {
+  border-left: solid 1px gray;
+  margin-left: 1px }
+
+table.docinfo {
+  margin: 2em 4em }
+
+table.docutils {
+  margin-top: 0.5em ;
+  margin-bottom: 0.5em }
+
+table.footnote {
+  border-left: solid 1px black;
+  margin-left: 1px }
+
+table.docutils td, table.docutils th,
+table.docinfo td, table.docinfo th {
+  padding-left: 0.5em ;
+  padding-right: 0.5em ;
+  vertical-align: top }
+
+table.docutils th.field-name, table.docinfo th.docinfo-name {
+  font-weight: bold ;
+  text-align: left ;
+  white-space: nowrap ;
+  padding-left: 0 }
+
+h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
+h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
+  font-size: 100% }
+
+ul.auto-toc {
+  list-style-type: none }
+
+</style>
+</head>
+<body>
+<div class="document">
+
+
+<div class="section" id="django-postgresql-manager-help">
+<h1>django-postgresql-manager Help</h1>
+<p>This file contains detailed information on how to configure and use
+<tt class="docutils literal"><span class="pre">django-postgresql-manager</span></tt>.</p>
+<div class="section" id="how-to-read-this-document">
+<h2>How to read this document</h2>
+<p>This document is written in <tt class="docutils literal">reStructuredText</tt> (<em>rst</em>). Although reStructuredText
+is an easy-to-read plain text markup format, it is recommended to convert it
+to <em>HTML</em> for a better reading experience.</p>
+<p>In order to convert this document to <em>HTML</em> you need <tt class="docutils literal">docutils</tt>, which you can
+install in your system using <tt class="docutils literal">pip</tt>:</p>
+<pre class="literal-block">
+pip install docutils
+</pre>
+<p>Or <tt class="docutils literal">easy_install</tt>:</p>
+<pre class="literal-block">
+easy_install docutils
+</pre>
+<p>Once <tt class="docutils literal">docutils</tt> is installed, you can use the <tt class="docutils literal">rst2html.py</tt> utility to
+do the conversion:</p>
+<pre class="literal-block">
+rst2html.py HELP help.html
+</pre>
+<p>Then use any web browser to view the exported <tt class="docutils literal">help.html</tt> file.</p>
+</div>
+</div>
+<div class="section" id="postgresql-administrator-role">
+<h1>PostgreSQL Administrator Role</h1>
+<p>This application requires that you create a PostgreSQL (refered to as <em>Pg</em>
+hereafter) role which will be used for the role and database management.</p>
+<p>While in the Pg shell as a superuser, create the <em>administrator</em> role:</p>
+<pre class="literal-block">
+CREATE ROLE administrator WITH LOGIN CREATEDB CREATEROLE PASSWORD '1234';
+</pre>
+</div>
+<div class="section" id="configuration">
+<h1>Configuration</h1>
+<p>This section outlines the configuration options that need to be set in your
+Django project's <tt class="docutils literal">settings.py</tt> file.</p>
+<p>Add an extra database connection, named <tt class="docutils literal">PostgreSQL_manager_conn</tt>,
+which will be used to connect to the PostgreSQL cluster using the
+<tt class="docutils literal">administrator</tt> role:</p>
+<pre class="literal-block">
+DATABASES = {
+    ...
+    # Database connection settings for PostgreSQL_manager
+    'PostgreSQL_manager_conn': {
+        'ENGINE': 'django.db.backends.postgresql_psycopg2',
+        'NAME': 'postgres',
+        'USER': 'administrator',
+        'PASSWORD': '1234',
+        'HOST': 'localhost',
+        'PORT': '5432',
+        'OPTIONS': {
+            'autocommit': True,
+        },
+    },
+    ...
+}
+</pre>
+<p><strong>Important Note</strong>: It should be noted that the <tt class="docutils literal">PostgreSQL_manager_conn</tt>
+database connection is only used to perform role and database management
+on the PostgreSQL Cluster. No extra databases or tables will be created.
+The <tt class="docutils literal">PostgreSQL_manager</tt> application specific tables will be created in
+the Django project's default database, which may exist in any database
+backend.</p>
+<p>Add the <tt class="docutils literal">PostgreSQL_manager</tt> app in the <tt class="docutils literal">INSTALLED_APPS</tt> setting:</p>
+<pre class="literal-block">
+INSTALLED_APPS = (
+    ...
+    'PostgreSQL_manager',
+    ...
+)
+</pre>
+<div class="section" id="optional-configuration-settings">
+<h2>Optional Configuration Settings</h2>
+<p><tt class="docutils literal">PostgreSQL_manager</tt> supports the following configuration settings:</p>
+<dl class="docutils">
+<dt><strong>PGMANAGER_FORBIDDEN_USER_NAMES</strong></dt>
+<dd>A list of role names that should not be used. By default, the following role
+names are forbidden: postgres, postgresql, pg, admin, administrator, root,
+sys, system.</dd>
+<dt><strong>PGMANAGER_FORBIDDEN_DATABASE_NAMES</strong></dt>
+<dd>A list of database names that should not be used. By default, the following
+names are forbidden: postgres, template0, template1.</dd>
+</dl>
+</div>
+<div class="section" id="synchronize-the-django-project-database">
+<h2>Synchronize the Django Project database</h2>
+<p>Finally synchronize your project database:</p>
+<pre class="literal-block">
+python manage.py syncdb
+</pre>
+</div>
+</div>
+</div>
+</body>
+</html>
 include AUTHORS
 include BUGS
 include HELP
+include HELP.html
 include INSTALL
 include LICENSE
 include NOTICE
 The following list outlines the kind of information each of the files of this
 distribution package contains:
 
- * AUTHORS : List of all authors and contributors.
- * BUGS    : Information about how to file bug reports or ask for new features.
- * HELP    : Instructions on how to use this software.
- * INSTALL : Information and examples of how to use the provided installation
- * LICENSE : The terms of the license that governs your use of this software.
- * NOTICE  : Copyright, trademark, attribution and sponsorship information.
- * SUPPORT : Information on how to get support for this software.
- * README  : This file.
+ * AUTHORS  : List of all authors and contributors.
+ * BUGS     : Information about how to file bug reports or ask for new features.
+ * HELP     : Instructions on how to use this software.
+ * HELP.html: A HTML version of the HELP document.
+ * INSTALL  : Information and examples of how to use the provided installation
+ * LICENSE  : The terms of the license that governs your use of this software.
+ * NOTICE   : Copyright, trademark, attribution and sponsorship information.
+ * SUPPORT  : Information on how to get support for this software.
+ * README   : This file.
 
 
 License
 optimize = 1
 
 [bdist_rpm]
-doc_files = AUTHORS BUGS HELP LICENSE NOTICE README SUPPORT
+doc_files = AUTHORS BUGS HELP HELP.html LICENSE NOTICE README SUPPORT
 group = Development/Libraries