Deploy to Heroku

An LTI provider must run on a server accessible by your LTI consumer. This documentation assumes your LTI consumer is edX, but the principle is the same for other LTI consumers.

Heroku is a popular hosting service that offers free deployment for low volume applications and a sliding pricing model for higher demand applications. For the purpose of documentation we will use Heroku as our deployment target though you may deploy to any host or hosting service you choose.

The following steps have these prerequisites:

• you have cloned the mit_lti_flask_sample to your development machine
• you can open a terminal window and navigate to the cloned sample code
• you have installed the git command line tool, or some other git client.

Note

The following steps presume that you have a collection of command line utilities installed on your machine. These utilities are installed by default on Linux machines, and freely available for OSX. This link will guide you to resources for your operation system: Command Line Tools

Heroku Deployment

The documentation that Heroku provides for preparing your machine and installing required software is excellent. Start there by getting a Heroku account and following the Python track of their tutorial.

1. Sign up for a free account by navigating to https://www.heroku.com. If you already have an account, navigate to https://devcenter.heroku.com/articles/getting-started-with-python#introduction to proceed with the Heroku tutorial.
2. Once you have an account, the Heroku site will guide you to install the Heroku Toolbelt and upload your SSH keypair. Your SSH keypair authenticates you to Heroku. If you don’t have a SSH keypair, Heroku provides a link on that page to help you create one.
3. The next step of the Heroku tutorial, “Prepare the app”, presumes you don’t have an app to deploy, but you do. Before continuing with the Heroku tutorial, let’s first confirm that your app will run in the Heroku environment. Do this by using an application installed as part of the Heroku Toolbelt.
4. In your terminal window, navigate to the file system directory that contains the sample application you cloned earlier. If you haven’t cloned the sample app to a local directory, see this guide Tutorial: Using the Sample LTI provider in edX.)
5. Heroku provides a development server called foreman as part of its “Heroku Toolbelt”. (You should have installed the “Toolbelt” in the ‘Introduction’ step of the Heroku ‘getting started’ process.) Foreman allows you to simulate the Heroku runtime environment locally; very handy to help you verify that your app will run once deployed. You can run your app with this terminal command:

foreman start

6. Once your app starts, navigate to http://localhost:5000/is_up to confirm that the app is working. The page will display the text “I’m up” if the app is working properly. To terminate the app, type Cntl-C in the terminal.
7. Now that you know that your app will run in the Heroku environment, your next step is to deploy your app to Heroku. Proceed to the “Deploy the app” step in the Heroku tutorial.Use the create command to deploy your app:

heroku create
Creating salty-tundra-1591... done, stack is cedar-14
https://salty-tundra-1591.herokuapp.com/ | git@heroku.com:salty-tundra-1591.git

The create command returns useful information. It indicates

• success or failure,
• the Heroku platform stack that your app runs in,
• the URL for your deployed app on Heroku (In this case, https://salty-tundra-1591.herokuapp.com/)
• the Git URL for your Git repository on Heroku (In this case, git@heroku.com:salty-tundra-1591.git)

You can now use the URL of your deployed app on Heroku to test the sample against your edX course.

Additional Heroku Configuration

We recommend not storing secrets inside the git repository such as the OAuth keys needed for LTI security. As a result, we have instrumented the config.py file to have an example of using environment variables to store these secrets.

For example:

# secret key for authentication
SECRET_KEY = os.environ.get("FLASK_SECRET_KEY", "you-will-never-guess")
CONSUMER_KEY_PEM_FILE = os.path.abspath('consumer_key.pem')
with open(CONSUMER_KEY_PEM_FILE, 'w') as wfile:
    wfile.write(os.environ.get('CONSUMER_KEY_CERT', ''))

PYLTI_CONFIG = {
        "consumers": {
                "__consumer_key__": {
                        "secret": os.environ.get("CONSUMER_KEY_SECRET", "__lti_secret__"),
                        "cert": CONSUMER_KEY_PEM_FILE
                }
        }
}

Now it is attempting to get the FLASK_SECRET_KEY, the CONSUMER_KEY_CERT and CONSUMER_KEY_SECRET environment variable values for the actual secrets. To do this in Heroku you can set these variables with the heroku config commands. To set the flask secret to pink_unicorns and __consumer_key__ secret to horn_of_plenty you would run:

heroku config:set FLASK_SECRET_KEY=pink_unicorn CONSUMER_KEY_SECRET=horn_of_plenty

To check your configuration, you can run heroku config by itself, and it will show what environment variables are set for your application.

To replicate the secure configuration locally using foreman you can create a file in the root of the application at .env that contains K=V values for configuration. i.e.

FLASK_SECRET_KEY=pink_unicorn
CONSUMER_KEY_SECRET=horn_of_plenty

Note

Environment variables can be absolutely huge, so there is no problem storing full client SSL certificates in the CONSUMER_KEY_PEM_FILE if your application requires client certificates in addition to the OAuth scheme. config.py above, for example, reads the environment variable the SSL certificate and key and writes it out to a file for use by httplib during execution on Heroku.

Note

Developers whose LTI app will be consumed by MITx will need an application certificate issued by MIT IS&T to be able to send grades to edX. You can request an application certificate by following the instructions at this support page https://wikis.mit.edu/confluence/display/devtools/How+to+acquire+and+verify+a+x509+Application+Certificate

Files added for Heroku Support

The items described below are in the sample solely to support Heroku deployment. If you don’t deploy to Heroku, you can ignore or remove them.

Procfile

Heroku requires a text file named Procfile to reside in the application’s root directory. Heroku documents the contents of the Procfile here: https://devcenter.heroku.com/articles/procfile

runtime.txt

Heroku uses the contents of runtime.txt to pin a specific version of the Python runtime to a specific version. The app has been tested with the Python runtime version found in the file.