7/25/2019 Setting Up Django With Nginx

http://slidepdf.com/reader/full/setting-up-django-with-nginx 1/13

Setting up Django withNginx, Gunicorn,

 virtualenv, supervisor andPostgreSQLJUN 9 TH, 2013

Django is an efcient, versatile and dynamically evolving web applicationdevelopment ramework. When Django initially gained popularity, the recommendedsetup or running Django applications was based around pache with mod!wsgi. Theart o running Django advanced and these days the recommended con"guration is

more efcient and resilient, but also more comple# and includes such tools as$ %gin#,&unicorn, virtualenv, supervisord and 'ostgre()*.+n this te#t + will e#plain how to combine all o these components into a Djangoserver running on *inu#.

Prerequisites

+ assume you have a server available on which you have root privileges. + am using aserver running Debian , so everything here should also work on an -buntu server or

other Debianbased distribution. + you/re using an 0'1based distro 2such as3ent4(5, you will need to replace the aptitude commands by their yum counterpartsand i you/re using 6ree7(D you can install the components rom ports.+ you don/t have a server to play with, + would recommend the ine#pensive 8'(servers o9ered by Digital 4cean. + you click through this link when signing up, you/llpay a bit o my server bill $5+/m also assuming you con"gured your D%( to point a domain at the server/s +'. +nthis te#t, + pretend your domain is e#ample.com

Update your syste

*et/s get started by making sure our system is up to date.

: sudo aptitude update

: sudo aptitude upgrade

PostgreSQL

 To install 'ostgre()* on a Debianbased system run this command$

7/25/2019 Setting Up Django With Nginx

http://slidepdf.com/reader/full/setting-up-django-with-nginx 2/13

: sudo aptitude install postgres;l postgres;lcontrib

3reate a database user and a new database or the app. &rab a perect passwordrom &03.

: sudo su postgres

postgres<django$=: createuser interactive '

>nter name o role to add$ hello!django

>nter password or new role$

>nter it again$

(hall the new role be a superuser? 2y@n5 n

(hall the new role be allowed to create databases? 2y@n5 n

(hall the new role be allowed to create more new roles? 2y@n5 n

postgres<django$=:

postgres<django$=: createdb owner hello!django hello

postgres<django$=: logout

:

 !pplication user

>ven though Django has a pretty good security track record, web applications can

become compromised. + the application has limited access to resources on yourserver, potential damage can also be limited. Aour web applications should run assystem users with limited privileges.3reate a user or your app, named hello and assigned to a system groupcalled webapps.

: sudo groupadd system webapps

: sudo useradd system gid webapps shell @bin@bash home @webapps@hello!django hello

"nstall virtualenv and create an environent #or you app

8irtualenv is a tool which allows you to create separate 'ython environments on yoursystem. This allows you to run applications with di9erent sets o re;uirementsconcurrently 2e.g. one based on Django B.C, another based on B.5. virtualenv is easyto install on Debian$

: sudo aptitude install pythonvirtualenv

$reate and activate an environent #or your application

+ like to keep all my web apps in the@webapps@

 directory. + you preer@var@www@

,@srv@

 orsomething else, use that instead. 3reate a directory to store your application

7/25/2019 Setting Up Django With Nginx

http://slidepdf.com/reader/full/setting-up-django-with-nginx 3/13

in @webapps@hello!django@ and change the owner o that directory to your applicationuser hello

: sudo mkdir p @webapps@hello!django@

: sudo chown hello @webapps@hello!django@

s the application user create a virtual 'ython environment in the applicationdirectory$

: sudo su hello

hello<django$=: cd @webapps@hello!django@

hello<django$=: virtualenv .

%ew python e#ecutable in hello!django@bin@python

+nstalling distribute..............done.

+nstalling pip.....................done.

hello<django$=: source bin@activate

2hello!django5hello<django$=:

 Aour environment is now activated and you can proceed to install Django inside it.

2hello!django5hello<django$=: pip install django

Downloading@unpacking django

2...5

+nstalling collected packages$ django

2...5

(uccessully installed django

3leaning up...

 Aour environment with Django should be ready to use. &o ahead and create anempty Django project.

2hello!django5hello<django$=: djangoadmin.py startproject hello

 Aou can test it by running the development server$

2hello!django5hello<django$=: cd hello

7/25/2019 Setting Up Django With Nginx

http://slidepdf.com/reader/full/setting-up-django-with-nginx 4/13

2hello!django5hello<django$=: python manage.py runserver e#ample.com$EFFF

8alidating models...

F errors ound Gune F, IFBJ F$BI$FF

Django version B.C.B, using settings Khello.settingsK

Development server is running at http$@@e#ample.com$EFFF@

)uit the server with 34%T04*3.

 Aou should now be able to access your development serverrom http$@@e#ample.com$EFFF !llowing other users write access to the application directory 

 Aour application will run as the user hello, who owns the entire application directory. + you want regular user to be able to change application "les, you can set the groupowner o the directory to users and give the group write permissions.

: sudo chown 0 hello$users @webapps@hello!django

: sudo chmod 0 gLw @webapps@hello!django

 Aou can check what groups you/re a member o by issuing the groups command or id.

: id

uidMBFFF2michal5 gidMBFFF2michal5 groupsMBFFF2michal5,I2sudo5,BFF2users5

+ you/re not a member o users, you can add yoursel to the group with thiscommand$

: sudo usermod a & users NwhoamiN

&roup memberships are assigned during login, so you may need to log out and backin again or the system to recogniOe your new group.

$on#igure PostgreSQL to wor% with Django

+n order to use Django with 'ostgre()* you will need to install the psycopgI databaseadapter in your virtual environment. This step re;uires the compilation o a nativee#tension 2written in 35. The compilation will ail i it cannot "nd header "les andstatic libraries re;uired or linking 3 programs with libp; 2library or communicationwith 'ostgres5 and building 'ython modules 2pythondev package5. We have to installthese two packages "rst, then we can install psycopgI using '+'.+nstall dependencies$

7/25/2019 Setting Up Django With Nginx

http://slidepdf.com/reader/full/setting-up-django-with-nginx 5/13

: sudo aptitude install libp;dev pythondev

+nstall psycopgI database adapter$

2hello!django5hello<django$=: pip install psycopgI

 Aou can now con"gure the databases section in your settings.py$

B

I

J

P

C

E

B

F

DT7(>( M Q

  KdeaultK$ Q

  K>%&+%>K$ Kdjango.db.backends.postgres;l!psycopgIK,

  K%1>K$ KhelloK,

  K-(>0K$ Khello!djangoK,

  K'((W40DK$ KBkC0T)tmtwF40>s'hGAOR+akPBgnrmC%WA>os3e+duGckBFaw+OoysBwvb*EK,

  KH4(TK$ KlocalhostK,

  K'40TK$ KK, S (et to empty string or deault.

 

nd "nally build the initial database or Django$

2hello!django5hello<django$=: python manage.py syncdb

Gunicorn

+n production we won/t be using Django/s singlethreaded development server, but adedicated application server called gunicorn.+nstall gunicorn in your application/s virtual environment$

2hello!django5hello<django$=: pip install gunicorn

Downloading@unpacking gunicorn

  Downloading gunicornF.B.P.tar.gO 2JIUb5$ JIUb downloaded

  0unning setup.py egg!ino or package gunicorn

+nstalling collected packages$ gunicorn

  0unning setup.py install or gunicorn

  +nstalling gunicorn!paster script to @webapps@hello!django@bin

  +nstalling gunicorn script to @webapps@hello!django@bin

  +nstalling gunicorn!django script to @webapps@hello!django@bin

(uccessully installed gunicorn

7/25/2019 Setting Up Django With Nginx

http://slidepdf.com/reader/full/setting-up-django-with-nginx 6/13

3leaning up...

%ow that you have gunicorn, you can test whether it can serve your Djangoapplication by running the ollowing command$

2hello!django5hello<django$=: gunicorn hello.wsgi$application bind e#ample.com$EFFB

 Aou should now be able to access the &unicorn serverrom http$@@e#ample.com$EFFB . + intentionally changed port EFFF to EFFB to orceyour browser to establish a new connection.&unicorn is installed and ready to serve your app. *et/s set some con"gurationoptions to make it more useul. + like to set a number o parameters, so let/s putthem all into a small 7(H script, which + save as bin@gunicorn!start

SV@bin@bash

%1>Mhello!app  S %ame o the applicationDG%&4D+0M@webapps@hello!django@hello S Django project directory(43U6+*>M@webapps@hello!django@run@gunicorn.sock S we will communicte using this uni# socket-(>0Mhello S the user to run as&04-'Mwebapps S the group to run as%-1!W40U>0(MJ S how many worker processes should &unicorn spawnDG%&4!(>TT+%&(!14D-*>Mhello.settings S which settings "le should Django useDG%&4!W(&+!14D-*>Mhello.wsgi S W(&+ module name

echo (tarting :%1> as NwhoamiN

S ctivate the virtual environment

cd :DG%&4D+0source ..@bin@activatee#port DG%&4!(>TT+%&(!14D-*>M:DG%&4!(>TT+%&(!14D-*>e#port 'ATH4%'THM:DG%&4D+0$:'ATH4%'TH

S 3reate the run directory i it doesnKt e#ist0-%D+0M:2dirname :(43U6+*>5test d :0-%D+0 XX mkdir p :0-%D+0

S (tart your Django -nicornS 'rograms meant to be run under supervisor should not daemoniOe themselves 2do not use daemon5e#ec ..@bin@gunicorn :QDG%&4!W(&+!14D-*>$application Y  name :%1> Y  workers :%-1!W40U>0( Y

  userM:-(>0 groupM:&04-' Y  bindMuni#$:(43U6+*> Y  loglevelMdebug Y  log"leM

view raw gunicorn_start.bashhosted with Z by GitHub

(et the e#ecutable bit on the gunicorn!start script$

: sudo chmod uL# bin@gunicorn!start

 Aou can test your gunicorn!start script by running it as the user hello.

: sudo su hello

7/25/2019 Setting Up Django With Nginx

http://slidepdf.com/reader/full/setting-up-django-with-nginx 7/13

hello<django$=: bin@gunicorn!start

(tarting hello!app as hello

IFBJFF BP$IB$PC [BFIP\ [+%64\ (tarting gunicorn BE.F

IFBJFF BP$IB$PC [BFIP\ [D>7-&\ rbiter bootedIFBJFF BP$IB$PC [BFIP\ [+%64\ *istening at$ uni#$@webapps@hello!django@run@gunicorn.sock 2BFIP5

IFBJFF BP$IB$PC [BFIP\ [+%64\ -sing worker$ sync

IFBJFF BP$IB$PC [BFJC\ [+%64\ 7ooting worker with pid$ BFJC

IFBJFF BP$IB$PC [BFJ\ [+%64\ 7ooting worker with pid$ BFJ

IFBJFF BP$IB$PC [BFJ\ [+%64\ 7ooting worker with pid$ BFJ

]3 234%T04*3 to kill &unicorn5

IFBJFF BP$IB$PE [BFJ\ [+%64\ Worker e#iting 2pid$ BFJ5

IFBJFF BP$IB$PE [BFJC\ [+%64\ Worker e#iting 2pid$ BFJC5

IFBJFF BP$IB$PE [BFIP\ [+%64\ Handling signal$ int

IFBJFF BP$IB$PE [BFJ\ [+%64\ Worker e#iting 2pid$ BFJ5

IFBJFF BP$IB$PE [BFIP\ [+%64\ (hutting down$ 1aster

: e#it

%ote the parameters set in gunicorn!start. Aou/ll need to set the paths and "lenames tomatch your setup.

s a ruleothumb set the workers 2%-1!W40U>0(5 according to the ollowing ormula$I ^ 3'-s L B. The idea being, that at any given time hal o your workers will be busydoing +@4. 6or a single 3'- machine it would give you J. The name 2%1>5 argument speci"es how your application will identiy itsel inprograms such as top or ps. +t deaults to gunicorn, which might make it harder todistinguish rom other apps i you have multiple &unicornpowered applicationsrunning on the same server.+n order or the name argument to have an e9ect you need to install a 'ythonmodule called setproctitle. To build this native e#tension pip needs to have access to 3

header "les or 'ython. Aou can add them to your system with the pythondev packageand then install setproctitle.

: sudo aptitude install pythondev

2hello!django5hello<django$=: pip install setproctitle

%ow when you list processes, you should see which gunicorn belongs to whichapplication.

: ps au#

7/25/2019 Setting Up Django With Nginx

http://slidepdf.com/reader/full/setting-up-django-with-nginx 8/13

-(>0 '+D _3'- _1>1 8(` 0(( TTA (TT (T0T T+1> 3411%D

2...5

hello BBCEE F. F.I CEPFF BBCE ? ( BP$CI F$FF gunicorn$ master [hello!app\

hello BBFI F.C F.J CEP BFPF ? ( BP$CI F$FF gunicorn$ worker [hello!app\hello BBFJ F.C F.J CI BFPP ? ( BP$CI F$FF gunicorn$ worker [hello!app\

hello BBFP F.C F.J FP BFCI ? ( BP$CI F$FF gunicorn$ worker [hello!app\

Starting and onitoring with Supervisor

 Aour gunicorn!start script should now be ready and working. We need to make sure thatit starts automatically with the system and that it can automatically restart i orsome reason it e#its une#pectedly. These tasks can easily be handled by a servicecalled supervisord. +nstallation is simple$

: sudo aptitude install supervisor

When (upervisor is installed you can give it programs to start and watch by creatingcon"guration "les in the @etc@supervisor@con.d  directory. 6or our hello application we/llcreate a "le named @etc@supervisor@con.d@hello.con  with this content$[program$hello\command M @webapps@hello!django@bin@gunicorn!start 3ommand to startappuser M hello -ser to run asstdout!log"le M @webapps@hello!django@logs@gunicorn!supervisor.log Where to write

log messagesredirect!stderr M true (ave stderr in the same logenvironmentM*%&Men!-(.-T6E,*3!**Men!-(.-T6E (et -T6E asdeault encoding

view rawhello.conf hosted with Z by GitHub

 Aou can set many other options, but this basic con"guration should sufce.3reate the "le to store your application/s log messages$

hello<django$=: mkdir p @webapps@hello!django@logs@

hello<django$=: touch @webapps@hello!django@logs@gunicorn!supervisor.log

ter you save the con"guration "le or your program you can ask supervisor toreread con"guration "les and update 2which will start your the newly registered app5.

: sudo supervisorctl reread

hello$ available

: sudo supervisorctl update

hello$ added process group

 Aou can also check the status o your app or start, stop or restart it using supervisor.

7/25/2019 Setting Up Django With Nginx

http://slidepdf.com/reader/full/setting-up-django-with-nginx 9/13

: sudo supervisorctl status hello

hello 0-%%+%& pid BEFIF, uptime F$FF$CF

: sudo supervisorctl stop hello

hello$ stopped: sudo supervisorctl start hello

hello$ started

: sudo supervisorctl restart hello

hello$ stopped

hello$ started

 Aour application should now be automatically started ater a system reboot andautomatically restarted i it ever crashed or some reason.

Nginx

 Time to set up %gin# as a server or out application and its static "les. +nstall andstart %gin#$

: sudo aptitude install ngin#

: sudo service ngin# start

 Aou can navigate to your server 2http$@@e#ample.com5 with your browser and %gin#should greet you with the words Welcome to ngin#V.$reate an Nginx virtual server con#iguration #or Django

>ach %gin# virtual server should be described by a "le in the @etc@ngin#@sites

availabledirectory. Aou select which sites you want to enable by making symbolic linksto those in the@etc@ngin#@sitesenabled directory.3reate a new ngin# server con"guration "le or your Django application running one#ample.com in @etc@ngin#@sitesavailable@hello. The "le should contain something alongthe ollowing lines. more detailed e#ample is available rom the olks who make

&unicorn.upstream hello!app!server Q  S ail!timeoutMF means we always retry an upstream even i it ailed  S to return a good HTT' response 2in case the -nicorn master nukes a  S single worker or timing out5.

  server uni#$@webapps@hello!django@run@gunicorn.sock ail!timeoutMF

server Q

  listen  EF  server!name e#ample.com

7/25/2019 Setting Up Django With Nginx

http://slidepdf.com/reader/full/setting-up-django-with-nginx 10/13

  client!ma#!body!siOe P&

  access!log @webapps@hello!django@logs@ngin#access.log  error!log @webapps@hello!django@logs@ngin#error.log

  location @static@ Q  alias  @webapps@hello!django@static@   

location @media@ Q  alias  @webapps@hello!django@media@ 

  location @ Q  S an HTT' header important enough to have its own Wikipedia entry$  S http$@@en.wikipedia.org@wiki@R6orwarded6or  pro#y!set!header R6orwarded6or :pro#y!add!#!orwarded!or

  S enable this i and only i you use HTT'(, this helps 0ack  S set the proper protocol or doing redirects$  S pro#y!set!header R6orwarded'roto https

  S pass the Host$ header rom the client right along so redirects  S can be set properly within the 0ack application  pro#y!set!header Host :http!host

  S we donKt want ngin# trying to do something clever with

  S redirects, we set the Host$ header above already.  pro#y!redirect o9 

  S set pro#y!bu9ering o9 ^only^ or 0ainbowsV when doing  S 3omet@longpoll stu9. +tKs also sae to set i youKre  S using only serving ast clients with -nicorn L ngin#.  S 4therwise you !want! ngin# to bu9er responses to slow  S clients, really.  S pro#y!bu9ering o9

  S Try to serve static "les rom ngin#, no point in making an

  S ^application^ server like -nicorn@0ainbowsV serve static "les.  i  2V :re;uest!"lename5 Q  pro#y!pass http$@@hello!app!server  break   

  S >rror pages  error!page CFF CFI CFJ CFP @CFF.html  location M @CFF.html Q  root @webapps@hello!django@static@ 

view raw hello.nginxconf hosted with Z by GitHub

7/25/2019 Setting Up Django With Nginx

http://slidepdf.com/reader/full/setting-up-django-with-nginx 11/13

3reate a symbolic link in the sitesenabled older$

: sudo ln s @etc@ngin#@sitesavailable@hello @etc@ngin#@sitesenabled@hello

0estart %gin#$

: sudo service ngin# restart

+ you navigate to your site, you should now see your Django welcomepage poweredby %gin# and &unicorn. &o ahead and develop to your heart/s content.

t this stage you may "nd that instead o the Django welcomepage, you encounterthe deault Welcome to nginx! page. This may be caused bythe deault con"guration "le, which is installed with %gin# and masks your new site/scon"guration. + you don/t plan to use it, delete the symbolic link to this "lerom @etc@ngin#@sitesenabled.+ you run into any problems with the above setup, please drop me a line.

&inal directory structure

+ you ollowed this tutorial, you should have created a directory structure resemblingthis$

@webapps@hello!django@

bin M Directory created by virtualenv

activate M >nvironment activation script

djangoadmin.py

gunicorn

gunicorn!django

gunicorn!start M (cript to start application with &unicorn

python

hello M Django project directory, add this to 'ATH4%'TH

manage.py

project!application!B

project!application!I

hello M 'roject settings directory

!!init!!.py

settings.py M hello.settings settings module &unicorn will use

urls.py

wsgi.py M hello.wsgi W(&+ module &unicorn will use

7/25/2019 Setting Up Django With Nginx

http://slidepdf.com/reader/full/setting-up-django-with-nginx 12/13

include

pythonI. @usr@include@pythonI.

lib

pythonI. libP @webapps@hello!django@lib

logs M pplication logs directory

gunicorn!supervisor.log

ngin#access.log

ngin#error.log

media M -ser uploaded "les older

run

gunicorn.sock

static M 3ollect and serve static "les rom here

Uninstalling the Django application

+ time comes to remove the application, ollow these steps.

0emove the virtual server rom %gin# sitesenabled older$

: sudo rm @etc@ngin#@sitesenabled@hello!django

0estart %gin#$

: sudo service ngin# restart

+ you never plan to use this application again, you can remove its con"g "le alsorom the sitesavailable directory

: sudo rm @etc@ngin#@sitesavailable@hello!django

(top the application with (upervisor$

: sudo supervisorctl stop hello

0emove the application rom (upervisor/s control scripts directory$

: sudo rm @etc@supervisor@con.d@hello.con 

+ you never plan to use this application again, you can now remove its entire

directory rom webapps$

7/25/2019 Setting Up Django With Nginx

http://slidepdf.com/reader/full/setting-up-django-with-nginx 13/13

: sudo rm r @webapps@hello!django