Flask By Example

For our Hello World application, we only need the Python Flask package, but we'll install several Python packages throughout the development process of our three applications. To manage these packages, we'll use the Python package manager pip. If you've developed in Python without a package manager until now, you'll love how easy it is to download, install, remove, and update packages using pip. If you already use it, then skip to the next step where we'll use it to install Flask.

The pip manager is included in Python's 3.4+ and 2.7.9+ versions. For older versions of Python, pip needs to be installed. To install pip on Ubuntu, open a terminal and run the following command:

sudo apt-get update
sudo apt-get install python-pip

That's it! You can now easily install any Python package you need through pip.

Installing Flask through pip could not be more straightforward. Simply run the following:

pip install –-user flask

You might see some warnings in your terminal, but at the end, you should also see Successfully installed Flask. Now, you can import Flask into a Python program just as with any other library.

Our application will be a single Python file. Create a directory in your home directory called firstapp and a file inside this called hello.py. In the hello.py file, we'll write code to serve a web page comprising the static string "Hello, World!". The code looks as follows:

from flask import Flask

app = Flask(__name__)

@app.route("/")
def index():
    return "Hello, World!"

if __name__ == '__main__':
    app.run(port=5000, debug=True)

Let's break down what this does. The first line should be familiar; it simply imports Flask from the package flask. The second line creates an instance of the Flask object using our module's name as a parameter. Flask uses this to resolve resources, and in complex cases, one can use something other than __name__ here. For our purposes, we'll always use __name__, which links our module to the Flask object.

Line 3 is a Python decorator. Flask uses decorators for URL routing, so this line of code means that the function directly below it should be called whenever a user visits the main root page of our web application (which is defined by the single forward slash). If you are not familiar with decorators, these are beautiful Python shortcuts that seem a bit like black magic at first. In essence, they call a function that takes the function defined under the decorator (in our case, index()) and returns a modified function.

The next two lines should also seem familiar. They define a very simple function that returns our message. As this function is called by Flask when a user visits our application, the return value of this will be what is sent in response to a user who requests our landing page.

Line 6 is a Python idiom with which you are probably familiar. This is a simple conditional statement that evaluates to True if our application is run directly. It is used to prevent Python scripts from being unintentionally run when they are imported into other Python files.

The final line kicks off Flask's development server on our local machine. We set it to run on port 5000 (we'll use port 80 for production) and set debug to True, which will help us see detailed errors directly in our web browser.

To run our development web server, simply fire up a terminal and run the hello.py file. If you used the same structure outlined in the previous section, the commands will be as follows:

cd firstapp/hello
python hello.py

You should get an output similar to that in the following screenshot:

Also, you should see the process continue to run. This is our web server listening for requests. So, let's make a request!

Fire up a web browser—I use Firefox, which comes packaged with Ubuntu—and navigate to localhost:5000.

The localhost part of the URL is a shortcut to the loopback address, usually 127.0.0.1, which asks your computer to make the web request to itself. The number after the colon (5000) is the port it should make the request to. By default, all HTTP (web) traffic is carried over port 80. For now, we'll use 5000 as it is unlikely to conflict with any existing services, but we'll change over to port 80 in production, which is conventional, so that you won't have to worry about the colon.

You should see the "Hello, World!" string displayed in your browser as in the following screenshot. Congratulations, you've built your first web application using Flask!

Although you could, in theory, host your web application on your local machine and allow others to use it, this has some severe limitations. First of all, every time you turned off your computer, your app would not be available. Also, your computer probably connects to the Internet via an Internet Service Provider (ISP) and possibly a wireless router. This means that your IP address is dynamic and changes regularly, which makes it difficult for your applications' users to keep up! Finally, chances are that you have an asymmetrical connection to the Internet, which means that your upload speed is slower than your download speed.

Hosting your application on a server solves all of these problems. Before "the cloud" became popular, the traditional way to host a web application was to buy a physical server and find a data center to host it. These days, things are far simpler. In a few minutes, you can fire up a virtual server, which to you seems just like a physical server—you can log in to it, configure it, and enjoy full control over it—but it is actually just a virtual "piece" of a machine owned and controlled by a cloud provider.

At the time of writing, major players in the cloud provider field include Amazon Web Services, Microsoft Azure, Google Cloud Compute, and Digital Ocean. All of these companies allow you to hire a virtual server or servers upon paying by the hour. If you are learning Flask as a hobby and are unwilling to pay anyone to host your web applications, you'll probably find a free trial at one of the providers quite easily. The smallest offering by any provider is fine to host all the applications that we'll run.

Select one of the preceding providers or another of your choosing. If you've never done anything similar before, Digital Ocean is often cited to have the simplest process of signing up and creating a new machine. Once you select a provider, you should be able to follow their respective instructions to fire up a VPS that runs Ubuntu Server 14.04 and SSH into it. You'll have full control over the machine with one slight difference: you won't have a display or a mouse.

