Prepare for release

1 files changed, 104 insertions, 0 deletions

diff --git a/doc/install.rst b/doc/install.rst
new file mode 100644
index 0000000..6827054
--- /dev/null
+++ b/doc/install.rst
@@ -0,0 +1,104 @@
+============
+Installation
+============
+
+.. note::
+    This installation guide covers HyperKitty, the web user interface to access
+    GNU Mailman v3 Archives. To install GNU Mailman follow the instructions in
+    the documentation: http://packages.python.org/mailman/
+
+
+Install the code
+================
+
+Install the HyperKitty package and its dependencies with the following
+commands::
+
+    sudo pip install -r requirements.txt
+    sudo python setup.py install
+
+
+Setup your django project
+=========================
+
+You now have installed the necessary packages but you still need to setup the
+Django site (project).
+
+First, get the project directory from the source code management system::
+
+    bzr branch bzr://bzr.fedorahosted.org/bzr/hyperkitty/hyperkitty_standalone
+
+Second, change the database setting in ``hyperkitty_standalone/settings.py`` to
+your preferred database. HyperKitty uses two databases, one to store the metadata
+and other to store the emails. Edit this file to reflect the correct database
+credentials. The configuration variables are ``DATABASES`` (at the top of the
+file) and ``KITTYSTORE_URL`` (at the bottom).
+
+.. note::
+    Detailed information on how to use different database engines can be found
+    in the `Django documentation`_.
+
+.. _Django documentation: https://docs.djangoproject.com/en/1.4/ref/settings/#databases
+
+Third, you must setup the database tables, and the admin account (you will be
+prompted for it).
+
+
+.. Setting up the databases
+
+.. include:: database.rst
+
+
+Running HyperKitty on Apache with mod_wsgi
+==========================================
+
+.. note::
+    This guide assumes that you know how to setup a VirtualHost with Apache.
+    If you are using SQLite, the ``.db`` file as well as its folder need to be
+    writable by the web server.
+
+Edit ``hyperkitty_standalone/hyperkitty.apache.conf`` to point to your source
+code location.
+
+Add following line to your apache/httpd configuration file::
+
+    Include "/{path-to-hyperkitty_standalone}/hyperkitty.apache.conf"
+
+And reload Apache. We're almost ready. But you need to collect the static files
+from HyperKitty (which resides somewhere on your pythonpath) to be able to
+serve them from the site directory. All you have to do is to change into the
+``hyperkitty_standalone`` directory and run::
+
+    python manage.py collectstatic
+
+These static files will be served by Apache. You should now be all set. Try
+accessing HyperKitty in your web browser.
+
+
+Connecting to Mailman
+=====================
+
+To receive incoming emails from Mailman, you must add the follwing lines to
+``mailman.cfg``::
+
+    [archiver.hyperkitty]
+    class: hyperkitty.lib.archiver.Archiver
+    enable: yes
+    configuration: /path/to/hyperkitty_standalone/hyperkitty.cfg
+
+The ``hyperkitty.cfg`` file which path is specified by the ``configuration``
+key is an additional HyperKitty-specific configuration file for which an
+example is provided. See the included ``hyperkitty_standalone/hyperkitty.cfg``
+file.
+
+After having made these changes, you must restart Mailman. Check its log files
+to make sure the emails are correctly archived. You should not see "``Broken
+archiver: hyperkitty``" messages.
+
+
+License
+=======
+
+HyperKitty is licensed under the `GPL v3.0`_
+
+.. _GPL v3.0: http://www.gnu.org/licenses/gpl-3.0.html