Running and Debugging Tropofy Apps

After Tropofy is installed, there are two steps to creating and running a Tropofy App.

  1. Run tropofy quickstart to create your App from an example.

Whenever you want to run tropofy you will have to activate the virtual environment you created when installing Tropofy (assumed to be tropofy_env below). If you don’t, the command tropofy quickstart will not work.

On a Windows system:

> tropofy_env\Scripts\activate
> tropofy quickstart tropofy_facility_location
> cd tropofy_facility_location
> notepad config.py  # Insert your keys
> python setup.py develop
> tropofy app -c config.py

On a Unix system:

$ source tropofy_env/bin/activate
$ tropofy quickstart tropofy_facility_location
$ cd tropofy_facility_location
$ nano config.py  # Insert your keys
$ python setup.py develop
$ tropofy app -c config.py

Now visit http://localhost:8080 in your favourite browser to see the facility location example app running live on your local compute node.

Note

Behind a proxy?

In most corporate environments you will access the internet through a proxy. This may cause issues when your local compute node attempts to contact the Tropofy servers. To get around this, create an environment variable with your proxy details as follows (you may have to contact your IT department to get proxy details and authentication info):

On a Windows system:

c:\> setx HTTP_PROXY http://user:pass@proxyAddress:proxyPort

On a Unix system:

$ export HTTP_PROXY=http://user:pass@proxyAddress:proxyPort
# Add this line to the end of ~/.bashrc to remember this setting outside of the terminal instance.

Now try and run Tropofy again. If problems persist, contact us at info@tropofy.com.

tropofy quickstart

tropofy quickstart creates a project directory on your machine, and copies an example App into it.

$ tropofy quickstart tropofy_facility_location

The above example installs the tropofy_facility_location app. To list all available example apps, run:

$ tropofy quickstart --list

Running your app

tropofy app -c config.py launches the App it finds within the project directory using the Tropofy Framework. If your machine is not connected to the web, or your keys specified within config.py are invalid, your App will not load correctly.

$ tropofy app -c config.py

After running the command you need to open your browser and navigate to http://localhost:8080 to log in and view your app. When you make a change to your app, you need to kill it using ctrl+c and run it again, go back to your browser and refresh it (F5) to view your changes.

Database management

Tropofy creates a database for each App, this is stored as a file in the project directory. Frequently when you are developing your app you will change the SQLAlchemy derived python classes, this may cause an error when running your app.

On a Windows system:

c:\> del <app_name>.db

On a Unix system:

$ rm <app_name>.db

This is useful when your app is under development and your data model is changing frequently. The Tropofy framework will recreate your database according to your new data model. If you use example data, getting the data back into you app while developing should not be a problem.

Note

Tropofy uses SQLite <https://www.sqlite.org/>_ to automate the database set up process for developers. SQLite <https://www.sqlite.org/>_ is a fantastic database for local development, however for production deployments we recomend PostgreSQL <https://www.postgresql.org/>_

Running and Debugging using PyCharm

Pycharm is an excellent IDE (integrated development environment) for Python. It is simple to setup, and available on Windows, Max OS X, and Linux. Furthermore, a free community edition is available which enables an excellent Tropofy development environment - including running and debugging apps. Using an IDE such as PyCharm, it is simple to set ‘break points’ in your Python code which allow you to pause program execution and step through code.

Running and Debugging using the command line or shell

The simplest and quickest way to run and debug a Tropofy App is through the console. Tropofy aims to provide meaningful error messages such that when a problem occurs, an explanation will be given in the console from which you can often fix the problem. Of course, this won’t always be enough and it is strongly recommended that you read about the other debugging techniques on this page.

Key points for console debugging:

  • To stop an app: ctrl+c, then enter, from the command line or shell.
  • If an error occurs, read the bottom few lines of the console output - it will often give you a good idea of what went wrong.
  • Print debugging: print <python code which returns a string> will output text to the console which may be used to debug.
  • If you press the up arrow key in the console the last command can easily be re-run.

You can use print statements in your Tropofy app to aid in development, and they will appear in the console as the app is running.

Running and Debugging using pdb

When writing any Python code, you have access to The Python Debugger (pdb). This allows you to enter a line of code, which will cause your code to stop when hit. You then have a range of debugging options available to you while the code is stopped.

Key points for pdb debugging:

  • Insert the line import pdb; pdb.set_trace() anywhere in your Python code to create a ‘break point’.
  • Run your code normally (using tropofy app -c config.py), and when the pdb line is hit, your code will stop in the console.
  • You can now enter Python code to debug the app in its current state i.e. access the value of variables etc
  • To stop debugging and let the code continue: c, then enter
  • To step over the current line of code: n, then enter.
  • For a full list of commands see the docs

Downsides of pdb debugging:

  • You must change your source code to insert break points (unlike an IDE like PyCharm, or Eclipse with PyDev)
  • It is hard to see your code while debugging: only the line of code beneath the pdb line is visible by default.

Note: pdbpp is an excellent extension of pdb which gives code visibility and highlighting while debugging as well as many more features focused on ease of use of pdb.