Provided by: libjifty-perl_1.10518+dfsg-1ubuntu2_all bug

NAME

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

DESCRIPTION

       XXXXXXXXXXXXX: This document is intended to answer two questions:

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

       o   XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 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

       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:

       o   var/mason/cache

       o   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.

SEE ALSO

       Jifty::Manual::Tutorial, Jifty::Manual::Upgrading