1Mojolicious::Guides::CoUoskebrooCko(n3t)ributed Perl DocMuomjeonltiactiioouns::Guides::Cookbook(3)
2
6 Mojolicious::Guides::Cookbook - Cookbook
7
9 Cooking with Mojolicious, recipes for every taste.
10
12 Getting Mojolicious and Mojolicious::Lite applications running on
13 different platforms.
14 Builtin Server
16 Mojolicious contains a very portable HTTP 1.1 compliant web server. It
17 is usally used during development but is solid and fast enough for
18 small to mid sized applications.
19 % ./script/myapp daemon
21 Server available at http://127.0.0.1:3000.
22 It has many configuration options and is known to work on every
24 platform Perl works on.
25 % ./script/myapp help daemon
27 ...List of available options...
28 Another huge advantage is that it supports TLS and WebSockets out of
30 the box.
31 % ./script/myapp daemon --listen https://*:3000
33 Server available at https://*:3000.
34 A development certificate for testing purposes is built right in, so it
36 just works.
37 Builtin Preforking Server
39 To allow scaling with multiple CPUs (cores) and to lower the
40 performance loss from (slow) blocking APIs the built in web server also
41 has a preforking multi process mode. It doesn't work on Windows due to
42 UNIX optimizations but is fast and scalable enough for large
43 applications.
44 % ./script/myapp daemon_prefork
46 Server available at http://127.0.0.1:3000.
47 By default it will accept one client connection per worker process just
49 like Apache, but this value can be increased, allowing huge amounts of
50 concurrent client connections. (epoll and kqueue will be used
51 automatically if available)
52 % ./script/myapp daemon_prefork --clients 100
54 Server available at http://127.0.0.1:3000.
55 Nginx
57 One of the most popular setups these days is the builtin preforking web
58 server behind a Nginx reverse proxy.
59 upstream myapp {
61 server 127.0.0.1:3000;
62 }
63 server {
64 listen 80;
65 server_name localhost;
66 location / {
67 proxy_read_timeout 300;
68 proxy_pass http://myapp;
69 }
70 }
71 Also possible using UNIX domain sockets.
73 upstream myapp {
75 server unix:/tmp/myapp.sock;
76 }
77 server {
78 listen 80;
79 server_name localhost;
80 location / {
81 proxy_read_timeout 300;
82 proxy_pass http://myapp;
83 }
84 }
85 The builtin web server of course supports them as well.
87 % ./script/myapp daemon_prefork --listen file:///tmp/myapp.sock
89 Server available at file:///tmp/myapp.sock.
90 One interesting side effect here is that you can start multiple prefork
92 web servers parallel letting them share the same UNIX domain socket and
93 lock file. This allows something called "Hot Deployment", which
94 essentially means zero downtime software updates.
95 % ./script/myapp daemon_prefork --listen file:///tmp/myapp.sock\
97 --pid /tmp/myapp1.pid --lock /tmp/myapp.lock --daemonize
98 Server available at file:///tmp/myapp.sock.
99 All you have to do is update your application code, start a second web
101 server instance and after that send a "USR1" signal to the old
102 instance. This will bring down the old web server gracefully, so no
103 active connections get interrupted and your users won't notice a thing.
104 % ./script/myapp daemon_prefork --listen file:///tmp/myapp.sock\
106 --pid /tmp/myapp2.pid --lock /tmp/myapp.lock --daemonize
107 % kill -s USR1 `cat /tmp/myapp1.pid`
109 Apache/CGI
111 "CGI" is supported out of the box and your Mojolicious application will
112 automatically detect that it is executed as a "CGI" script.
113 <VirtualHost *:80>
115 ServerName localhost
116 DocumentRoot /home/sri/myapp/public
117 ScriptAlias /myapp "/home/sri/myapp/script/myapp"
119 </VirtualHost>
120 Apache/FastCGI
122 "FastCGI" is also supported out of the box and your Mojolicious
123 application will automatically detect that it is executed as a
124 "FastCGI" script.
125 <VirtualHost *:80>
127 ServerName localhost
128 DocumentRoot /home/sri/myapp/public
129 FastCgiServer /home/sri/myapp/script/myapp -processes 10
131 Alias /myapp /home/sri/myapp/script/myapp
132 </VirtualHost>
133 PSGI/Plack
135 PSGI is an interface between Perl web frameworks and web servers, and
136 Plack is a Perl module and toolkit that contains PSGI middleware,
137 helpers and adapters to web servers. PSGI and Plack are inspired by
138 Python's WSGI and Ruby's Rack. Mojolicious applications are
139 ridiculously simple to deploy with Plack.
140 % plackup ./script/myapp
142 HTTP::Server::PSGI: Accepting connections at http://0:5000/
143 Plack provides many server and protocol adapters for you to choose from
145 such as "FCGI", "SCGI" and "mod_perl". Make sure to run "plackup" from
146 your applications home directory, otherwise libraries might not be
147 found.
148 % plackup ./script/myapp -s FCGI -l /tmp/myapp.sock
150 Because "plackup" uses a weird trick to load your script, Mojolicious
152 is not always able to detect the applications home directory, if thats
153 the case you can simply use the "MOJO_HOME" environment variable. Also
154 note that "app->start" needs to be the last Perl statement in the
155 application script for the same reason.
156 % MOJO_HOME=/home/sri/myapp plackup ./script/myapp
158 HTTP::Server::PSGI: Accepting connections at http://0:5000/
159 Some server adapters might ask for a ".psgi" file, if thats the case
161 you can just point them at your application script because it will
162 automatically act like one if it detects the presence of a "PLACK_ENV"
163 environment variable.
164 Apache/mod_perl (PSGI/Plack)
166 "mod_perl" is a good example for a PSGI adapter that is used without
167 "plackup", note that setting the "PLACK_ENV" environment variable is
168 required for Mojolicious PSGI detection.
169 <VirtualHost *:80>
171 ServerName localhost
172 DocumentRoot /home/sri/myapp/public
173 <Perl>
175 $ENV{PLACK_ENV} = 'production';
176 $ENV{MOJO_HOME} = '/home/sri/myapp';
177 </Perl>
178 <Location /myapp>
180 SetHandler perl-script
181 PerlHandler Plack::Handler::Apache2
182 PerlSetVar psgi_app /home/sri/myapp/script/myapp
183 </Location>
184 </VirtualHost>
185 IIS6.0/FastCGI
187 We don't suggest using IIS, it is a horribly broken web server, avoid
188 it if you can. There is nothing we can do to make this a pleasant
189 experience for you, but maybe we can at least ease some of the pain.
190 First you should make sure to get recent versions of "Strawberry Perl"
192 and Mojolicious installed, "Strawberry" is as good as a Windows version
193 of Perl can be.
194 Then you'll have to install IIS 6.0 and its FastCGI extension, which is
196 not part of the standard installation. Create a new website with
197 "Control Panel" > "Administrative Tools" > "Internet Information
198 Services Manager" > "Action" > "New" > "Web Site" and finish the
199 installation wizard.
200 Open your newly created websites properties and select the tab "Web
202 Site". Set the proper values for "Site Description", "IP Address",
203 "TCP Port", "SSL Port" etc.
204 On the tab "Home Directory" set "Local Path" to "c:\myapp\public",
206 "Local Path Permission Flags" to "Read" and "Log Visits", "Execute
207 Permissions" to "Scripts Only".
208 Click on the "Configuration" button and then "Insert" (next to
210 "Wildcard Application Mappings"). In the next dialog set "Executable"
211 to "c:\windows\system32\inetsrv\fcgiext.dll" and uncheck "Verify That
212 Files Exist".
213 Now put the following lines into
215 "c:\windows\system32\inetsrv\fcgiext.ini" or
216 "c:\windows\syswow64\inetsrv\fcgiext.ini" on 64-bit systems.
217 [Types]
219 *=MyApp
220 [MyApp]
222 ExePath=c:\strawberry\perl\bin\perl.exe
223 Arguments="c:\myapp\script\myapp fastcgi"
224 ; Let IIS serve static files
226 IgnoreExistingFiles=0
227 IgnoreDirectories=1
228 There is one more thing, IIS sometimes clears your environment
230 variables but Windows won't work without "SYSTEMROOT", so you might
231 have to set it manually in your application.
232 # Application
234 package MyApp;
235 use base 'Mojolicious';
236 sub startup {
238 my $self = shift;
239 # Use plugin hook to set environment variable for every request
241 $self->plugins->add_hook(
242 before_dispatch => sub { $ENV{SYSTEMROOT} = 'c:\\winnt' }
243 );
244 }
245 1;
247
249 Hacks that might not be very useful but are fun! :)
250 Hello World
252 If every byte matters this is the smallest "Hello World" application
253 you can write with Mojolicious::Lite.
254 use Mojolicious::Lite;
256 get '/' => {text => 'Hello World!'};
257 app->start;
258 It works because automatic rendering kicks in even if no actual code
260 gets executed by the router, the renderer just picks up the "text"
261 value from the stash and generates a response.
262perl v5.12.3 2010-08-12 Mojolicious::Guides::Cookbook(3)