At some point in your application's lifecycle, you're going to run the application on a machine other than your development environment. In this chapter we'll cover packaging your application (for internal or CPAN release) and running that package in a production environment with a real web server. As many deployment options can change from time to time, you can check http://wiki.catalystframework.org/wiki/deployment for up-to-date deployment information.
The first step in deploying your application is to copy your application from your development/build environment to your production environment. This may sound trivial, but it's important to make sure that your process is easy and repeatable. If you require every step to be done manually, it's likely that at some point (under the pressure of short maintenance windows), something will be missed and your users will be unhappy. Are you sure you remembered to install every dependency, update the source tree on every server in the farm, change permissions, and edit configuration files appropriately?
Fortunately, Catalyst makes it easy to carry out the deployment correctly. If you've been diligent about keeping the dependencies in your Makefile.PL up-to-date, then you'll find it very easy to manage dependencies and the application itself.
Let's start with a quick run-through of the Makefile.PL build process. We will use Makefile.PL twice, once on the build system (to build the package) and again on the target system, to build the application itself.
The first step is to run Makefile.PL on your development or build system as follows:
$ perl Makefile.PL
This will generate a Makefile that includes some useful targets—make dist, make test, make clean, make manifest, make distclean, and many others. Before we build a distribution, we'll want to run make distclean to delete any non-code that has accumulated during the development process. Unfortunately, as the Makefile is considered a temporary file, it will be removed in this step. After the distclean, re-run Makefile.PL to regenerate the Makefile.
Now that you have a clean working directory, you can generate a manifest file containing a list of the files in your application. make manifest will do this automatically and save the results in a file called MANIFEST. If this file looks good, you're ready for the next step. If it contains entries that aren't a part of your application, then create a file called MANIFEST.SKIP to indicate paths to skip. A MANIFEST.SKIP that I usually use looks like this:
.git/ blib pm_to_blib MANIFEST.bak MANIFEST.SKIP~ cover_db Makefile$ Makefile.old$
The format is one regular expression per line. If a file's full path is matched by any regular expression in the file, then it will be skipped over when building the manifest.
You can test the skip list by re-running make manifest. That command will inform you of what it added to, or removed from the manifest based on the new skip rules.
When the manifest is to your liking, all that's left to do is to actually build the package with make dist. The make dist command will build a compressed TAR file of your application called MyApp-0.01.tar.gz that contains the source (and Makefile.PL) of your application, suitable for uploading to the CPAN or copying to another system to install. The 0.01 in the filename is the version number that can be changed by editing the our $VERSION = '0.01' line in your application's main file, lib/MyApp.pm. Traditionally, versions start at 0.01 and are increased by 0.01 on each release. Test releases are marked with a version number, an underscore, and another number, such as 0.01_01 (note that 0.01_01 sorts after 0.01). Many utilities assume this convention, so it's good to stick to it even if you don't plan to release your code to the world.
With this package built, the final step is to copy the tarball to your deployment server. On that machine, simply run:
$ tar xzvf MyApp-0.01.tar.gz
$ cd MyApp
$ perl Makefile.PL
$ make && make test
That will extract the application, generate the Makefile, install all the dependencies that Makefile.PL mentions and finally, run the application's automated test suite. If all goes well, you're ready to point your web server at the application directory.
If your build environment and production are at the same platform, you can save some time and trouble by deploying a PAR package instead of manually building a tarball. A PAR file is a Perl Archive, a self-contained Perl application. It will contain your application and all the dependencies, which means that you can copy a single file to all of your production machines and have your application "Just Work".
Building a PAR is usually as simple as adding a line that says:
catalyst_par();
to your Makefile.PL, running Makefile.PL, and then running make catalyst_par. The PAR packer will examine your application to determine its dependencies and then generate an archive that bundles the dependencies, your application, and the scripts to run the application together in a file called myapp.par. To run your application, put the PAR file somewhere convenient and then run parl myapp.par <script>, where the script is myapp_server.pl, myapp_fastcgi.pl, myapp_test.pl, and so on. The PAR will unpack itself and then execute the requested command.
Note that the command is parl, not Perl; it's included in the PAR CPAN distribution, which must be installed on the target system.
Sometimes the auto-scanning of your application might not pick up all the dependencies; you can manually add a list of dependencies to always include, by including the following line inside Makefile.PL:
catalyst_par_classes(qw/A::Dependency Another::Dependency .../);
It's likely that your development and production environments will require different configuration files. Catalyst provides a few ways to handle this. The most flexible is to maintain separate configuration files for each instance of your application (development, staging, QA, production, and so on) and set the MYAPP_CONFIG environment variable to point to the correct file on each environment.
If there is a lot of configuration that overlaps between the instances, then that approach might not be ideal. Catalyst has a concept of local configuration files that you can use instead. If there is an environment variable called MYAPP_CONFIG_LOCAL_SUFFIX set, then Catalyst will supplement the default configuration (say, myapp.yml) with a file named myapp_<suffix>.yml. The default suffix is local, so if you have only two environments to configure, then you can put your development-specific settings in the local file and simply copy the myapp_local.yml file to production.
If you have more than two environments, put the bulk of your config in myapp.yml, then create a myapp_envname.yml for each environment. Then just set the MYAPP_CONFIG_LOCAL_SUFFIX environment variable appropriately, and you're set.
Note
If you use the hostname as the suffix, you can say MYAPP_CONFIG_LOCAL_SUFFIX='hostname'; then even the environment variable setting is identical between machines.
Alternatively, you can specify configuration directly as environment variables with the Catalyst::Plugin::ConfigLoader::Environment extension.