Source

slipper / doc / webfaction.txt

==================================
 Installing Slipper on Webfaction
==================================


This HOWTO assumes that you are logged into your `Webfaction
<http://webfaction.com>`__ account.


Install virtualenv
------------------

`virtualenv <http://pypi.python.org/pypi/virtualenv/>`__ is a
wonderful tool for isolating Python instances and dependencies.

Install it for Python 2.5::
    
    $ easy_install-2.5 -d $HOME/lib/python2.5 -s $HOME/bin virtualenv


Create an environment for Slipper
---------------------------------

Creating a new environment is easy::
    
    $ cd ~
    $ virtualenv slipper.env


Install Slipper
---------------

Any commands run within the environment's `bin` directory run within
the virtual environment.

Install or upgrade it directly from the repository::
    
    $ slipper.env/bin/easy_install -U \
      http://getschevo.org/hg/slipper-open/archive/tip.tar.gz


Install Mercurial
-----------------

It's useful to just install Mercurial within the virtual environment,
so we know that `Slipper` is always working with the same version.

We need to do this manually, since Mercurial cannot be installed using
`easy_install`::
    
    $ source slipper.env/bin/activate
    (slipper.env)$ mkdir slipper.env/src
    (slipper.env)$ cd slipper.env/src
    (slipper.env)$ easy_install -eb. -U Mercurial
    (slipper.env)$ cd mercurial
    (slipper.env)$ python2.5 setup.py install
    (slipper.env)$ which hg
    ~/slipper.env/bin/hg


Set up objects in Webfaction control panel
------------------------------------------

Create a new `Custom app (listening on port)` app to host your
`Slipper` WSGI application, named something like `my_slipper_wsgi`.
Go back to the list of apps and make a note of the port it should
listen on.

Mount the app on your website at a location of your choice (such as
``/s``) and make a note of the mount point.

If you don't already have a `Static/CGI/PHP` app with which to place
static files and an ``.htaccess`` file, create one, named something
like `my_slipper_static`, and mount it to your website.


Create configuration files
--------------------------

Let's say you want to host this repository at the root of
``http://mysite.com/``:

- It's located on disk at ``/home2/myusername/hg/myapp-dev``

- You use the ``.txt`` file extension to tag reStructuredText
  documents.

- You want to serve the ``doc/`` directory within the repository as
  the root of the site.

- You want to serve the ``tip`` revision.

- You have a `hgweb` or `hgwebdir` presenting the repository at
  ``http://mysite.com/hg/myapp-dev/``.

Create a configuration file, such as ``slipper.ini``, and place it in
the directory of the web app you created, such as
``/home2/myusername/webapps/my_slipper_wsgi``. Make it look like this,
replacing the value of `port` with the port that you noted earlier:

.. sourcecode:: ini 

    [server:main]
    use = egg:Paste#http
    host = 127.0.0.1
    port = 1234

    [app:main]
    use = egg:Slipper

    slipper.myapp-dev.local_dir = /home2/myusername/hg/myapp-dev
    slipper.myapp-dev.hgweb_url = http://mysite.com/hg/myapp-dev
    slipper.myapp-dev.rst_extension = .txt
    slipper.myapp-dev.cache_dir = /home2/myusername/slipper.env/cache

.. note::

    In addition to setting the `rst_extension` and `cache_dir`
    settings on a per-repository basis, you may also set them globally
    by using the repository name ``DEFAULT``, as in the following
    example::

        slipper.DEFAULT.rst_extension = .txt
        slipper.DEFAULT.cache_dir = /home2/myusername/slipper.env/cache


Start Slipper server
--------------------

Change to the directory of your `Slipper` WSGI webapp, such as
`/home2/myusername/webapps/my_slipper_wsgi`.  Start the server in
foreground mode::

    $ cd /home2/myusername/webapps/my_slipper_wsgi
    $ ~/slipper.env/bin/paster serve --reload slipper.ini

Verify that it worked by visiting
``http://mysite.com/s/myapp-dev/tip/doc/index.html``. You should see
the index page of your site, provided there is an ``index.txt`` in the
``doc`` directory in your repository.

Now make that available as ``http://mysite.com/`` and make other
resources available as well by creating, or adding to, the
``.htaccess`` file in the directory of your static app, such as
``/home2/myusername/webapps/my_slipper_static``::
    
    RewriteEngine On
    RewriteBase /

    RewriteRule ^$ /s/myapp-dev/tip/doc/index.txt [L]

    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteRule ^(.*)$ /s/myapp-dev/tip/doc/$1 [L]

.. note::

    If your `my_slipper` Webfaction app is mounted on your site at a
    location other than ``/``, be sure to set `RewriteBase` to that
    point rather than ``/`` as shown in these examples.

To make available specific versions, add some more rules, paying
attention to proper ordering (since they are evaluated sequentially)::
    
    RewriteEngine On
    RewriteBase /

    RewriteRule ^$ /s/myapp-dev/tip/doc/index.txt [L]
    
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteRule ^v/([^/]*)/(.*)$ /s/myapp-dev/$1/doc/$2 [L]

    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteRule ^(.*)$ /s/myapp-dev/tip/doc/$1 [L]


Run Slipper server in background
--------------------------------

Stop the slipper server you started above by pressing `Ctrl-C`.

Open your `crontab` for editing::

    $ crontab -e

Add a new entry to the file to start the server and keep its PID
within your webapp directory::

    6,26,46 * * * * $HOME/slipper.env/bin/paster serve \
        --daemon --pid-file=$HOME/webapps/my_slipper_wsgi/slipper.pid \
        --log-file=$HOME/logs/user/my_slipper_wsgi.log \
        $HOME/webapps/my_slipper_wsgi/slipper.ini >/dev/null 2>&1

Save the file and exit the editor.

You can either wait for 6, 26, or 46 minutes past the hour for the
server to start on its own, or you can enter the command above
starting at ``$HOME`` to start the server right away.

Once the server starts, further attempts each 20 minutes to start the
server again will be benign if the server is still running.


Stopping the server
-------------------

Edit your `crontab` as described in `Start Slipper server`_ above, and
place a ``#`` character in front of each line to comment out the
startup command.

Run the command to stop your app::

    $ ~/slipper.env/bin/paster serve --stop-daemon \
        --pid-file=$HOME/webapps/my_slipper_wsgi/slipper.pid