In this guide, we will be setting up a simple Python application using the Flask micro-framework on Ubuntu 14.04. The bulk of this article will be about how to set up the Gunicorn application server to launch the application and Nginx to act as a front end reverse proxy.
Before starting on this guide, you should have a non-root user configured on your server. This user needs to have sudo
privileges so that it can perform administrative functions. To learn how to set this up, follow our initial server setup guide.
To learn more about the WSGI specification that our application server will use to communicate with our Flask app, you can read the linked section of this guide. Understanding these concepts will make this guide easier to follow.
When you are ready to continue, read on.
Our first step will be to install all of the pieces that we need from the repositories. We will install pip
, the Python package manager, in order to install and manage our Python components. We will also get the Python development files needed to build some of the Gunicorn components. We’ll install Nginx now as well.
Update your local package index and then install the packages by typing:
sudo apt-get update
sudo apt-get install python-pip python-dev nginx
Next, we’ll set up a virtual environment in order to isolate our Flask application from the other Python files on the system.
Start by installing the virtualenv
package using pip
:
sudo pip install virtualenv
Now, we can make a parent directory for our Flask project. Move into the directory after you create it:
mkdir ~/myproject
cd ~/myproject
We can create a virtual environment to store our Flask project’s Python requirements by typing:
virtualenv myprojectenv
This will install a local copy of Python and pip
into a directory called myprojectenv
within your project directory.
Before we install applications within the virtual environment, we need to activate it. You can do so by typing:
source myprojectenv/bin/activate
Your prompt will change to indicate that you are now operating within the virtual environment. It will look something like this (myprojectenv)user@host:~/myproject$
.
Now that you are in your virtual environment, we can install Flask and Gunicorn and get started on designing our application:
We can use the local instance of pip
to install Flask and Gunicorn. Type the following commands to get these two components:
pip install gunicorn flask
Now that we have Flask available, we can create a simple application. Flask is a micro-framework. It does not include many of the tools that more full-featured frameworks might, and exists mainly as a module that you can import into your projects to assist you in initializing a web application.
While your application might be more complex, we’ll create our Flask app in a single file, which we will call myproject.py
:
nano ~/myproject/myproject.py
Within this file, we’ll place our application code. Basically, we need to import flask and instantiate a Flask object. We can use this to define the functions that should be run when a specific route is requested. We’ll call our Flask application in the code application
to replicate the examples you’d find in the WSGI specification:
This basically defines what content to present when the root domain is accessed. Save and close the file when you’re finished.
You can test your Flask app by typing:
python myproject.py
Visit your server’s domain name or IP address followed by the port number specified in the terminal output (most likely :5000
) in your web browser. You should see something like this:
When you are finished, hit CTRL-C in your terminal window a few times to stop the Flask development server.
Next, we’ll create a file that will serve as the entry point for our application. This will tell our Gunicorn server how to interact with the application.
We will call the file wsgi.py
:
nano ~/myproject/wsgi.py
The file is incredibly simple, we can simply import the Flask instance from our application and then run it:
Save and close the file when you are finished.
Before moving on, we should check that Gunicorn can correctly.
We can do this by simply passing it the name of our entry point. We’ll also specify the interface and port to bind to so that it will be started on a publicly available interface:
cd ~/myproject
gunicorn --bind 0.0.0.0:8000 wsgi
If you visit your server’s domain name or IP address with :8000
appended to the end in your web browser, you should see a page that looks like this:
When you have confirmed that it’s functioning properly, press CTRL-C in your terminal window.
We’re now done with our virtual environment, so we can deactivate it:
deactivate
Any operations now will be done to the system’s Python environment.
The next piece we need to take care of is the Upstart script. Creating an Upstart script will allow Ubuntu’s init system to automatically start Gunicorn and serve our Flask application whenever the server boots.
Create a script file ending with .conf
within the /etc/init
directory to begin:
sudo nano /etc/init/myproject.conf
Inside, we’ll start with a simple description of the script’s purpose. Immediately afterwards, we’ll define the conditions where this script will be started and stopped by the system. The normal system runtime numbers are 2, 3, 4, and 5, so we’ll tell it to start our script when the system reaches one of those runlevels. We’ll tell it to stop on any other runlevel (such as when the server is rebooting, shutting down, or in single-user mode):
description "Gunicorn application server running myproject"
start on runlevel [2345]
stop on runlevel [!2345]
We’ll tell the init system that it should restart the process if it ever fails. Next, we need to define the user and group that Gunicorn should be run as. Our project files are all owned by our own user account, so we will set ourselves as the user to run. The Nginx server runs under the www-data
group. We need Nginx to be able to read from and write to the socket file, so we’ll give this group ownership over the process:
description "Gunicorn application server running myproject"
start on runlevel [2345]
stop on runlevel [!2345]
respawn
setuid user
setgid www-data
Next, we need to set up the process so that it can correctly find our files and process them. We’ve installed all of our Python components into a virtual environment, so we need to set an environmental variable with this as our path. We also need to change to our project directory. Afterwards, we can simply call the Gunicorn application with the options we’d like to use.
We will tell it to start 3 worker processes (adjust this as necessary). We will also tell it to create and bind to a Unix socket file within our project directory called myproject.sock
. We’ll set a umask value of 007
so that the socket file is created giving access to the owner and group, while restricting other access. Finally, we need to pass in the WSGI entry point file name:
description "Gunicorn application server running myproject"
start on runlevel [2345]
stop on runlevel [!2345]
respawn
setuid user
setgid www-data
env PATH=/home/user/myproject/myprojectenv/bin
chdir /home/user/myproject
exec gunicorn --workers 3 --bind unix:myproject.sock -m 007 wsgi
Save and close the file when you are finished.
You can start the process immediately by typing:
sudo start myproject
Our Gunicorn application server should now be up and running, waiting for requests on the socket file in the project directory. We need to configure Nginx to pass web requests to that socket by making some small additions to its configuration file.
Begin by creating a new server block configuration file in Nginx’s sites-available
directory. We’ll simply call this myproject
to keep in line with the rest of the guide:
sudo nano /etc/nginx/sites-available/myproject
Open up a server block and tell Nginx to listen on the default port 80. We also need to tell it to use this block for requests for our server’s domain name or IP address:
server {
listen 80;
server_name server_domain_or_IP;
}
The only other thing that we need to add is a location block that matches every request. Within this block, we’ll include the proxy_params
file that specifies some general proxying parameters that need to be set. We’ll then pass the requests to the socket we defined using the proxy_pass
directive:
server {
listen 80;
server_name server_domain_or_IP;
location / {
include proxy_params;
proxy_pass http://unix:/home/user/myproject/myproject.sock;
}
}
That’s actually all we need to serve our application. Save and close the file when you’re finished.
To enable the Nginx server block configuration we’ve just created, link the file to the sites-enabled
directory:
sudo ln -s /etc/nginx/sites-available/myproject /etc/nginx/sites-enabled
With the file in that directory, we can test for syntax errors by typing:
sudo nginx -t
If this returns without indicating any issues, we can restart the Nginx process to read the our new config:
sudo service nginx restart
You should now be able to go to your server’s domain name or IP address in your web browser and see your application:
In this guide, we’ve created a simple Flask application within a Python virtual environment. We create a WSGI entry point so that any WSGI-capable application server can interface with it, and then configured the Gunicorn app server to provide this function. Afterwards, we created an Upstart script to automatically launch the application server on boot. We created an Nginx server block that passes web client traffic to the application server, relaying external requests.
Flask is a very simple, but extremely flexible framework meant to provide your applications with functionality without being too restrictive about structure and design. You can use the general stack described in this guide to serve the flask applications that you design.
Thanks for learning with the DigitalOcean Community. Check out our offerings for compute, storage, networking, and managed databases.
This textbox defaults to using Markdown to format your answer.
You can type !ref in this text area to quickly search our full set of tutorials, documentation & marketplace offerings and insert the link!
Don’t you need to activate the virtualenv in the upstart script before running gunicorn?
For this example, you don’t need to do that since we are specifying the PATH where all of the Python executables we care about are located. If this doesn’t suit your needs however, you can convert the
exec
line into ascript
block like this:With a little testing and tweaking, that should correctly load the virtual environment for you if the PATH isn’t enough to catch all of the things you need from your Virtual env. Hope that helps.
Nice tutorial. I’ve been wanting to understand how WSGI servers worked and also have a chance to try nginx and Flask. I recently learned Bottle and used CGI to serve my app through Apache. So this is like the modern way of doing everything I did earlier. Thanks for that!
When I try to run the “gunicorn --bind 0.0.0.0:8000 wsgi” I get a “Failed to find application : ‘wsgi’”. I’m in the same dir as wsgi.py file. Any ideas?
Thanks in advance!
I just had to figure out this same problem. Had to run the following command:
gunicorn --bind 0.0.0.0:8000 wsgi:app
Hope this works for you.
This works for me, but do you know why I had to add that specification to the command? It seems like the tutorial (implicitly anyway) worked fine without it, so I’m trying to see why it was necessary for my particular project/configuration.
Same here. I think the tutorial has incorrect syntax. At the very least, it’d be nice to include the alternative syntax:
gunicorn --bind 0.0.0.0:8000 wsgi:app
in the instructions.
Its because gunicorn looks for the variable “application” by default, not “app”
I’m having trouble accessing the app after initially configuring it any running the server with python myproject.py. The server is running (It says “Running on http://127.0.0.1:5000/ (Press CTRL+C to quit)”)
When I try to connect using my web browser to XX.XX.XXX.XX:5000, it gives me an unable to connect error. I’m going to continue through the tutorial to setting up gunicorn, and go from there, but what could I be doing wrong?
‘127.0.0.1’ is the address of ‘localhost’. This means when you have the application runtime bound to the localhost, only the local host device can access that application. If you were to run this application on your home desktop, you could open chrome and view the application. The application is hosted on your droplet, however, and you’re trying to access the application from your home desktop, which is not the local host.
To properly view this application, you will want to bind the application to 0.0.0.0:xxxx (any free port would work) and you would view the application by going IP_ADDRESS:xxxx. I presume, when you ran it with gunicorn (according to your updated comment below) you set the bind option as “–bind 0.0.0.0:5000”.
The “0.0.0.0” address means “no particular address” and, in the context of running applications on a server (the server being the localhost), further means run this application on all IPv4 addresses on the localhost.
Once I ran it with gunicorn, it worked.
Following the setup exactly, I get a 502 Bad Gateway error when going to my server IP address. Now I can access the page if I’m running the “gunicorn test:application -b 0.0.0.0:8000” and it loads fine.
I even followed the comment fixes by using the script section instead to activate the env with the right python settings. Still no go.
Has things changed since this was written?
@sudogaron: I just ran through the entire guide again, copying and pasting the commands and changing only the parts highlighted in red. I wasn’t able to reproduce your issues.
It sounds like you are having problems with the gunicorn process. Can you verify that the application server is actually running? Check the
/var/log/upstart/myproject.log
file. My guess is that your upstart init file has an issue.This happened to me too. I think it was because i had created a LAMP application with the Apache server interfering with NGinx. I created a new Ubuntu droplet without selecting the Lamp application and it works now.
Justin could you please help me with my setup? I have my python app running nginx and gunicorn successfully on windows azure. However, i have a website running on another instance on azure and would like my python app to be served through the website to show something like www.mywebsite.com/nameofmyapp/. I understand its got to do with proxies. Any guide? Thanks.
I get an error when I try to run “sudo start myproject”, saying “sudo: start: command not found”. How can I fix this? Thanks for the help!
@tomcek112: Upstart, Ubuntu’s init system on 14.04, comes with the
start
command to execute init scripts. If you do not have that command, either you are attempting to complete this tutorial on a different operating system or your Ubuntu 14.04 server is in a very unexpected state. Did you start this guide on a fresh Ubuntu 14.04 installation?First of all, tyvm for this tutorial. I’ve gotten further with it than any other in setting up Flask.
I’m having the same problem as @tomcek112. This is under Ubuntu 16.04, a fresh copy from AWS EC2. As a shot in the dark I tried
sudo apt-get start
without luck.Any suggestions?
@chivalry Hey there.
As the comment you responded to mentions, Ubuntu 14.04 uses the Upstart init system which includes the
start
command. If you’re running this on Ubuntu 16.04, that command will be unavailable because that release transitioned away from Upstart, replacing it with systemd. This guide won’t function as-is on Ubuntu 16.04 because of that.So to sort this out, you can either:
I hope that helps!
@jellingwood tyvm, I was actually looking at the 16.04 article when I noticed the reply. I’m about to try that out. :)
Strange, I don’t think you’ve done anything wrong. “Start” is a command that might be different on your machine or not installed by default. What are you running? Ubuntu, Debian?
For those who are getting timeouts at the first attempt to connect via port 5000 (or whatever is assigned), I got around the issue by adding that port to the ufw firewall, if you set it up per the initial server setup guide.
This may only help newcomers like myself, but I’m sure there are a few of us around.
I got and error trying to run
sudo start myproject
. It says:start: Job failed to start
. All the files are exactly like the tutorial. How can I solve this, please?I ran into this issue too - make sure that you are using a non-root account so that the /home/user paths are correct in /etc/init/myproject.conf!
@julianlaval Thank you! I will work on it now. I hope it works. :)
Great writeup thanks a lot! I have a question: How can I set this up so that changes to the Flask application will automatically appear? I tried sudo service nginx restart.
@ktizzel: Try reloading your application server instead:
If that doesn’t work, you can try restarting it:
Hope that helps!
Hi again,
I have another question for you. I am trying to run “sudo reload myproject” using a python script in my flask app. I tried using os.system(“sudo reload myproject”) but that does not work. Do you know how I would do this?
Thanks that worked!
How come it only works if i remove the -m 007 ? edit: It only works perfect if i run the following without (-m 007) directly as the logged in user.
if i use the above in the upstart script, some pages wont work. If i include -m 007, nothing works. Any ideas?
What does
include proxy_params
do? How can i serve the flask static folder with this setup?@igorotak6: The
include proxy_params
reads the contents of the/etc/nginx/proxy_params
file into that point in the configuration file. Basically, this allows us to set up a lot of basic configuration items without having to go through them one by one.You can serve static content by adding an additional location block to your
/etc/nginx/sites-available/myproject
file. For instance, if your application looks for static content at the/static
endpoint, you could adjust your file to look like this:I’m getting a 502 error. Running
gunicorn --bind 0.0.0.0:8000 wsgi:app
worked fine.One deviation from the tutorial is that I cloned in a project I had been working on locally with github, then installed flask and project dependencies via a requirements.txt file, but I don’t think that should cause errors, especially since running gunicorn manually in the virtualenv worked for me.
I tried
sudo tail -f /var/log/upstart/flask-portfolio.log
(my project is called flask-portfolio) and it spit out this:I’ve restarted multiple times, and just can’t get this working. I’m very new to this, so I could be missing something obvious.
I think I found what specifically was messing up my deployment.
When I ran gunicorn inside my virtualenv, I needed to stray a little from the tutorial. The tutorial initially had:
I had to change it to:
I’m not exactly sure why that change was necessary, but I tried it when the tutorial command wasn’t working.
Now keeping that in mind, I forgot to make that same change to the gunicorn exec command in the upstart script:
Once I changed it to:
Everything started working.
After I restart nginx, in the very last step, when I navigate to my domain I’m shown the nginx welcome screen instead of the flask application. All other checkpoints were successful. Any ideas what I could be missing? Thank you for the tutorial.
Exactly the same here. I tried restarting, triple checking etc, just get the screen.
Ok so finally managed to get it working.
So edit sudo nano /etc/nginx/sites-available/myproject and restart Ngixn with
It did not work straight away, so I did what any English man would do, made some tea, and when I came back!!! boom! it was working.
Also to make any changes to your flask app work you need to restart mypyproject
phew!
This is an AWESOME tutorial - thank you soo much. I follwed it exactly and it worked flawlessly.
I just wanted to say thank you for this awesome tutorial!
hello please help me ive been trying to use this tutorial to deploy my application but im getting a strange error (111 connection to upstream client refused) please help ive been stuck for days, when i ru with gunicorn --bind 0.0.0.0:8000 wsgi it works what could be the issue
Hello,
I’ve been doing the tutorial as
root
. When I configure everything I get this error on nginx error.log:I’ve tried to change permissions of test.sock (even 777) and the issue doesn’t disappear. When I start the application with the command
gunicorn --bind 0.0.0.0:8000 wsgi
inside the folder it works perfectly… Do you have any suggestion?Thanks
I solved the issue changing the folder where my app was (from
/root/test
to/home/test
) and it works now. I also had to remove default nginx configuration in/etc/nginx/sites-available/
.Have a nice day
Thanks man…
So quick question, and n00b on flask/gunicorn here. What is the purpose of front ending this with nginx if gunicorn can serve up its own webserver?
Hi!, great tutorial! high quality! Although I am having a problem and I hope you could help. I am using debian (raspbian to be precise). I have gunicorn running with the following command:
And it gives back the pid for the three workers… so it should be fine. I set up the nginx as the guide suggests (I just changed the port):
I have created the link in site-enabled as well. But if I connect to the address I get a “502 Bad Gateway” response…
I have tried several things already, please help!
The -m flag was throwing me off! I used -m 500 and it worked fine.
This flag in gunicorn is used for umask, which is a linux utility that I only half-understand. You can read more about it here (which, while written for Arch, is applicable for both Arch & Debian-based systems) https://wiki.archlinux.org/index.php/Umask
sudo start myproject throws start: Unknown job: myproject
Great tutorial. I have a single Flask app running using the above. I am struggling to get multiple apps running though or getting the flask app served from a location other than /. I’m trying something like this;
server { listen 80; server_name _;
}
I have the 2 apps set up and they both work individually when the location in sites-available is / but can’t get the app running from another location, which was my first step to getting multiple apps running.
Any help would be appreciated.
@redmondinho: I’m not certain, but I think that the issue you’re experiencing is due to behavior of the
proxy_pass
directive combined with the fact that we’re using unix sockets. Basically, if you do not have a URI at the end ofproxy_pass
(which Nginx just defines as some sort of path, even a single slash), it will prepend the matched portion of the location when passing the request to the socket. Basically, this means that if you do not have a trailing slash on theproxy_pass
line, requests for/app1
will get passed to the backend with/app
as the beginning of the request.Since we are using unix sockets, we can’t just append a trailing slash though or else Nginx will think that we are referring to an additional directory level. The syntax needed is to use a colon followed by the path.
What this all comes down to is that you can probably the two location blocks to start working if you adjust them to look like this:
That should interact with Flask correctly because it won’t prepend the
/app1
and/app2
to passes made to Flask. I hope that helps!@jellingwood,
Perfect, cheers.
Thanks for the tutorial. I have one question though. What port do I open with ufw so pip will continue to work as normal?
I saw some stuff on the web saying port 8123/tcp, but I didn’t have any luck with that. Any help is greatly appreciated.
I got one error over and over again while trying to set up nginx and flask on a virtual machine. I copy pasted everything, but I still just saw the default nginx webpage. To fix it, I finally realized that I had to go to /etc/nginx/sites-available and delete the default config, and then it worked perfectly
hello im using debian, sudo start, start command not found?
Hello everyone, I am using ubuntu 16.10 machine, and when I try to execute
sudo start myproject
, it tells me start command not found. I googled for some time and found out that ubuntu 16.10 uses systemd and not upstart, so how am I suppose to execute above command for 16.10 machine ?@jellingwood I have this error “init: Failed to spawn myproject main process: unable to find setuid user”. Here is myproject.conf :
description “Gunicorn application server running myproject”
start on runlevel [2345] stop on runlevel [!2345]
respawn setuid user setgid www-data
env PATH=/root/myproject/myprojectenv/bin chdir /root/myproject exec gunicorn --workers 3 --bind unix:myproject.sock -m 007 wsgi
I dont have home/user/myproject/ instead I have root/myproject and I also changed myproject.py into app.py . I had it running on port 5000 and port 8000.
These are my error logs:
random: nonblocking pool is initialized Disconnected from Upstart Disconnected from Upstart init: upstart-udev-bridge main process (667) terminated with status 1 init: upstart-udev-bridge main process ended, respawning init: upstart-socket-bridge main process (953) terminated with status 1 init: upstart-socket-bridge main process ended, respawning init: upstart-file-bridge main process (1261) terminated with status 1 init: upstart-file-bridge main process ended, respawning (root) CMD ( cd / && run-parts --report /etc/cron.hourly) init: Failed to spawn myproject main process: unable to change working directory: No such file or directory init: Failed to spawn myproject main process: unable to change working directory: No such file or directory init: Failed to spawn myproject main process: unable to change working directory: No such file or directory Failed to spawn myproject main process: unable to change working directory: No such file or directory init: Failed to spawn myproject main process: unable to find setuid user init: Failed to spawn myproject main process: unable to find setuid user
Down at the step of creating the .conf file in the /etc/init directory it seems there are some important parts missing in the conf file. I suspect the pathing.
When I run ‘sudo start (myproject)’ I get:
“sudo: start: command not found”
Is the syntax in:
exec gunicorn --workers 3 --bind unix:myproject.sock -m 007 wsgi
correct? Should there be more comprehensive paths in here?
Thanks,
Chris.
@chris1066 If the system is telling you that the
start
command is not available, it’s very likely that you are trying to run this on the wrong version of Ubuntu. Thestart
command is a part of the Upstart init system, which Ubuntu used through version 14.04.Ubuntu 16.04 is the first long term support release to switch from the Upstart init system to the systemd init system. This means that if you are running on Ubuntu 16.04 or later, the
start
command will not be available.You can either run this tutorial on Ubuntu 14.04 (which is still supported), or you can try following the Ubuntu 16.04 version of this guide to match the version of your server more closely.
Thanks for this great tutorial, while try to access the domain i get below error. 017/09/03 06:25:18 [error] 15994#0: *1 connect() to unix:/home/ubuntu/4k/smilesnaturecure/mysnc.sock failed (111: Connection refused) while connecting to upstream, client: 182.65.222.167, server: smilesnaturecure.com, request: “GET /favicon.ico HTTP/1.1”, upstream: “http://unix:/home/ubuntu/4k/smilesnaturecure/mysnc.sock:/favicon.ico”, host: “www.smilesnaturecure.com”, referrer: “http://www.smilesnaturecure.com/”
Hi! The upstart script needs sudo privileges as you mentioned. I do not have sudo access, and I installed all of the dependencies from source. How is it possible to have an upstart script without root privileges?