Developer Guide

Contents

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 db 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

Pipenv commands

The Pipfile contains a number of commands that are useful during development.

Running unit tests

$ pipenv run unit-test

Running Robot tests

$ pipenv run robot-test

Running linters

$ pipenv run flake8 $ pipenv run black $ pipenv run isort

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.

Testing Provider Callbacks

Hot Potato uses callbacks from message delivery APIs like pushover to tell if a message has been read and/or acknowledged.

If you’re changing code that interacts with these it might be a good idea to manually test that they work as expected.

Establish a Tunnel A simple way to temporarily make the testing application public is to use ngrok.

WARNING: You should make sure there is no sensitive data on the instance before doing this and change the passwords of the test accounts and any others you created.

$ ngrok http 8000

Leave this command running for the duration of your testing.

Set the Application URL

This should give you a URL like https://12345678.ngrok.io. Open .env and change the line;

HOTPOTATO_HOTPOTATO_WEBUI_URL=localhost:8000

to:

HOTPOTATO_HOTPOTATO_WEBUI_URL=12345678.ngrok.io

Note: There is no protocol here! That’s set to http whether you like it or not.

Restart Hot Potato

A restart is required for configuration changes to take effect.

Adding or updating translations

Hot Potato uses flask-babelex to help translate the website into other languages. All translating is done by people. Original strings are saved in all_strings.pot Translations are kept in translations/language/LC_MESSAGES/messages.po Messages.mo is a compiled version of messages.po

To mark a string to be translated

Add gettext around string: gettext("my string") Then run: pipenv run gen-language

To compile Translations

Run: pipenv run compile-language

To add Translation language files

Run: pipenv run pybabel init -i hotpotato/language-support/all_strings.pot -d hotpotato/app/translations -l [language code] Replace [language code] with a language code e.g. en

Update translation language files

Run: pipenv run update-language This will update .po files from all_strings.pot Then compile translations (see above)

Translations are stored in app/translations.