diff --git a/lib/Dancer2/Manual.pod b/lib/Dancer2/Manual.pod index a981fcc64..a6e5ec120 100644 --- a/lib/Dancer2/Manual.pod +++ b/lib/Dancer2/Manual.pod @@ -1934,150 +1934,6 @@ access to the configuration using the imported keywords: # ... -=head1 PACKAGING - -=head2 Carton - -=head3 What it does - -L sets up a local copy of your project prerequisites. You only -need to define them in a file and ask Carton to download all of them -and set them up. -When you want to deploy your app, you just carry the git clone and ask -Carton to set up the environment again and you will then be able to run it. - -The benefits are multifold: - -=over 4 - -=item * Local Directory copy - -By putting all the dependencies in a local directory, you can make -sure they aren't updated by someone else by accident and their versions -locked to the version you picked. - -=item * Sync versions - -Deciding which versions of the dependent modules your project needs -allows you to sync this with other developers as well. Now you're all -using the same version and they don't change unless you want update the -versions you want. When updated everyone again uses the same new version -of everything. - -=item * Carry only the requirement, not bundled modules - -Instead of bundling the modules, you only actually bundle the requirements. -Carton builds them for you when you need it. - -=back - -=head3 Setting it up - -First set up a new app: - - $ dancer2 gen -a MyApp - ... - -Delete the files that are not needed: - - $ rm -f Makefile.PL MANIFEST MANIFEST.SKIP - -Create a git repo: - - $ git init && git add . && git commit -m "initial commit" - -Add a requirement using the L format: - - $ cat > cpanfile - requires 'Dancer2' => 0.155000; - requires 'Template' => 0; - recommends 'URL::Encode::XS' => 0; - recommends 'CGI::Deurl::XS' => 0; - recommends 'HTTP::Parser::XS' => 0; - -Ask carton to set it up: - - $ carton install - Installing modules using [...] - Successfully installed [...] - ... - Complete! Modules were install into [...]/local - -Now we have two files: I and I. We -add both of them to our Git repository and we make sure we don't -accidentally add the I directory Carton created which holds -the modules it installed: - - $ echo local/ >> .gitignore - $ git add .gitignore cpanfile cpanfile.snapshot - $ git commit -m "Start using carton" - -When we want to update the versions on the production machine, -we simply call: - - $ carton install --deployment - -By using --deployment we make sure we only install the modules -we have in our cpanfile.snapshot file and do not fallback to querying -the CPAN. - -=head2 FatPacker - -L (using its command line interface, L) packs -dependencies into a single file, allowing you to carry a single file -instead of a directory tree. - -As long as your application is pure-Perl, you could create a single -file with your application and all of Dancer2 in it. - -The following example will demonstrate how this can be done: - -Assuming we have an application in I: - - package MyApp; - use Dancer2; - get '/' => sub {'OK'}; - 1; - -And we have a handler in I: - - use strict; - use warnings; - use FindBin; - use lib "$FindBin::Bin/../lib"; - use MyApp; - - MyApp->to_app; - -To fatpack it, we begin by tracing the script: - - $ fatpack trace bin/app.pl - -This creates a I file. From this we create the packlists: - - $ fatpack packlists-for `cat fatpacker.trace` > packlists - -The packlists are stored in a file called I. - -Now we create the tree using the following command: - - $ fatpack tree `cat packlists` - -The tree is created under the directory I. - -Now we create a file containing the dependency tree, and add our script to it, -using the following command: - - $ (fatpack file; cat bin/app.pl) > myapp.pl - -This creates a file called I with everything in it. Dancer2 uses -L which has a database of all MIME types and helps translate those. -The small database file containing all of these types is a binary and therefore -cannot be fatpacked. Hence, it needs to be copied to the current directory so our -script can find it: - - $ cp fatlib/MIME/types.db . - =head1 MIDDLEWARES =head2 Plack middlewares @@ -2148,37 +2004,6 @@ This is necessary if you need to add eTag or ContentMD5 headers to C requests, and you are encouraged to manually add those default middleware back into your PSGI stack. -=head3 Running on Perl web servers with plackup - -A number of Perl web servers supporting PSGI are available on CPAN: - -=over 4 - -=item * L - -C is a high performance web server, with support for preforking, -signals, multiple interfaces, graceful restarts and dynamic worker pool -configuration. - -=item * L - -C is an C web server, it's light and fast. - -=item * L - -C is a C based web server. - -=back - -To start your application, just run plackup (see L and specific -servers above for all available options): - - $ plackup bin/app.psgi - $ plackup -E deployment -s Starman --workers=10 -p 5001 -a bin/app.psgi - -As you can see, the scaffolded Perl script for your app can be used as a -PSGI startup file. - =head4 Enabling content compression Content compression (gzip, deflate) can be easily enabled via a Plack @@ -2228,41 +2053,6 @@ Currently this still demands the same appdir for both (default circumstance) but in a future version this will be easier to change while staying very simple to mount. -=head3 Running from Apache with Plack - -You can run your app from Apache using PSGI (Plack), with a config like the -following: - - - ServerName www.myapp.example.com - ServerAlias myapp.example.com - DocumentRoot /websites/myapp.example.com - - - AllowOverride None - Order allow,deny - Allow from all - - - - SetHandler perl-script - PerlResponseHandler Plack::Handler::Apache2 - PerlSetVar psgi_app /websites/myapp.example.com/app.psgi - - - ErrorLog /websites/myapp.example.com/logs/error_log - CustomLog /websites/myapp.example.com/logs/access_log common - - -To set the environment you want to use for your application (production or -development), you can set it this way: - - - ... - SetEnv DANCER_ENVIRONMENT "production" - ... - - =head1 PLUGINS =head2 Writing a plugin diff --git a/lib/Dancer2/Manual/Deployment.pod b/lib/Dancer2/Manual/Deployment.pod index ca65ed01f..dbc6d3fde 100644 --- a/lib/Dancer2/Manual/Deployment.pod +++ b/lib/Dancer2/Manual/Deployment.pod @@ -91,6 +91,36 @@ B if you are using Dancer 2's asynchronous capabilities, using Shotgun will kill Twiggy. If you need async processing, consider an alternative to Shotgun. +=head3 Running on Perl web servers with plackup + +A number of Perl web servers supporting PSGI are available on CPAN: + +=over 4 + +=item * L + +C is a high performance web server, with support for preforking, +signals, multiple interfaces, graceful restarts and dynamic worker pool +configuration. + +=item * L + +C is an C web server, it's light and fast. + +=item * L + +C is a C based web server. + +=back + +To start your application, just run plackup (see L and specific +servers above for all available options): + + $ plackup -E deployment -s Starman --workers=10 -p 5001 -a bin/app.psgi + +As you can see, the scaffolded Perl script for your app can be used as a +PSGI startup file. + =head2 Running under Apache You can run your Dancer app from Apache using the following examples: @@ -721,5 +751,149 @@ will prevent you from fatpacking your application. These modules are installed by default when building a Docker container containing your application. +=head1 Packaging Dancer2 applications for CPAN + +=head2 Carton + +=head3 What it does + +L sets up a local copy of your project prerequisites. You only +need to define them in a file and ask Carton to download all of them +and set them up. +When you want to deploy your app, you just carry the git clone and ask +Carton to set up the environment again and you will then be able to run it. + +The benefits are multifold: + +=over 4 + +=item * Local Directory copy + +By putting all the dependencies in a local directory, you can make +sure they aren't updated by someone else by accident and their versions +locked to the version you picked. + +=item * Sync versions + +Deciding which versions of the dependent modules your project needs +allows you to sync this with other developers as well. Now you're all +using the same version and they don't change unless you want update the +versions you want. When updated everyone again uses the same new version +of everything. + +=item * Carry only the requirement, not bundled modules + +Instead of bundling the modules, you only actually bundle the requirements. +Carton builds them for you when you need it. + +=back + +=head3 Setting it up + +First set up a new app: + + $ dancer2 gen -a MyApp + ... + +Delete the files that are not needed: + + $ rm -f Makefile.PL MANIFEST MANIFEST.SKIP + +Create a git repo: + + $ git init && git add . && git commit -m "initial commit" + +Add a requirement using the L format: + + $ cat > cpanfile + requires 'Dancer2' => 0.155000; + requires 'Template' => 0; + recommends 'URL::Encode::XS' => 0; + recommends 'CGI::Deurl::XS' => 0; + recommends 'HTTP::Parser::XS' => 0; + +Ask carton to set it up: + + $ carton install + Installing modules using [...] + Successfully installed [...] + ... + Complete! Modules were install into [...]/local + +Now we have two files: I and I. We +add both of them to our Git repository and we make sure we don't +accidentally add the I directory Carton created which holds +the modules it installed: + + $ echo local/ >> .gitignore + $ git add .gitignore cpanfile cpanfile.snapshot + $ git commit -m "Start using carton" + +When we want to update the versions on the production machine, +we simply call: + + $ carton install --deployment + +By using --deployment we make sure we only install the modules +we have in our cpanfile.snapshot file and do not fallback to querying +the CPAN. + +=head2 FatPacker + +L (using its command line interface, L) packs +dependencies into a single file, allowing you to carry a single file +instead of a directory tree. + +As long as your application is pure-Perl, you could create a single +file with your application and all of Dancer2 in it. + +The following example will demonstrate how this can be done: + +Assuming we have an application in I: + + package MyApp; + use Dancer2; + get '/' => sub {'OK'}; + 1; + +And we have a handler in I: + + use strict; + use warnings; + use FindBin; + use lib "$FindBin::Bin/../lib"; + use MyApp; + + MyApp->to_app; + +To fatpack it, we begin by tracing the script: + + $ fatpack trace bin/app.pl + +This creates a I file. From this we create the packlists: + + $ fatpack packlists-for `cat fatpacker.trace` > packlists + +The packlists are stored in a file called I. + +Now we create the tree using the following command: + + $ fatpack tree `cat packlists` + +The tree is created under the directory I. + +Now we create a file containing the dependency tree, and add our script to it, +using the following command: + + $ (fatpack file; cat bin/app.pl) > myapp.pl + +This creates a file called I with everything in it. Dancer2 uses +L which has a database of all MIME types and helps translate those. +The small database file containing all of these types is a binary and therefore +cannot be fatpacked. Hence, it needs to be copied to the current directory so our +script can find it: + + $ cp fatlib/MIME/types.db . + =cut