06.01 SC Developer Setup

SuttaCentral Developer Setup

1. Install pyenv python virtual environment

pyenv is a newer alternative to virtualenv and tends to be more straightforward to use as a development/deployment environment, pyenv is designed for installing python to the $HOME folder and does not depend on any operating system version of python. Instructions are for Ubuntu/Debian but the method is extremely similar for other Linuxes. For Windows you are on your own.

Install git sudo apt-get install git

Install pyenv git clone git://github.com/yyuu/pyenv.git ~/.pyenv

Install pyenv virtualenv git clone https://github.com/yyuu/pyenv-virtualenv.git ~/.pyenv/plugins/pyenv-virtualenv

Add the following to ~/.bashrc

export PYENV_ROOT="${HOME}/.pyenv"

if [ -d "${PYENV_ROOT}" ]; then
    export PATH="${PYENV_ROOT}/bin:${PATH}"
    eval "$(pyenv init -)"
fi

Restart bash so the changes to .bashrc take effect, just run bash

When you use pyenv it will download and compile a copy of python which is unique to the environment. This is useful as the distribution python might be outdated.

Install build dependencies

sudo apt-get install zlib1g-dev libncurses5-dev libreadline-dev libssl-dev libbz2-dev libsqlite3-dev tk-dev libgdbm-dev

Install python3.4 (3.4 has superior virtual environment support)

pyenv install 3.4.1

2. Clone the Sutta Central Git Repository

If you wish to be able to push changes to the github repository you should first add your ssh public key to github, then use the following commands:

git clone git@github.com:suttacentral/suttacentral.git ~/suttacentral
cd ~/suttacentral
git clone git@github.com:suttacentral/suttacentral-data.git data

ALTERNATIVELY, if you are content with simply running the server, and do not require or are not authorized with write access to the github repository, you should use https instead:

git clone https://github.com/suttacentral/suttacentral.git ~/suttacentral
cd ~/suttacentral
git clone https://github.com/suttacentral/suttacentral-data.git data

3. Create a virtual environment for sutta central

pyenv virtualenv 3.4.1 suttacentral

Specify that the suttacentral project is to use that virtual environment

cd ~/suttacentral
pyenv local suttacentral

You can also manually activate the virtual environment by entering:

pyenv activate suttacentral

But by setting pyenv local you don't ever need to perform this step unless for some reason you want to use the suttacentral environment outside the suttacentral folder hierarchy.

4. Install Python Packages

Install package build dependencies

sudo apt-get install libxml2-dev libxslt1-dev zlib1g-dev

Use pip to download and install all required python packages

pip install -r requirements.txt

Note that the .pyenv folder can be zipped up and copied to another user account or sometimes even other linuxes (depending on library compatibility), easily duplicating the environment. This works because it is contained entirely within the home folder and has no symlinks to system files. However doing so may not be recommended and pyenv uses symlinks which may result in problems.

5. Install external programs used by the Sutta Central invoke scripts

sudo apt-get install -y zip unzip p7zip-full zopfli

6. Edit Configuration

Copy local.conf-example to local.conf. You probably don't need edit anything as the defaults are suitable.

7. Run the Server

Run the server:

invoke server

Please note that the first time Sutta Central starts, it will need to create it's database of the texts available in the data/texts folder (the so called 'Text Info Model'), this may take up to 10 minutes. On future runs the server will start much more quickly, only around 10 seconds.

It is possible that on the first run the server may fail to start, basically because certain resources took too long to become available. After letting it run until it throws an exception (a large incomprehensible stack trace), kill the server by hitting ctrl-c. Then run invoke server again and it should start correctly.

Then browse to http://localhost:8800/.

7.1 Killing the server

When you have started the server using invoke server you should kill it by hitting ctrl-c in that terminal. You might have to wait a few seconds and hit ctrl-c again if it does not terminate right away.

Note that webservers are designed to be hard to kill. Closing the terminal may not be sufficient to kill it. If it still seems to be running you can use this command to send a kill signal:

killall cherryd

This kills the cherrypy webserver.