10/4/13

Getting Started with Django on Heroku | Heroku Dev Center

GettingStartedwithDjangoonHeroku
LastUpdated:27September2013

TableofContents
Prerequisites StartaDjangoappinsideaVirtualenv DeclareprocesstypeswithProcfile SpecifydependencieswithPip Djangosettings StoreyourappinGit DeploytoHeroku Dynosleepingandscaling Nextsteps ThisquickstartwillgetyougoingwithaPython/DjangoapplicationthatusesaPostgresdatabase,deployedtoHeroku.For otherPythonapps,seeGettingStartedwithPythononHeroku.Forgeneralinformationonhowtodevelopandarchitect appsforuseonHeroku,seeArchitectingApplicationsforHeroku. IfyouhavequestionsaboutPythononHeroku,considerdiscussingitinthePythononHerokuforums.BothHerokuand communitybasedPythonexpertsareavailable.

Prerequisites
TheHerokutoolbelt,asdescribedinGettingStartedwithPython. InstalledPythonandVirtualenv.Seethisguideforguidance. AninstalledversionofPostgrestotestlocally. AHerokuuseraccount.Signupisfreeandinstant.

StartaDjangoappinsideaVirtualenv
First,wellcreateanemptytopleveldirectoryforourproject:
$m k d i rh e l l o d j a n g o& &c dh e l l o d j a n g o

Makesureyoureusingthelatestvirtualenvrelease.IfyoureusingaversionthatcomeswithUbuntu,youmayneedto addthen o s i t e p a c k a g e s flag. Next,wellcreateaPythonVirtualenv(v0.7):

$v i r t u a l e n vv e n vd i s t r i b u t e N e wp y t h o ne x e c u t a b l ei nv e n v / b i n / p y t h o n I n s t a l l i n gd i s t r i b u t e . . . . . . . . . . . . . . . d o n e . I n s t a l l i n gp i p . . . . . . . . . . . . . . . d o n e .

Tousethenewvirtualenv,weneedtoactivateit.(Youmustsourcethevirtualenvenvironmentforeachterminalsession whereyouwishtorunyourapp.) Windowsuserscanrunv e n v \ S c r i p t s \ a c t i v a t e . b a t forthesameeffect.

$s o u r c ev e n v / b i n / a c t i v a t e

Next,installourapplicationsdependencieswithpip.Inthiscase,wewillbeinstallingdjangotoolbelt,whichincludesall ofthepackagesweneed:

https://devcenter.heroku.com/articles/getting-started-with-django

1/6

10/4/13

Getting Started with Django on Heroku | Heroku Dev Center

Django(thewebframework) Gunicorn(WSGIserver) djdatabaseurl(aDjangoconfigurationhelper) djstatic(aDjangostaticfileserver) Fromyourvirtualenv:

$p i pi n s t a l ld j a n g o t o o l b e l t I n s t a l l i n gc o l l e c t e dp a c k a g e s :D j a n g o ,p s y c o p g 2 ,g u n i c o r n ,d j d a t a b a s e u r l ,d j s t a t i c ,s t a t i c . . . S u c c e s s f u l l yi n s t a l l e dD j a n g op s y c o p g 2g u n i c o r nd j d a t a b a s e u r ld j s t a t i cs t a t i c C l e a n i n gu p . . .

NowthatwehaveacleanPythonenvironmenttoworkin,wellcreateoursimpleDjangoapplication. Dontforgetthe. attheend.ThistellsDjangotoputtheextracttheintothecurrentdirectory,insteadofputtingitinanew subdirectory.

$d j a n g o a d m i n . p ys t a r t p r o j e c th e l l o d j a n g o.

DeclareprocesstypeswithProcfile
UseaProcfile,atextfileintherootdirectoryofyourapplication,toexplicitlydeclarewhatcommandshouldbeexecuted tostartawebdyno.Inthiscase,youneedtoexecuteGunicornwithafewarguments. HeresaP r o c f i l e forournewapp.ItshouldbecalledP r o c f i l e andliveattherootdirectoryofourproject: Procfile
w e b :g u n i c o r nh e l l o d j a n g o . w s g i

