Ubuntu Manpage: Jifty::Manual::Deploying - Deploying your application for production use

Provided by: libjifty-perl_1.10518+dfsg-3ubuntu1_all

NAME

       Jifty::Manual::Deploying - Deploying your application for production use

DESCRIPTION

       This document is intended to answer two questions:

       •   Now that you've developed your Jifty application, how do you deploy it on the
           production server?

       •   Once deployed, what's the process for performing upgrades to the production server?

       Developers and administrators may wish to use this document as a checklist to make sure
       they hit everything when deploying. This document should be updated according to the best
       practices of Jifty deployment to aid this end.

HOW TO

Installing on a Production Server
Once you've finished developing your Jifty application and you want to deploy it for use
on a production server you'll need to follow these steps:

1. Install Jifty on your production server.

2. Copy your application onto the production server.

3. Adjust the configuration to suit your production environment.

4. Deploy your production database.

5. Configure your web server.

6. Start using your production service.

Install Jifty

Jifty installation proceeds just as it did on your development machine (or machines). If
you installed from CPAN, you may do the same for your production server.

perl -MCPAN -e 'install Jifty'

or download Jifty and run:

tar zxf Jifty-VERSION.tar.gz
cd Jifty-VERSION
perl Makefile.PL
make
make test
sudo make install

You may also have installed it via the package manager available for your Linux
distribution.

Finally, you may want to use bleeding-edge features available only in the Jifty Subversion
repository. This has a slightly higher risk, but this is what the Best Practical team does
for their Jifty applications. When doing this, you will probably want to be sure to check
out the exact same version as you are using on your development machines.

Be sure to run the tests when installing Jifty to make sure there aren't any problems on
your production server that you need to fix before deploying your application.

Copy the Application

After you've gotten Jifty deployed, you need to copy your application onto the server.
This can be done in whatever way suits your project. You can run your Jifty application
straight out of the development directory just as you have on testing. Just place the
directory into an appropriate location on your server.

It may be advisable to consider using a version control system, such as SVK or Subversion,
to aid you in this process. For example, with either SVK or Subversion, any production
customizations can be handled as branches of your application to help you keep those
changes sorted out clearly. This can also help you if you make any tweaks to the code on
the production server that need to be put back into your development.

Here is an example of how to create the branch in Subversion or. This example is built
upon in the "Upgrading the Production Server" section below.

All these commands are assumed to be running on the production server in this example, but
you could do much of these from anywhere.

svn mkdir http://svn.example.com/myapp/branches
svn copy http://svn.example.com/myapp/trunk \
http://svn.example.com/myapp/branches/production
svn checkout http://svn.example.com/myapp/branches/production \
myapp
cd myapp

Make sure to remember (possibly by recording it in the log messages) which revision your
trunk was at when you ran the copy command. This will be important later. If you're using
SVK rather than Subversion, you don't have to worry about this.

In SVK:

svk mkdir //myapp/branches
svk copy //myapp/trunk //myapp/branches/production
svk checkout //myapp/branches/production myapp
cd myapp

You will now have a copy of the latest version of your project in the directory named
myapp. You can then make any of the modifications you need to to get your application
configured for the production environment (read the following sections for details).

When you're finished, commit those changes to the branch:

svn commit

or in SVK:

svk commit

All of these changes will be made only to the production branch. In the upgrade section,
it will be clearer how this will help you.

Tweak the Configuration

After you've copied your application onto the server, change into that directory and make
any changes to your configuration required for production.

Put all your site-specific changes in etc/site_config.yml and never edit etc/config.yml,
as it will be overwritten with the next application update.

Here are some things you'll want to consider changing:

AdminMode
While developing, you'll probably want to try running your application with this
turned off. This turns on the administrative functions for managing models, data, and
actions.

Set this to 0 to turn it off.

Database
These settings will be covered in more detail in "Deploy the Database".

DevelMode
This turns off certain checks that slow down a production system but are vital to fast
development. For example, with ever request to a server with "DevelMode" turned on,
the server checks to see if any of the library or template files have changed and
reloads them, if this is turned on.

By switching this setting off, you also enable extra caching and speed-up features
including the use of CSS::Squish, which helps your application load CSS files more
quickly.

LogConfig
You may wish to add this option to specify a custom logger configuration. See
Jifty::Logger.

LogLevel
Depending on your environment, you may want to adjust the default log level or you may
want to customize the log configuration by introducing an etc/log4perl.conf
configuration file.