You'll enter commands on your local terminal, which will in fact be run on the remote machine. Detailed instructions on how to connect to your VPS will be given by the provider, but if you use Ubuntu, it should be as simple as running the following:

ssh user@123.456.789.000

Alternatively, if you set it up with a public-private key authentication, where yourkey.pem is the full path to your private key file, here's the command to run:

ssh user@123.456.78.000 –i yourkey.pem

Here, user is the default user on the VPS, and yourkey is the name of your private key file.

SSH from other operating systems:

Once we connect to the VPS, installing Flask is the same process as it was previously:

sudo apt-get update
sudo apt-get install python-pip
pip install --user Flask

To install our web server, Apache, and WSGI, we will run the following:

sudo apt-get install apache2
sudo apt-get install libapache2-mod-wsgi

Apache is our web server. It will listen for web requests (which are generated by our users visiting our web application using their browsers) and hand these requests over to our Flask application. As our application is in Python, we also need WSGI (Web Server Gateway Interface).

This is a common interface between web servers and Python applications, which allows Apache to talk to Flask and vice versa. An overview of the architecture can be seen in the following diagram:

Now that we've installed Apache, we can see our first results. You're probably used to visiting websites using a URL, such as http://example.com. We'll access our web applications using the IP address of our VPS directly. Your VPS should have a static public address. Static means that it doesn't change periodically, and public means that it is globally unique. When you connected to the VPS via SSH, you probably used the public IP to do this. If you can't find it, run the following on your VPS and you should see an inet addr section in the output, which contains your public IP:

ifconfig

The IP address should look similar to 123.456.78.9. Enter your IP address into your browser's address bar, and you should see a page saying "Apache2 Ubuntu Default Page: It Works!" or something similar, as in the following screenshot:

This means that we can now serve web content to anyone with an Internet connection! However, we still have to:

For the first step, we'll set up a Git repository on our local machine and clone the repository to the VPS. For the second step, we'll use the WSGI module that we installed with Apache. Finally, we'll take a look at how to write a virtual host to have Apache serve our Flask application by default.

Git is a version control system. A version control system, among other things, saves multiple versions of our code base automatically. This is great to undo accidental changes or even deletions; we can simply revert to a previous version of our code. It also includes lots of functionality for distributed development—that is, many developers working on a single project. We'll use it mainly for its backup and deployment features, however.

To install Git on your local machine and VPS, run the following commands on each:

sudo apt-get update
sudo apt-get install git