YoucannowstarttheprocessesinyourProcfilelocallyusingForeman(installedaspartoftheToolbelt):
$f o r e m a ns t a r t 2 0 1 3 0 4 0 31 6 : 1 1 : 2 2[ 8 4 6 9 ][ I N F O ]S t a r t i n gg u n i c o r n0 . 1 7 . 2 2 0 1 3 0 4 0 31 6 : 1 1 : 2 2[ 8 4 6 9 ][ I N F O ]L i s t e n i n ga t :h t t p : / / 1 2 7 . 0 . 0 . 1 : 8 0 0 0( 8 4 6 9 )

Makesurethingsareworkingproperlyc u r l orawebbrowser,thenCtrlCtoexit.

SpecifydependencieswithPip
HerokurecognizesPythonapplicationsbytheexistenceofar e q u i r e m e n t s . t x t fileintherootofarepository.This simpleformatisusedbymostPythonprojectstospecifytheexternalPythonmodulestheapplicationrequires. Piphasanicecommand(p i pf r e e z e )thatwillgeneratethisfileforus:
$p i pf r e e z e>r e q u i r e m e n t s . t x t

requirements.txt
D j a n g o = = 1 . 5 . 1 d j d a t a b a s e u r l = = 0 . 2 . 1 d j s t a t i c = = 0 . 0 . 5 g u n i c o r n = = 1 7 . 5 p s y c o p g 2 = = 2 . 5 . 1 s t a t i c = = 0 . 4

Pipcanalsobeusedforadvanceddependencymanagement.SeePythonDependenciesviaPiptolearnmore.

Djangosettings

https://devcenter.heroku.com/articles/getting-started-with-django

2/6

10/4/13

Getting Started with Django on Heroku | Heroku Dev Center

Next,configuretheapplicationfortheHerokuenvironment,includingHerokusPostgresdatabase.Thedjdatabaseurl modulewillparsethevaluesoftheD A T A B A S E _ U R L environmentvariableandconvertthemtosomethingDjangocan understand. Makesuredjdatabaseurlisinyourrequirementsfile,thenaddthefollowingtothebottomofyours e t t i n g s . p y file: settings.py

#P a r s ed a t a b a s ec o n f i g u r a t i o nf r o m$ D A T A B A S E _ U R L i m p o r td j _ d a t a b a s e _ u r l D A T A B A S E S [ ' d e f a u l t ' ]= d j _ d a t a b a s e _ u r l . c o n f i g ( ) #H o n o rt h e' X F o r w a r d e d P r o t o 'h e a d e rf o rr e q u e s t . i s _ s e c u r e ( ) S E C U R E _ P R O X Y _ S S L _ H E A D E R=( ' H T T P _ X _ F O R W A R D E D _ P R O T O ' ,' h t t p s ' ) #A l l o wa l lh o s th e a d e r s A L L O W E D _ H O S T S=[ ' * ' ] #S t a t i ca s s e tc o n f i g u r a t i o n i m p o r to s B A S E _ D I R=o s . p a t h . d i r n a m e ( o s . p a t h . a b s p a t h ( _ _ f i l e _ _ ) ) S T A T I C _ R O O T=' s t a t i c f i l e s ' S T A T I C _ U R L=' / s t a t i c / ' S T A T I C F I L E S _ D I R S=( o s . p a t h . j o i n ( B A S E _ D I R ,' s t a t i c ' ) , )

Withthesesettingsavailable,youcanaddthefollowingcodetow s g i . p y toservestaticfilesinproduction: wsgi.py

f r o md j a n g o . c o r e . w s g ii m p o r tg e t _ w s g i _ a p p l i c a t i o n f r o md j _ s t a t i ci m p o r tC l i n g a p p l i c a t i o n=C l i n g ( g e t _ w s g i _ a p p l i c a t i o n ( ) )

StoreyourappinGit
Nowthatwevewrittenandtestedourapplication,weneedtostoretheprojectinaGitrepository. Sinceourcurrentdirectorycontainsalofofextrafiles,wellwanttoconfigureourrepositorytoignorethesefileswitha . g i t i g n o r e file: GitHubprovidesanexcellentPythongitignorefilethatcanbeinstalledsystemwide. .gitignore
v e n v * . p y c s t a t i c f i l e s

