aboutsummaryrefslogtreecommitdiffstats
path: root/doc/installation.rst
diff options
context:
space:
mode:
authorTomasz Mieszkowski <tomasz.mieszkowski@ext.allegro.pl>2014-08-28 08:54:15 +0200
committerTomasz Mieszkowski <tomasz.mieszkowski@ext.allegro.pl>2014-08-28 08:54:15 +0200
commit60c073a6ed451cf91d9877a3305407756b9ffdce (patch)
tree955542ec282745e31d78d1b2b9515d8cebe67e78 /doc/installation.rst
downloadtipboard-60c073a6ed451cf91d9877a3305407756b9ffdce.tar.gz
tipboard-60c073a6ed451cf91d9877a3305407756b9ffdce.tar.bz2
tipboard-60c073a6ed451cf91d9877a3305407756b9ffdce.zip
Tipboard got open-sourced!1.4.0
Diffstat (limited to 'doc/installation.rst')
-rw-r--r--doc/installation.rst98
1 files changed, 98 insertions, 0 deletions
diff --git a/doc/installation.rst b/doc/installation.rst
new file mode 100644
index 0000000..9f16ff0
--- /dev/null
+++ b/doc/installation.rst
@@ -0,0 +1,98 @@
+.. _installation:
+
+==============
+How to install
+==============
+
+You can install Tipboard on a variety of sensible operating systems. This guide
+assumes **Ubuntu Server 12.04 LTS** and presents shell command examples
+accordingly.
+
+Prerequisites
+-------------
+
+Tipboard requires Python 2.7 which can be installed with this command::
+
+ $ sudo apt-get install python-dev python-virtualenv
+
+Another dependency which needs to be satisfied before proceeding further is
+`Redis <http://redis.io/>`_ server::
+
+ $ sudo apt-get install redis-server
+
+Optional yet recommended packages
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+One of such packages is ``supervisor`` - it facilitates program administration
+(e.g. its reboot), especially if there are a few instances launched on the
+machine.
+
+Based on the Tornado framework, Tipboard has a built-in server available, but
+a typical use case assumes communication with the world via reverse proxy (e.g.
+using ``nginx`` or ``apache``).
+
+.. note::
+
+ Although configuration of reverse proxy is out of scope of this manual, we
+ would like to emphasise that Tipboard use Web Sockets – a relatively new
+ mechanism – and thus you should ensure a server in a version that will
+ support it (e.g. ``nginx`` >= 1.3.13 or ``apache2`` >= 2.4.6). By default
+ Ubuntu 12.04 offers older versions – you may then use backports.
+
+.. note::
+
+ It will be useful to have an updated version of ``pip`` (i.e. >= 1.4) and
+ ``virtualenv`` (i.e. >= 1.10).
+
+Preparing environment for installation
+--------------------------------------
+
+Start by creating a user, the privileges of whom will be used by the
+application (for the needs of this manual, let's create the user "pylabs")::
+
+ $ sudo adduser pylabs --home /home/pylabs --shell /bin/bash
+ $ sudo su - pylabs
+
+Virtual environment
+~~~~~~~~~~~~~~~~~~~
+
+Continue by creating a virtual environment that will help you conveniently
+separate your instance from what you already have installed in the system
+(let's say we name it "tb-env")::
+
+ $ cd /home/pylabs
+ $ virtualenv tb-env
+
+Activate the created virtual environment with the following command::
+
+ $ source /home/pylabs/tb-env/bin/activate
+
+.. note::
+
+ It is worth saving the above line in the ``~/.profile`` file. As a result,
+ the virtual environment will be activated automatically whenever you log in
+ on the machine.
+
+.. note::
+
+ Further setup assumes an activated virtual environment, which is denoted by
+ ``(tb-env)`` prefix in your shell prompt.
+
+Installing with pip
+-------------------
+
+After creating and activating virtualenv, install the latest (current) version
+of Tipboard package available on pypi ("Python Package Index") with the
+following command::
+
+ (tb-env)$ pip install tipboard
+
+Verification
+------------
+
+To verify if installation has been successful, launch this command::
+
+ (tb-env)$ tipboard runserver
+
+If you see the message "Listening on port..." instead of errors, it means that
+installation was successful and you may proceed to the next section.