create INSTALL.rst

advanced install info moved to INSTALL.rst

INSTALL.rst

@@ -0,0 +1,160 @@
+Installation
+============
+
+This section covers more detailed installation info for pywb.
+
+Requirements
+~~~~~~~~~~~~
+
+pywb has tested in python 2.6, 2.7 and pypy.
+
+It runs best in python 2.7 currently.
+
+pywb tool suite provides several WSGI applications, which have been
+tested under *wsgiref* and *uWSGI*.
+
+For best results, the *uWSGI* container is recommended.
+
+Support for Python 3 is planned.
+
+Sample Data
+~~~~~~~~~~~
+
+pywb comes with a a set of sample archived content, also used by the
+test suite.
+
+The data can be found in ``sample_archive`` and contains ``warc`` and
+``cdx`` files.
+
+The sample archive contains recent captures from ``http://example.com``
+and ``http://iana.org``
+
+Runnable Apps
+~~~~~~~~~~~~~
+
+The pywb tool suite currently includes two runnable applications, installed
+as command-line scripts via setuptools
+
+-  ``wayback`` or ``python -m pywb.apps.wayback`` -- start the full wayback on port
+   8080
+
+-  ``cdx-server`` or ``python -m pywb.apps.cdx_server`` -- start standalone cdx server on
+   port 8090
+   
+-  ``cdx-indexer`` or ``python -m pywb.warc.archiveindexer`` -- create .cdx indexs for
+one more more archive files.
+
+Step-By-Step Installation
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To start a pywb with sample data:
+
+1. Clone this repo
+
+2. Install with ``python setup.py install``
+
+3. Run ``wayback`` (shorthand for ``python -m pywb.apps.wayback``) to start the pywb wayback server with reference WSGI implementation.
+
+OR run ``run-uwsgi.sh`` to start with uWSGI (see below for more info).
+
+4. Test pywb in your browser! (pywb is set to run on port 8080 by
+   default).
+
+If everything worked, the following pages should be loading (served from
+*sample\_archive* dir):
+
++------------------------+----------------------------------------+--------------------------------------------+
+| Original Url           | Latest Capture                         | List of All Captures                       | 
++========================+========================================+============================================+
+| ``http://example.com`` | http://localhost:8080/pywb/example.com | http://localhost:8080/pywb/\*/example.com  |
++------------------------+----------------------------------------+--------------------------------------------+
+| ``http://iana.org``    | http://localhost:8080/pywb/iana.org    | http://localhost:8080/pywb/\*/iana.org     |
++------------------------+----------------------------------------+--------------------------------------------+
+
+uWSGI startup script
+^^^^^^^^^^^^^^^^^^^^
+
+A sample uWSGI start up script, ``run-uwsgi.sh`` which assumes a default
+uWSGI installation is provided as well.
+
+Currently, uWSGI is not installed automatically with this distribution,
+but it is recommended for production environments.
+
+Please see `uWSGI
+Installation <http://uwsgi-docs.readthedocs.org/en/latest/Install.html>`_
+for more details on installing uWSGI.
+
+Vagrant
+~~~~~~~
+
+pywb comes with a Vagrantfile to help you set up a VM quickly for
+testing and deploy pywb with uWSGI.
+
+If you have `Vagrant <http://www.vagrantup.com/>`_ and
+`VirtualBox <https://www.virtualbox.org/>`_ installed, then you can
+start a test instance of pywb like so:
+
+::
+
+    git clone https://github.com/ikreymer/pywb.git
+    cd pywb
+    vagrant up
+
+After pywb and all its dependencies are installed, the uWSGI server will
+startup
+
+::
+
+    spawned uWSGI worker 1 (and the only) (pid: 123, cores: 1)
+
+At this point, you can open a web browser and navigate to the examples
+above for testing.
+
+Test Suite
+~~~~~~~~~~
+
+Currently pywb includes a full (and growing) suite of unit doctest and
+integration tests.
+
+Top level integration tests can be found in the ``tests/`` directory,
+and each subpackage also contains doctests and unit tests.
+
+The full set of tests can be run by executing:
+
+``python setup.py test``
+
+which will run the tests using py.test.
+
+The py.test coverage plugin is used to keep track of test coverage.
+
+Sample Setup
+~~~~~~~~~~~~
+
+pywb is configurable via yaml.
+
+The simplest `config.yaml <https://github.com/ikreymer/pywb/blob/develop/configs/config.yaml>`_ is roughly as follows:
+
+::
+
+
+    collections:
+       pywb: ./sample_archive/cdx/
+
+
+    archive_paths: ./sample_archive/warcs/
+
+This sets up pywb with a single route for collection /pywb
+
+(The the latest version of `config.yaml <https://github.com/ikreymer/pywb/blob/master/config.yaml>`_ contains
+additional documentation and specifies all the optional properties, such
+as ui filenames for Jinja2/html template files.)
+
+For more advanced use, the pywb init path can be customized further:
+
+-  The ``PYWB_CONFIG_FILE`` env can be used to set a different yaml
+   file.
+
+-  Custom init app (with or without yaml) can be created. See
+   `wayback.py <https://github.com/ikreymer/pywb/blob/master/pywb/apps/wayback.py>`_ and
+   `pywb\_init.py <https://github.com/ikreymer/pywb/blob/master/pywb/core/pywb_init.py>`_ for examples of existing
+   initialization paths.