Next,wellcreateanewgitrepositoryandsaveourchanges.
$g i ti n i t I n i t i a l i z e de m p t yG i tr e p o s i t o r yi n/ U s e r s / k r e i t z / h e l l o d j a n g o / . g i t / $g i ta d d. $g i tc o m m i tm" m yd j a n g oa p p " [ m a s t e r( r o o t c o m m i t )2 9 4 3 4 1 2 ]m yd j a n g oa p p 7f i l e sc h a n g e d ,2 3 0i n s e r t i o n s ( + ) c r e a t em o d e1 0 0 6 4 4. g i t i g n o r e c r e a t em o d e1 0 0 6 4 4P r o c f i l e c r e a t em o d e1 0 0 6 4 4h e l l o d j a n g o / _ _ i n i t _ _ . p y c r e a t em o d e1 0 0 6 4 4h e l l o d j a n g o / s e t t i n g s . p y

https://devcenter.heroku.com/articles/getting-started-with-django

3/6

10/4/13

Getting Started with Django on Heroku | Heroku Dev Center

c r e a t em o d e1 0 0 6 4 4h e l l o d j a n g o / u r l s . p y c r e a t em o d e1 0 0 6 4 4h e l l o d j a n g o / w s g i . p y c r e a t em o d e1 0 0 6 4 4m a n a g e . p y c r e a t em o d e1 0 0 6 4 4r e q u i r e m e n t s . t x t

DeploytoHeroku
ThenextstepistopushtheapplicationsrepositorytoHeroku.First,wehavetogetaplacetopushtofromHeroku.We candothiswiththeh e r o k uc r e a t e command:
$h e r o k uc r e a t e C r e a t i n gs i m p l e s p r i n g 9 9 9 9 . . .d o n e ,s t a c ki sc e d a r h t t p : / / s i m p l e s p r i n g 9 9 9 9 . h e r o k u a p p . c o m /|g i t @ h e r o k u . c o m : s i m p l e s p r i n g 9 9 9 9 . g i t G i tr e m o t eh e r o k ua d d e d

ThisautomaticallyaddedtheHerokuremoteforourapp(g i t @ h e r o k u . c o m : s i m p l e s p r i n g 9 9 9 9 . g i t )toourrepository. Nowwecandoasimpleg i tp u s h todeployourapplication:

$g i tp u s hh e r o k um a s t e r C o u n t i n go b j e c t s :1 1 ,d o n e . D e l t ac o m p r e s s i o nu s i n gu pt o4t h r e a d s . C o m p r e s s i n go b j e c t s :1 0 0 %( 9 / 9 ) ,d o n e . W r i t i n go b j e c t s :1 0 0 %( 1 1 / 1 1 ) ,4 . 0 1K i B ,d o n e . T o t a l1 1( d e l t a0 ) ,r e u s e d0( d e l t a0 ) >P y t h o na p pd e t e c t e d >N or u n t i m e . t x tp r o v i d e d ;a s s u m i n gp y t h o n 2 . 7 . 4 . >P r e p a r i n gP y t h o nr u n t i m e( p y t h o n 2 . 7 . 4 ) >I n s t a l l i n gD i s t r i b u t e( 0 . 6 . 3 6 ) >I n s t a l l i n gP i p( 1 . 3 . 1 ) >I n s t a l l i n gd e p e n d e n c i e su s i n gP i p( 1 . 3 . 1 ) D o w n l o a d i n g / u n p a c k i n gD j a n g o = = 1 . 5( f r o mrr e q u i r e m e n t s . t x t( l i n e1 ) ) . . . S u c c e s s f u l l yi n s t a l l e dD j a n g op s y c o p g 2g u n i c o r nd j d a t a b a s e u r ld j s t a t i cs t a t i c C l e a n i n gu p . . . >C o l l e c t i n gs t a t i cf i l e s 0s t a t i cf i l e sc o p i e d . >D i s c o v e r i n gp r o c e s st y p e s P r o c f i l ed e c l a r e st y p e s>w e b >C o m p i l e ds l u gs i z ei s2 9 . 5 M B >L a u n c h i n g . . .d o n e ,v 6 h t t p : / / s i m p l e s p r i n g 9 9 9 9 . h e r o k u a p p . c o md e p l o y e dt oH e r o k u T og i t @ h e r o k u . c o m : s i m p l e s p r i n g 9 9 9 9 . g i t *[ n e wb r a n c h ] m a s t e r>m a s t e r

