Flask Autodeploy

Website deployment and server configuration can be a rather unrewarding task. To save you the trouble of configuring your Python applications to run on Apache, we put together a script to do the dirty work for you. If you follow the instructions below, you should have your Flask application up and running in no time

Overview

1. Take a look at the example we included in the handoutcode repository. If you haven't pulled the handoutcode yet, cd to your project directory and run:

   git pull handoutcode master

   There should be a folder called "Flask_example" containing a single file called "main.py." Notice that the "main.py" file defines a variable called "app" which is assigned to a Flask application object. This is the entry point to the web application.
2. Now, let's try deploying the application to the 6.170 server. All you have to do is push your repository to the remote branch called "deploy_only"

   git add .
   git commit -a -m "first deploy"
   git push origin dev:deploy_only

3. Now, browse to your deploy url at https://courses.csail.mit.edu/6.170/sp12/students/ and navigate to the folder called Flask_example. Click on the file called "index.fcgi" to launch the web application.
4. If all goes well, you should see the line "Hello World! I'm a Flask example."

Using databases

• Because of the way AFS permissions work, all of your database files must be located in the folder named "db." For example, the path to a database for assignment 4 would look something like this:

  MY_REPO/assignment4/db/mydatabase.db

• When you access the database file in your Python application, do not hard-code the absolute path to the file. For example, don't do this:

  DATABASE = "/home/me/Documents/6170_code/assignment4/db/mydatabase.db"

  The previous code will obviously break if you choose to move your project to a different folder. Instead, do something like this:

  DATABASE = os.path.join(os.path.dirname(__file__),"db","mydatabase.db")

  This command calculates the absolute path to "mydatabase.db" given the absolute path to your main Python file.

Extra Tips

• Note, your website is also automatically deployed whenever you push to the submit branch:

  git push origin dev:submit

• We run python 2.5 and Flask 0.9 on our server. Note that certain python commands do not work in version 2.5. Please contact us if you need additional python modules installed.
• The server loads the your application using the command "from main import app". This means that your project should define the "app" object in a file called "main.py," or alternatively create a python module called "main" with the "app" variable defined in the "__init__.py" file. The server will complain if it cannot find the entry point to your application.
• Remember to set the debug flag if you want to see the errors in your python code:

  app.debug = True

• Unless you give us a different URL in the user manual of your project, we will use the auto-deployed version of your website when we grade the user interface and functionality of your website.

Behind the scenes

What is happening behind the scenes? When you run your web application from your laptop (or desktop), Flask automatically creates a lightweight "test server" on your computer which listens for requests on a specific port on your computer. On a large shared server such as courses.csail.mit.edu, however, we don't have convenience of spawning new test servers on different ports.

In one way or another, Apache must associate a specific URL with your Python application. A naive solution would simply invoke your Python application every time a client requests that specific url. However, this would mean that the server would have to initialize a Python environment and load your code on every single web request. This is certainly not a very scalable solution.

Instead, Apache only loads the Python environment during the very first web request by essentially spawning a new, separate process to house your web application. Though the first request may be slow, subsequent requests are quick because the application has already been loaded into RAM.

The "index.fcgi" file which the autodeploy script added to your project tells Apache where to find the entry point to your application. It additionally wraps your application in a middleware which prints pretty error messages whenever your application crashes.

However, what exactly is the Flask application, and how does Apache know how to use it? In fact, Python developers have settled on a convention called the "WSGI" application which provides a simple interface for communication between the web server (Apache) and your web application. This modular design makes it easy, for example, to wrap web applications in extra functionality very much the same way that Python function decorators add functionality to regular Python functions. If you want to learn more, you can read about it here.