Now that you have the software, you need a place to host your Git repositories or "repos". Two popular and free Git hosting services are GitHub (http://github.com) and Bitbucket (http://bitbucket.org). Head over to one of them, create an account, and create a new repository by following the instructions that they provide. When given the option to give your repository a name, call it firstapp to match the name of the directory that we will use for our code base. Once you create a new repository, you should be given a unique URL to your repository. Take note of this as we'll use it to push our Hello, World! application using git and then deploy it to our VPS.

On your local machine, open a terminal and change the directory to the Flask application. Initialize a new repository and link it to your remote Git repository via the following commands:

cd firstapp
git init
git remote add origin <your-git-url>

Tell git who you are, to allow it to automatically add metadata to your code changes, as follows:

git config --global user.email "you@example.com"
git config --global user.name "Your Name"

Git allows you full control over which files are part of your repository and which aren't. Even though we initialized the Git repo in our firstapp directory, our repo currently contains no files. Add our application to the repo, commit, and then push it, as follows:

git add hello.py
git commit -m "Initial commit"
git push -u origin master

These are the main Git commands that we'll use throughout this book, so let's take a brief look at what each does. The add command adds new or modified files to our repository. This tells Git which files are actually part of our project. Think of the commit command as taking a snapshot of our project in its current state. This snapshot is saved on our local machine. It is good to make a new commit with any major change to the code base as we can easily revert to previous commits if a later commit breaks our application. Finally, the push command pushes our local changes to the remote Git server. This is good for backup, and it will also allow us to fetch the changes on our VPS, thus keeping the code base on our local machine and that on our VPS in sync.

Now, SSH into your VPS again and get a copy of our code, as follows:

cd /var/www
git clone <your-git-url>

If you get a permission denied error on trying to clone the Git repository, you might need to take ownership of the /var/www directory for the Linux user that you're using. If you logged into the server with tom@123.456.789.123, you can run the following command, which will give your user ownership of /var/www and allow you to clone the Git repository into it. Again tom is the placeholder used in the following case:

sudo chown -R tom /var/www

If you used firstapp as a name for your remote repository, this should create a new directory called firstapp. Let's verify that our code is there using the following:

cd firstapp
ls

You should see your hello.py file. Now, we need to configure Apache to use WSGI.

First, we'll create a very straightforward .wsgi file in our application directory. Then, we'll create an Apache configuration file in the directory where Apache looks for available sites.

The only slightly tricky part about these two steps is that we'll create the files directly on our VPS, and as our VPS does not have a display, this means that we have to use command-line interface text editors. Of course, we could create the files locally and then transfer them to our VPS as we did for our code base, but for small changes to configuration files, this is often more effort than it's worth. Using a text editor without a mouse takes a bit of getting used to, but it's a good skill to learn. The default text editor on Ubuntu is Nano, and the other popular choices are vi or Vim. Some people use Emacs. If you already have a favorite, go with it. If not, we'll use Nano for the examples in this book (it is already installed and arguably the simplest to use). However, if you want to go the extra mile, I recommend learning to use Vim.

Assuming you're still connected to your VPS and have navigated to the /var/www/firstapp directory as in the most recent steps, run the following command:

nano hello.wsgi

This creates the hello.wsgi file, which you can now edit through Nano. Type the following:

import sys
sys.path.insert(0, "/var/www/firstapp")
from hello import app as application

This is simply Python syntax, which patches our application into the PATH system so that Apache can find it through WSGI. We will then import app (we named this in our hello.py app with the app = Flask(__name__) line) into the namespace.

Hit Ctrl + X to exit Nano and enter Y when prompted to save the changes.

Now, we'll create an Apache configuration file that points to the .wsgi file we just created, as follows:

cd /etc/apache2/sites-available
nano hello.conf

In this file, we'll create a configuration for an Apache virtual host. This will allow us to serve multiple sites from a single server, which will be useful later when we want to serve other applications using our single VPS. In Nano, enter the following configuration:

<VirtualHost *>
    ServerName example.com

    WSGIScriptAlias / /var/www/firstapp/hello.wsgi
    WSGIDaemonProcess hello
    <Directory /var/www/firstapp>
       WSGIProcessGroup hello
       WSGIApplicationGroup %{GLOBAL}
        Order deny,allow
        Allow from all
    </Directory>
</VirtualHost>

This might look quite complicated, but it's actually very straightforward. We will create a virtualhost and specify our domain name, where our .wsgi script is, the name of our application, and who is allowed to access it. We'll discuss domain names in the final chapter, but for now, you can just leave it as example.com because we'll access our application by its IP address.

Hit Ctrl + X and enter Y when prompted again to save and exit the file. Now, we need to enable the configuration and set it as our default site.

Configuring Apache to serve our Flask application

Apache sites work as follows: there is a sites-available directory (where we created the new virtual host configuration file) and a sites-enabled directory, which contains shortcuts to all the configuration files that we want to be active. By default, you'll see a file in the sites-available directory named 000-default.conf. This is the reason that we saw a default It works Apache page when we first installed Apache. We don't want this anymore; instead, we want to use our application as the default site. Therefore, we'll disable the default Apache site, enable our own, and then restart Apache for the changes to take effect. Run these commands to do this:

sudo a2dissite 000-default.conf
sudo a2ensite hello.conf
sudo service apache2 reload

Note

The required Apache configuration and commands can vary quite a bit based on the platform you're using. If you use Ubuntu Server as recommended, the preceding should all work smoothly. If not, you may need to read up a bit on how to configure Apache for your specific platform.

You should note reloading web server apache2 in the output. If errors are displayed, then you probably misconfigured something in the preceding command. If this is the case, read the error message carefully and go back over the previous steps to take a look at why things didn't work as expected.

To test that everything is working, open a web browser on your local machine and type your IP address into the address bar again. You should see Hello, World! displayed in your browser instead of the default Apache page that we saw before.

If you get Error 500 instead, it means that our application fell over for some reason. Fear not; it's better that you get used to dealing with this error now, when the fix will probably be simple, than later on, when we've added more components that could break or be misconfigured. To find out what went wrong, run the following command on your VPS:

sudo tail –f /var/log/apache2/error.log

The tail command simply outputs the last several lines of the file passed as an argument. The -f is for follow, which means that the output will be updated if the file changes. If you can't immediately work out which lines are indicative of the error we're looking for, visit the site in your web browser on your local machine again, and you'll see the output from the tail command be updated accordingly. The following screenshot shows the output from the tail command when there are no errors; however, if anything goes wrong, you'll see the error output printed among all the info messages.

Some possible tripping points are incorrectly configured WSGI and Apache files (make sure that your WSGIDaemonProcess and daemon name match, for example) or incorrectly configured Python (you may forget to install Flask on your VPS). If you can't figure out what the error message means, an Internet search for the message (removing the error-specific parts of your app, such as names and paths) will usually point you in the right direction. Failing this, there are strong and very friendly Flask and WSGI communities on Stack Overflow and Google Groups, and there's normally someone willing to help beginners. Remember that if you're having a problem and can't find an existing solution online, don't feel bad for asking; you'll help countless people facing issues similar to yours.