Visityourapplication
YouvedeployedyourcodetoHeroku,andspecifiedtheprocesstypesinaP r o c f i l e .YoucannowinstructHerokuto executeaprocesstype.Herokudoesthisbyrunningtheassociatedcommandinadynoalightweightcontainerwhichis thebasicunitofcompositiononHeroku. Letsensurewehaveonedynorunningthew e b processtype:
$h e r o k up s : s c a l ew e b = 1

Youcancheckthestateoftheappsdynos.Theh e r o k up s commandliststherunningdynosofyourapplication:
$h e r o k up s = = =w e b :` g u n i c o r nh e l l o d j a n g o . w s g i ` w e b . 1 :u pf o r1 0 s

Here,onedynoisrunning. Wecannowvisittheappinourbrowserwithh e r o k uo p e n .

https://devcenter.heroku.com/articles/getting-started-with-django

4/6

10/4/13

Getting Started with Django on Heroku | Heroku Dev Center

$h e r o k uo p e n O p e n i n gs i m p l e s p r i n g 9 9 9 9 . h e r o k u a p p . c o m . . .d o n e

YoushouldseethesatisfyingItworked!Djangowelcomepage.

Dynosleepingandscaling
Havingonlyasinglewebdynorunningwillresultinthedynogoingtosleepafteronehourofinactivity.Thiscausesa delayofafewsecondsforthefirstrequestuponwaking.Subsequentrequestswillperformnormally. Toavoidthis,youcanscaletomorethanonewebdyno.Forexample:
$h e r o k up s : s c a l ew e b = 2

Foreachapplication,Herokuprovides750freedynohours.Runningyourappat2dynoswouldexceedthisfree,monthly allowance,soletsscaleback:
$h e r o k up s : s c a l ew e b = 1

Viewthelogs
Herokutreatslogsasstreamsoftimeorderedeventsaggregatedfromtheoutputstreamsofallthedynosrunningthe componentsofyourapplication.HerokusLogplexprovidesasinglechannelforalloftheseevents. Viewinformationaboutyourrunningappusingoneoftheloggingcommands,h e r o k ul o g s :
$h e r o k ul o g s 2 0 1 2 0 4 0 6 T 1 9 : 3 8 : 2 5 + 0 0 : 0 0h e r o k u [ w e b . 1 ] :S t a t ec h a n g e df r o mc r e a t e dt os t a r t i n g 2 0 1 2 0 4 0 6 T 1 9 : 3 8 : 2 9 + 0 0 : 0 0h e r o k u [ w e b . 1 ] :S t a r t i n gp r o c e s sw i t hc o m m a n d` g u n i c o r nh e l l o d j a n g o . w s g i ` 2 0 1 2 0 4 0 6 T 1 9 : 3 8 : 2 9 + 0 0 : 0 0a p p [ w e b . 1 ] :V a l i d a t i n gm o d e l s . . . 2 0 1 2 0 4 0 6 T 1 9 : 3 8 : 2 9 + 0 0 : 0 0a p p [ w e b . 1 ] : 2 0 1 2 0 4 0 6 T 1 9 : 3 8 : 2 9 + 0 0 : 0 0a p p [ w e b . 1 ] :0e r r o r sf o u n d 2 0 1 2 0 4 0 6 T 1 9 : 3 8 : 2 9 + 0 0 : 0 0a p p [ w e b . 1 ] :D j a n g ov e r s i o n1 . 5 ,u s i n gs e t t i n g s' h e l l o d j a n g o . s e t t i n g s ' 2 0 1 2 0 4 0 6 T 1 9 : 3 8 : 2 9 + 0 0 : 0 0a p p [ w e b . 1 ] :D e v e l o p m e n ts e r v e ri sr u n n i n ga th t t p : / / 0 . 0 . 0 . 0 : 6 5 6 6 / 2 0 1 2 0 4 0 6 T 1 9 : 3 8 : 2 9 + 0 0 : 0 0a p p [ w e b . 1 ] :Q u i tt h es e r v e rw i t hC O N T R O L C . 2 0 1 2 0 4 0 6 T 1 9 : 3 8 : 3 0 + 0 0 : 0 0h e r o k u [ w e b . 1 ] :S t a t ec h a n g e df r o ms t a r t i n gt ou p 2 0 1 2 0 4 0 6 T 1 9 : 3 8 : 3 2 + 0 0 : 0 0h e r o k u [ s l u g c ] :S l u gc o m p i l a t i o nf i n i s h e d