You can set the LogLevel to: DEBUG, INFO, WARN, ERROR, or FATAL to specify the level.
If you want a custom log configuration for your server (allowing you to have per-
module log settings among other features), you need to set "LogConfig" and possibly
"LogReload". See Jifty::Logger

This configuration setting is overridden by the JIFTY_LOG_LEVEL environment variable
(if set).

LogReload
This allows you specify a custom reload period for your log configuration, if you use
"LogConfig". See Jifty::Logger.

Mailer
In some cases you will want to adjust the mailer configuration used by Jifty. The mail
configuration is used whenever Jifty::Notification messages are sent, which may or may
not be used by your application.

If you change the "Mailer" setting, be sure to also change "MailerArgs" to match.

See Jifty::Notification and Email::Send.

MailerArgs
You may want to adjust the configuration of the mailer you are using. See
Jifty::Notification and Email::Send.

Plugins
You may want to disable plugins you've been using in your development that you don't
need in production. In general, if these plugins are well-behaved this isn't
necessary, but you can provide yourself with extra insurance in case they are not.

You can disable them without removing them from the file by commenting them out using
the Perl-style "#" comment mark.

Web
BaseURL
You will want to change the "BaseURL" setting under "Web" to make sure it shows
the name of your production server's base URL.

ServeStaticFiles
If you want to improve the performance of your server, you may want your main web
server to serve static files rather than having Jifty do it. You will need to
manually flatten the static file structure yourself for this to work, but it can
be done.

etc.
Your application configuration may have additional changes that need to be made for
your application to operate properly in a production environment.

Make sure to check over all the settings to make sure they will work in your
production environment to save yourself headaches later.

Deploy the Database

If you've been developing your server using the default SQLite configuration, you will
likely want to change this for your production server. SQLite might work for production
environment, but chances are it will not.

For your production system, you will probably want to modify the "Driver" to suit your
production environment. For example, if you were going to change to use a MySQL server,
you might change your "Database" configuration in etc/site_config.yml to something like
this:

Database:
Database: myapp
Driver: mysql
Host: mysql.example.com
Password: 'secret'
RecordBaseClass: Jifty::DBI::Record::Cachable
User: myapp_user
Version: 0.0.1

In this example, the server is running the MySQL driver, connecting to the host at
"mysql.example.com" with the username "myapp_user" and password "secret".

You will need to create the database and grant access to the users according to your RDBMS
administrator documentation. In MySQL, this could be done to match the example above by
running these commands:

mysqladmin -uadmin -psecret create myapp
mysql -uadmin -psecret -e "grant all on myapp.\* to myapp_user'@'myapp.example.com identified by 'secret'"

Please refer to your RDBMS documentation for full details on how to configure your
database.

Configure the Web Server

There are several ways to configure your web server. You can use FastCGI or mod_perl or
you can use a proxy to the Jifty simple server. The first two options are what you will
most likely want to do, but the proxy configuration is presented for completeness.

Configuring FastCGI

Several configurations are explained by the "fastcgi" in Jifty::Script::FastCGI script
that comes with Jifty. It is recommended that you take one of those and modify the
configuration to suit your needs.

It may take a few tries to get the configuration exactly right. Be sure to check the
server logs for your web server when looking for problems.

Configuring mod_perl

Support for mod_perl version 2.0 is provided by Jifty::Script::ModPerl2. Remember that you
need to completely stop and start the Apache server after the Perl modules in your
application are changed.

Configuring a Proxy

You can use a proxy with the built-in server. This can be done with the following
configuration in Apache:

<Location />
ProxyPass / http://localhost:8888/
ProxyPassReverse / http://localhost:8888/
</Location>

Place that declaration in your main configuration or virtual host configuration file and
then whenever you run:

bin/jifty server

Apache will proxy your server on port 80 for you. This may not work exactly as expected
because the built-in server is intended for testing, not for a production environment. As
such, it is not well-tested as a production server.

Configure File Permissions

The <var/> subdirectory in your application should be writable by the server process. If
it runs as non-root UID (for example, FastCGI and Apache processes are usually running
under the user named apache or www or something alike), you need to change the group or
user permissions for this directory.

For example, assume your application will run under user apache and group apache. Then the
following commands should do the job:

chgrp -R apache var
chmod -R g+w var

