Developer Guide

Installing

Prerequisites

Running

To set up a development environment you first need to install the development dependencies

$ pipenv install --dev

Then setup the database

$ pipenv run cli database create-dev

Finally you can start Hot Potato with

$ docker-compose up hotpotato-dev

Some changes, such as those to dependencies or the docker environment require rebuilding the container:

$ docker-compose up --build hotpotato-dev

Accessing the development site

Once the development site has started, the following web services are exposed to the host:

Service URL Default credentials
Hot Potato http://localhost:8000 test1@example.com/test_password1 and test2@example.com/test_password2
RabbitMQ console http://localhost:15672 hotpotato/hotpotato
Cockroach console http://localhost:8080 -

If these ports clash with other services on your system, you can override them with environment variables (see .env for the full list), like so:

$ COCKROACH_WEBUI_PORT=8081 docker-compose up hotpotato-dev

Running the test suite

$ pipenv run unit-test

Generating a new Migration Script

  1. Bring up a Hot Potato Docker Compose instance, using a clone of master so that the new migration is generated against the latest revision.
  2. Update the model in the code with the new changes.
  3. Run the following command to generate a new revision file:
$ pipenv run cli db migrate --message "<message>"
INFO  [alembic.runtime.migration] Context impl CockroachDBImpl.
INFO  [alembic.runtime.migration] Will assume transactional DDL.
...
INFO  [alembic.autogenerate.compare] Detected added table 'message_log'
...
  Generating /code/hotpotato/migrations/versions/{date}_{time}_{revision}_{message}.py ... done
  1. Modify the generated revision file so that it is consistent with the changes actually made. The migration script tries to remove database indexes which are in the database, but are not seen by Alembic in the database model due to a bug in the CockroachDB Alembic runtime. These changes should be removed from the upgrade and downgrade functions.
  2. Add the newly generated migration script into the /hotpotato/migrations/versions folder of your branch, so that it gets pushed into master with the database changes.

Writing & Generating Documentation

Documentation is generated by sphinx and written in a mix of markdown and restructured text.

To generate the documentation run:

$ pipenv run docs

API documentation uses the sphinx http module to provide structured http documentation.