Basic Server Setup (Heroku)¶

Heroku is a commercial cloud hosting provider. If you are not experienced with web server administration, Heroku may be the simplest option for you.

The Heroku free plan is sufficient for small-scale testing of your app, but once you are ready to launch a study, you should upgrade to a paid server, which can handle more traffic.

Basic Heroku setup¶

Create an account¶

Create an account on Heroku. Select Python as your main language. However, you can skip the “Getting Started With Python” guide.

Install the Heroku Toolbelt¶

Install the Heroku Toolbelt.

This provides you access to the Heroku Command Line utility.

Once installed open PowerShell (Windows) or Terminal (Mac), and go to your project folder.

Log in using the email address and password you used when creating your Heroku account:

$ heroku login

If the heroku command is not found, close and reopen your command prompt.

Initialize your Git repo¶

If you haven’t already initialized a git repository run this command from your project’s root directory:

git init

Create the Heroku app¶

Create an app on Heroku, which prepares Heroku to receive your source code:

$ heroku create
Creating lit-bastion-5032 in organization heroku... done, stack is cedar-14
http://lit-bastion-5032.herokuapp.com/ | https://git.heroku.com/lit-bastion-5032.git
Git remote heroku added

When you create an app, a git remote (called heroku) is also created and associated with your local git repository.

Heroku generates a random name (in this case lit-bastion-5032) for your app. Or you can specify your own name; see heroku help create for more info. (And see heroku help for general help.)

Install Redis add-on¶

You need to install Heroku’s Redis add-on.

If you don’t do it, you will see an “Application Error”:

If Redis is not set up, you may also see messages in your heroku logs saying “Connection refused”, or an error mentioning port 6379. After adding Redis, if it’s still not working, you may need to wait for a few minutes, or restart with heroku restart.

Upgrade oTree¶

We recommend you upgrade to the latest version of oTree, to get the latest bugfixes. Run:

$ pip3 install -U otree-core

Save to requirements_base.txt¶

The above command will just upgrade otree-core locally. It will not affect what version is installed on your server.

You need to create a list of all the Python modules you have installed (including otree-core), and save it to the file in your project’s root directory called requirements_base.txt. Heroku will read this file and install the same version of each library on your server.

If using Windows PowerShell, enter:

pip3 freeze | out-file -enc ascii requirements_base.txt

Otherwise, enter:

pip3 freeze > requirements_base.txt

Open the file requirements_base.txt and have a look, especially for the line that says otree-core=x.x.x This is the version that will be installed on your server.

Side note about requirements¶

Technically, requirements_base.txt only needs to contain the lines for otree-core and Django. There are many other packages listed there (e.g. asgi-redis, channels), but they are automatically installed if you install otree-core. Still, it’s generally good to use the output of pip freeze. There should be about 40-50 items listed when you do pip freeze, and it should look roughly similar (but not identical) to the this file. If you see far more items in your requirements_base.txt, you might have extra unnecessary packages, e.g. for other projects you were doing unrelated to oTree. This might happen if you are using Anaconda, which installs many scientific and numeric packages that might not install properly on Heroku.

Push your code to Heroku¶

Commit your changes (note the dot in git add .):

git add .
git commit -am "your commit message"

Transfer (push) the local repository to Heroku:

$ git push heroku master

Note

If you get a message push rejected and the error message says could not satisfy requirement, open requirements_base.txt and delete every line except the ones for Django and otree-core. The line for Django should say Django==1.8.8. See this note above.

Reset the oTree database on Heroku. You can get your app’s name by typing heroku apps.

$ heroku run otree resetdb

Open the site in your browser:

$ heroku open

(This command must be executed from the directory that contains your project.)

That’s it! You should be able to play your app online. If not, see the next section.

Troubleshooting¶

If your app fails to load, e.g. “application error”, try the following:

Use the command heroku logs to check the server logs for any error messages (or, better yet, enable Papertrail, which provides a nice UI for browsing logs).
Make sure you remembered to enable the Heroku Redis add-on (see here).
Run heroku run otree --version to check that you are using the latest version of otree-core on Heroku.

Making updates and modifications¶

When you make modifications to your app and want to push the updates to Heroku, enter:

git add .
git commit -am "my commit message"
git push heroku master
# next command only required if you added/removed a field in models.py
heroku run otree resetdb

