General installation

As with the demo site, we recommend installing Atramhasis in a virtual environment.

$ mkvirtualenv atramhasis_dev

To install a fully working development environment a pip requirements-dev.txt file is provided. By passing this file to pip install -r all requirements for Atramhasis and development of the software (Sphinx, py.test, tox) will be installed.

The following step will help you get the python development environment up and running. If also need to work on the javascript admin backend, please refer to the admin module documentation.

# Install dependencies
$ pip install -r requirements-dev.txt
# create or update database
$ alembic upgrade head
# insert sample data
$ initialize_atramhasis_db development.ini
# compile the Message Catalog Files
$ python compile_catalog

Once you’ve executed these steps, you can run a development server. This uses the standard pyramid server (Waitress) and should not be used as-is in a production environment.

# run a local development server
$ pserve --reload development.ini

Admin development

To work on the admin part, you’ll need npm and bower installed. Consult your operating system documentation on how to install these. The following instructions will assume you’re running a recent Debian based Linux distribution.

# install npm, bower and grunt-cli
$ sudo apt-get install nodejs
$ sudo apt-get install npm
$ sudo npm install -g bower grunt-cli
# install js dependencies using bower
$ cd atramhasis/static/admin
$ bower install
# install dojo build tools
$ npm install

These commands will install a couple of js libraries that Atramhasis uses in /atramhasis/static/admin/src and a set of tools to be able to generate js builds. Builds are carried out through a simple grunt file:

# Build a dojo distribution
$ cd atramhasis/static/admin
$ grunt -v build

This will create a build a place the resulting files in atramhasis/static/admin/dist. The web application can be told to use this build by setting dojo.mode in development.ini to dist.


Atramhasis is being developed as open source software by the Flanders Heritage Agency. All development is done on the agency’s Github page for Atramhasis.

Since we place a lot of importance of code quality, we expect to have a good amount of code coverage present and run frequent unit tests. All commits and pull requests will be tested with Travis-ci. Code coverage is being monitored with Coveralls.

Locally you can run unit tests by using pytest or tox. Running pytest manually is good for running a distinct set of unit tests. For a full test run, tox is preferred since this can run the unit tests against multiple versions of python.

# Run unit tests for all environments
$ tox
# No coverage
$ py.test
# Coverage
$ py.test --cov atramhasis --cov-report term-missing
# Only run a subset of the tests
$ py.test atramhasis/tests/

Every pull request will be run through Travis-ci. When providing a pull request, please run the unit tests first and make sure they all pass. Please provide new unit tests to maintain 100% coverage. If you send us a pull request and this build doesn’t function, please correct the issue at hand or let us know why it’s not working.


For building a distribution use the prepare command before the distribution command. This will update the requirement files in the scaffolds.

$ python prepare sdist