Syncingthedatabase
Theh e r o k ur u n commandletsyourunoneoffadmindynos.YoucanusethistosynctheDjangomodelswiththe databaseschema:
$h e r o k ur u np y t h o nm a n a g e . p ys y n c d b R u n n i n gp y t h o nm a n a g e . p ys y n c d ba t t a c h e dt ot e r m i n a l . . .u p ,r u n . 1 C r e a t i n gt a b l e s. . . C r e a t i n gt a b l ea u t h _ p e r m i s s i o n C r e a t i n gt a b l ea u t h _ g r o u p _ p e r m i s s i o n s C r e a t i n gt a b l ea u t h _ g r o u p C r e a t i n gt a b l ea u t h _ u s e r _ g r o u p s C r e a t i n gt a b l ea u t h _ u s e r _ u s e r _ p e r m i s s i o n s C r e a t i n gt a b l ea u t h _ u s e r C r e a t i n gt a b l ed j a n g o _ c o n t e n t _ t y p e C r e a t i n gt a b l ed j a n g o _ s e s s i o n C r e a t i n gt a b l ed j a n g o _ s i t e Y o uj u s ti n s t a l l e dD j a n g o ' sa u t hs y s t e m ,w h i c hm e a n sy o ud o n ' th a v ea n ys u p e r u s e r sd e f i n e d . W o u l dy o ul i k et oc r e a t eo n en o w ?( y e s / n o ) :y e s U s e r n a m e( l e a v eb l a n kt ou s e' u 5 3 9 7 6 ' ) :k e n n e t h E m a i la d d r e s s :k e n n e t h @ h e r o k u . c o m P a s s w o r d : P a s s w o r d( a g a i n ) : S u p e r u s e rc r e a t e ds u c c e s s f u l l y . I n s t a l l i n gc u s t o mS Q L. . . I n s t a l l i n gi n d e x e s. . .

https://devcenter.heroku.com/articles/getting-started-with-django

5/6

10/4/13

Getting Started with Django on Heroku | Heroku Dev Center

I n s t a l l e d0o b j e c t ( s )f r o m0f i x t u r e ( s )

UsingtheDjangoshell
Similarly,youcanuseh e r o k ur u n togetaDjangoshellforexecutingarbitrarycodeagainstyourdeployedapp:
$h e r o k ur u np y t h o nm a n a g e . p ys h e l l R u n n i n gp y t h o nm a n a g e . p ys h e l la t t a c h e dt ot e r m i n a l . . .u p ,r u n . 1 P y t h o n2 . 7 . 4( d e f a u l t ,A p r 62 0 1 3 ,2 2 : 1 4 : 1 3 ) [ G C C4 . 4 . 3 ]o nl i n u x 2 T y p e" h e l p " ," c o p y r i g h t " ," c r e d i t s "o r" l i c e n s e "f o rm o r ei n f o r m a t i o n . ( I n t e r a c t i v e C o n s o l e ) > > >f r o md j a n g o . c o n t r i b . a u t h . m o d e l si m p o r tU s e r > > >U s e r . o b j e c t s . a l l ( ) [ < U s e r :k e n n e t h > ]

Nextsteps
LearnaboutDjangoandStaticAssetsandautomaticcollectstaticrunning. VisitthePythoncategorytolearnmoreaboutdevelopinganddeployingPythonapplications. LearnaboutPythonDependenciesviaPipandSpecifyingaPythonRuntime ExtendyourapparchitecturewithBackgroundTasksinPythonwithRQ ReadHowHerokuWorksforatechnicaloverviewoftheconceptsyoullencounterwhilewriting,configuring, deployingandrunningapplications.

https://devcenter.heroku.com/articles/getting-started-with-django

6/6