Development Installation¶
Warning
This installation guide is designed for debian based operating systems.
Other Linux distributions are good as well but the name of some packages may vary.
This document describes how to install nodeshot for development.
We are assuming you are executing commands as a sudoer user but not root.
Related pages: Contribute to nodeshot.
Install dependencies¶
First of all, update your apt cache:
sudo apt-get update --fix-missing
Install dependencies and development packages:
# dependencies
sudo apt-get install python-software-properties software-properties-common build-essential libxml2-dev python-setuptools python-virtualenv python-dev binutils libjson0-dev libjpeg-dev libffi-dev libpq-dev
# dev packages
sudo apt-get install wget git
Install postgresql, postgis and geospatial libraries:
sudo apt-get install postgis* libproj-dev gdal-bin libgdal1-dev python-gdal
Create database¶
Become postgres
user:
sudo su postgres
Create database, create required postgresql extensions, create a superuser:
createdb nodeshot
psql nodeshot
CREATE EXTENSION postgis;
CREATE EXTENSION hstore;
CREATE USER nodeshot WITH PASSWORD 'your_password';
ALTER USER nodeshot SUPERUSER;
exit (press CTRL+D) and go back to being your user:
exit
Install python packages¶
First of all, install virtualenvwrapper (systemwide):
sudo pip install virtualenvwrapper
virtualenvwrapper needs some initialization before you can use its shortcuts:
echo 'source /usr/local/bin/virtualenvwrapper.sh' >> ~/.bashrc
source ~/.bashrc
Create a python virtual environment, which is a self-contained python installation which will contain all the python packages required by nodeshot:
mkvirtualenv nodeshot
Update the basic python utilities:
pip install -U setuptools pip wheel
Clone your fork in your favourite location (/home/<user>
or /var/www
), have you forked nodeshot, right?
git clone git@github.com:<YOUR-FORK>/nodeshot.git
cd nodeshot
Replace <YOUR-FORK>
with your github username (be sure to have forked nodeshot first).
Install the required python packages:
pip install -r requirements.txt
Finally install nodeshot with:
python setup.py develop
Create the development project, be sure it’s called dev:
nodeshot startproject dev && cd dev
Project configuration¶
Open settings.py
:
vim dev/settings.py
And edit the following settings:
DOMAIN
: set localhostDATABASE['default']['USER']
: set nodeshotDATABASE['default']['PASSWORD']
: set the password chosen during the Create database step
Create the database tables and initial data:
# will prompt you to create a superuser, proceed!
./manage.py migrate --no-initial-data && ./manage.py loaddata initial_data
Run the development server:
./manage.py runserver
Alternatively, if you need to reach the dev server for other hosts on the same LAN, you can setup the development server to listen on all the network interfaces:
./manage.py runserver 0.0.0.0:8000
Now you can open your browser at http://localhost:8000/ or at http://localhost:8000/admin/.
How to setup the test environment¶
The /test
directory contains a nodeshot project called ci
(stands for continuous integration)
that is needed to run automated tests (unit tests, functional tests and regression tests).
Install the hstore extension on template1 according to how to run tests with django-hstore:
sudo su postgres
psql template1 -c 'CREATE EXTENSION hstore;'
exit
Do a cd
into the /test
dir:
cd /[PATH-TO-NODESHOT-REPO]/tests
Create a local_settings.py
file:
cp ci/local_settings.example.py ci/local_settings.py
Ensure your virtualenv is activated:
workon nodeshot
Run all the tests with:
./runtests.py --keepdb
The keepdb
option allows to avoid recreating the test database at each run, hence saving precious time.
If you want to speed up tests even more, tweak your local postgresql configuration by setting these values:
# /etc/postgresql/9.1/main/postgresql.conf
# only for development!
fsync = off
synchronous_commit = off
full_page_writes = off
Test specific modules¶
Each module has its own tests, so you can test one module at time:
python manage.py test --keepdb nodeshot.core.nodes
You can also test more modules:
python manage.py test --keepdb nodeshot.core.nodes nodeshot.core.layers nodeshot.core.cms
Test coverage¶
Install coverage package:
pip install coverage
Run test coverage and get a textual report:
coverage run --source=nodeshot runtests.py --keepdb && coverage report
Calculate test coverage for specific modules:
coverage run --source=nodeshot.core.nodes ./manage.py test --keepdb nodeshot.core.nodes && coverage report
Measure time spent running tests¶
Automated tests that involve database calls and/or HTTP requests can quickly become slow.
Slow tests mean low productivity, especially if you are used to Test Driven Development.
For this reason, if you notice that some tests are slow, you have two additional options to measure test executition times, find out which tests are slow and refactor them.
Time option¶
--time
will measure how much time is needed to execute each test class.
Detailed option¶
--time --detailed
will measure how much time is needed to execute each test class and each single test.
Examples¶
Here’s a couple of examples:
# general measurement
./runtests.py --keepdb --time
# detailed measurement
./runtests.py --keepdb --time --detailed
# detailed measurement for a specific test class
python manage.py test --keepdb --time --detailed nodeshot.core.nodes
How to build the documentation¶
Building the documentation locally is useful for several reasons:
- you can read it offline
- you can edit it locally
- you can preview the changes locally before sending any pull request
So let’s build the docs!
Install sphinx:
workon nodeshot
pip install sphinx
Do a cd
into the /docs
dir:
cd /[PATH-TO-NODESHOT-REPO]/docs
Now build the docs with:
make html
Quite some html files have been created, you can browse those HTML files in a web browser and it should work.
The format used in the docs is reStructured Text while the python package used is python-sphinx.
Contribute¶
If you intend to contribute to nodeshot, be sure to read How to contribute to nodeshot.