A more flexible way would be to create a new group myapp and add apache user in it. This
allows you to maintain the application from non-root login and use "sudo" for restarting
Apache.

All Systems Go

Once you have done all of the above, your application should be ready to use at the
production address you have configured.

Updating the Production Server
After you've made some collection of updates to your Jifty application, you'll then need
to install those changes onto your server and prepare your application to use the changes.

This documentation assumes a "cold" upgrade with the application offline during the
duration of the process. A future version of this document might also include instructions
for performing a "hot" upgrade without taking the server offline.

You can do this with the following steps:

1. Shutdown the application.

2. Update the Jifty installation.

3. Update your Jifty application.

4. Merge in configuration changes.

5. Clean up any temporary and cached files.

6. Upgrade your database.

7. Start using the updated application.

Shutdown the Application

This process cannot be performed on a live server. If it is, bad things may happen. You
may choose to shutdown the application in one of two ways: turn off your web server or
reconfigure your web server into an offline mode.

Remember, shutdown all Jifty application processes before continuing, or bad things may
happen!

Shutting Down the Server

This will involve a two step process. First, you will want to shutdown your web server.
The second is to shutdown the Jifty server. If you are using the built-in Jifty server,
you may do this by running:

bin/jifty server --stop

If you are using FastCGI, you will need to locate your server's process IDs and then kill
all the processes. If this is the only FastCGI and Perl script running on your system, you
may be able to just run:

killall perl

However, that might stop too many processes in many environments, so you'll just have to
find the processes and clean them up as suits your server.

Offline Mode

If you want to provide you site visitors with some feedback letting them know that the web
site is down, you might want to provide an alternative configuration for your application.
You still need to stop all your Jifty application processes when you engage the offline
configuration.

For example, you could have the following configuration on an Apache server to run an
offline mode:

<Location />
RewriteEngine on
RewriteRule ^.*$ /offline.html
</Location>

Then create a file named "offline.html" in your server root containing the message you
wish to give your visitors.

You can make this configuration change and then restart your web server to give it effect.
Then, stop all the Jifty application processes.

Update Jifty

This is exactly the same as "Install Jifty" above. Again, you'll probably want to install
the same version as you are using to developing with. If you have not made any changes to
the Jifty version you are using, you may skip this step.

Update the Application

This is again similar to what you've done above. You just need to update all the files
that have changed. However, you should be careful not to clobber any configuration changes
that you need to remember.

If you've used the suggestion of using a branch described above, you can automatically
update your production server to use the latest code without risk of clobbering your
changes on the production server.

In Subversion, you will first need to recall the revision of either the initial copy or of
the last merge you performed. If you stored this information in the log message, you can
retrieve it by running:

svn log http://svn.example.com/myapp/branches/production

When you have the revision number, you can then merge in all the latest changes in your
production server copy. Here, I assume that the revision number is "1234".

cd myapp
svn merge -r 1234:HEAD http://svn.example.com/myapp/trunk .

If you're using SVK, you can just run the following:

cd myapp
svk smerge //myapp/trunk .

SVK automatically remembers the revision number for you so you don't have to worry about
it.

Next, watch for any conflicts that might have occurred and be sure to correct them. Check
over all the changed files and make sure they look alright and you should also run your
tests again to be sure everything is working. Once you're sure everything is correct, you
can accept the changes with:

svn commit

or:

svk commit

Your code should now be ready.

Configuration Changes

Again, you need to look for any configuration updates that need to adjusted. This is no
different from the process during the initial installation.

Clear Temporary/Cached Files

This step is important to prevent strange issues from occurring. You remove all files from
the following directories:

• var/mason/cache

• var/mason/obj

You can run the following command (BE CAREFUL TO TYPE THIS CORRECTLY OR PAY THE
CONSEQUENCES):

rm -rf var/mason/{cache,obj}/*

This means that your application will have to rebuild these cached files, which will slow
your application down slightly at first.

However, if these files are left in place, the Mason server may continue using cached
versions of files that don't match your latest updates. This will lead to very strange
problems.

Upgrade the Database

If you've made any changes to the database schema or to the structure of your data that
requires an upgrade, you will need to run:

bin/jifty schema --setup

See Jifty::Manual::Upgrading.

All Systems Go

Now that all these changes have been made, you are ready to start your web server or
reconfigure your web server for production mode and restart.

NAME

DESCRIPTION

HOW TO

SEE ALSO