zulip/README.dev

Getting started
===============

Using Vagrant
-------------

This is the recommended approach, and is tested on OS X 10.10 as well as Ubuntu 14.04.

If your host is OS X, download VirtualBox from <http://download.virtualbox.org/virtualbox/4.3.30/VirtualBox-4.3.30-101610-OSX.dmg> and install it.

If your host is Ubuntu 14.04:
  sudo apt-get install vagrant lxc lxc-templates cgroup-lite redir

Once that's done, simply change to your zulip directory and run `vagrant up` in your terminal. You can now visit <http://localhost:9991/> in your browser.  To get shell access to the virtual machine running the server, use `vagrant ssh`.

By hand
-------

Install the following non-Python dependencies:
 * libffi-dev — needed for some Python extensions
 * postgresql 9.1 or later — our database (also install development headers)
 * memcached (and headers)
 * rabbitmq-server
 * libldap2-dev
 * python-dev
 * redis-server — rate limiting
 * tsearch-extras — better text search

On Debian or Ubuntu systems:
  sudo apt-get install libffi-dev memcached rabbitmq-server libldap2-dev redis-server postgresql-server-dev-all libmemcached-dev

  # If on 12.04 or wheezy:
  sudo apt-get install postgresql-9.1
  wget https://dl.dropboxusercontent.com/u/283158365/zuliposs/postgresql-9.1-tsearch-extras_0.1.2_amd64.deb
  sudo dpkg -i postgresql-9.1-tsearch-extras_0.1.2_amd64.deb

  # If on 14.04:
  sudo apt-get install postgresql-9.3
  wget https://dl.dropboxusercontent.com/u/283158365/zuliposs/postgresql-9.3-tsearch-extras_0.1.2_amd64.deb
  sudo dpkg -i postgresql-9.3-tsearch-extras_0.1.2_amd64.deb

  # If on 15.04 or jessie:
  sudo apt-get install postgresql-9.4
  wget https://dl.dropboxusercontent.com/u/283158365/zuliposs/postgresql-9.4-tsearch-extras_0.1_amd64.deb
  sudo dpkg -i postgresql-9.4-tsearch-extras_0.1_amd64.deb

  # Then, all versions:
  pip install -r requirements.txt
  ./scripts/setup/configure-rabbitmq
  ./tools/postgres-init-db
  ./tools/do-destroy-rebuild-database

To start the development server:
  ./tools/run-dev.py

… and hit http://localhost:9991/.


Running the test suite
======================

One-time setup of test databases:
  ./tools/postgres-init-test-db
  ./tools/do-destroy-rebuild-test-database

Run all tests:
  ./tools/test-all

This runs the linter plus all of our test suites; they can all be run
separately (just read `tools/test-all` to see them).  You can also run
individual tests, e.g.:
  ./tools/test-backend zerver.test_bugdown.BugdownTest.test_inline_youtube
  ./tools/test-js-with-casper 10-navigation.js

Possible issues
===============

The Casper tests are flaky on the Virtualbox environment (probably due
to some performance-sensitive races).  Until this issue is debugged,
you may need to rerun them to get them to pass.

When running the test suite, if you get an error like this:
    sqlalchemy.exc.ProgrammingError: (ProgrammingError) function ts_match_locs_array(unknown, text, tsquery) does not exist
    LINE 2: ...ECT message_id, flags, subject, rendered_content, ts_match_l...
                                                                 ^
… then you need to install tsearch-extras, described above. Afterwards, re-run the init*-db and the do-destroy-rebuild*-database scripts.