You should also regularly update your requirements_base.txt.

Further steps with Heroku¶

Below are the steps you should take before launching a real study, or to further configure your server’s behavior.

Look at your server check¶

In the oTree admin interface, click “Server Check” in the header bar. It will tell you what steps below you need to take.

Turn on timeout worker Dyno¶

To enable full functionality, you should go to the Heroku Dashboard, click on your app, click to edit the dynos, and turn on the timeoutworker dyno.

Turning on the second dyno is free, but you may need to register a credit card with Heroku.

If you are just testing your app, oTree will still function without the timeoutworker dyno, but if you are running a study with real participants and your pages have timeouts defined by timeout_seconds, then the timeoutworker will ensure that timeouts are still enforced even if a user closes their browser.

If you do not see a timeoutworker entry, make sure your Procfile looks like this:

web: otree webandworkers
timeoutworker: otree timeoutworker

To add an existing remote:¶

If you previously created a Heroku app and want to link your local oTree git repository to that app, use this command:

$ heroku git:remote -a [myherokuapp]

Scaling up the server¶

The Heroku free plan is sufficient for small-scale testing of your app, but once you are ready to go live, you need to upgrade to a paid plan.

After you finish your experiment, you can scale your dynos and database back down, so then you don’t have to pay the full monthly cost.

Postgres (upgrade required)¶

You need to upgrade your Postgres database to a paid tier (at least the cheapest paid plan), because the free version can only store a small amount of data.

To provision the “Hobby Basic” database:

$ heroku addons:create heroku-postgresql:hobby-basic
Adding heroku-postgresql:hobby-basic to sushi... done, v69
Attached as HEROKU_POSTGRESQL_RED
Database has been created and is available

This command will give you the name of your new DB (in the above example, HEROKU_POSTGRESQL_RED). Then you need to promote (i.e. “activate”) this new database:

$ heroku pg:promote HEROKU_POSTGRESQL_RED  # substitute your color here
Promoting HEROKU_POSTGRESQL_RED_URL to DATABASE_URL... done

More info on the database plans here, and more technical documentation here.

After purchasing the upgraded Postgres, it’s recommended to delete the hobby-dev (free) database, to avoid accidentally using the wrong database.

Upgrade dynos¶

In the Heroku dashboard, click on your app’s “Resources” tab, and in the “dynos” section, select “Upgrade to Hobby”. Then select either “Hobby” or “Professional”.

You can also increase the number of web dynos, but if you do so, you may need to upgrade your Redis plan also, because more dynos means more Redis connections.

You should not increase the number of timeoutworker dynos.

Upgrade Redis (optional)¶

I have not seen any problems yet with the free version of Redis. However, if running a study, consider upgrading to the “Premium 0” Redis for $15/month, because it has a higher connection limit.

Setting environment variables¶

If you would like to turn off debug mode, you should set the OTREE_PRODUCTION environment variable, like this:

$ heroku config:set OTREE_PRODUCTION=1

However, this will hide error pages, so you should set up Logging with Sentry.

To password protect parts of the admin interface, you should set OTREE_AUTH_LEVEL):

$ heroku config:set OTREE_AUTH_LEVEL=DEMO

More info at Password protection.

Before launching a study, you should set up Sentry.

Testing with browser bots¶

Before launching a study, it’s advisable to test your apps with bots, especially browser bots. See the section Bots & automated testing.

Logging with Sentry¶

Whether or not you use Heroku, you should enter your email address (here) to sign up for our free Sentry service which can log all errors on your server and send you email notifications. (Sentry.)

Sentry is necessary because many errors are not visible in the UI after you turn off debug mode. You will no longer see Django’s yellow error pages; you or your users will just see generic “500 server error” pages:

After you enter your email, you will receive an email with information on how to activate Sentry in your project.

Logging with Papertrail¶

If using Heroku, we recommend installing the free “Papertrail” logging add-on:

heroku addons:create papertrail:choklad

Papertrail gives you an easy-to-use interface for exploring the Heroku server logs. It is much easier to use than running heroku logs.

(This is useful even if you are already using Sentry, because it shows different types of errors.)

Database backups¶

When running studies, it is your responsibility to back up your database.

In Heroku, you can set backups for your Postgres database. Go to your Heroku Dashboard, click on the “Heroku Postgres” tab, and then click “PG Backups”. More information is available here.