Repository files navigation

AChef cookbook to deploy applications.

The application cookbook provides a central framework to deploy applicationsusing Chef. Generally this will be web applications using things like Rails,Django, or NodeJS, but the framework makes no specific assumptions. The coreapplication resource provides DSL support and helpers, but the heavy liftingis all done in specific plugins detailed below. Each deployment starts withanapplication resource:

application'/path/to/deploy'doowner'root'group'root'# ...end

Theapplication resource uses the Poise subresource system for plugins. Thismeans you configure the steps of the deployment like normal recipe code insidetheapplication resource, with a few special additions:

application'/path/to/deploy'do# Application resource properties.owner'root'group'root'# Subresources, like normal recipe code.package'ruby'git'/path/to/deploy'dorepository'https://github.com/example/myapp.git'endapplication_rails'/path/to/deploy'dodatabase'mysql://dbhost/myapp'endend

When evaluating the recipe inside theapplication resource, it first checksforapplication_#{resource}, as well as looking for an LWRP of the same namein any cookbook starting withapplication_. This means that a resource namedapplication_foo can be used asfoo inside theapplication resource:

application'/path/to/deploy'doowner'root'group'root'rails'/path/to/deploy'dodatabase'mysql://dbhost/myapp'endend

Additionally if a resource inside theapplication block doesn't have a name,it uses the same name as the application resource itself:

application'/path/to/deploy'doowner'root'group'root'railsdodatabase'mysql://dbhost/myapp'endend

Other than those two special features, the recipe code inside theapplicationresource is processed just like any other recipe.

• application_git – Deployapplication code from a git repository.
• application_ruby – Manage Rubydeployments, such as Rails or Sinatra applications.
• application_python – ManagePython deployments, such as Django or Flask applications.
• application_javascript –Manage server-side JavaScript deployments using Node.js or io.js.
• application_java –Coming soon!
• application_go –Coming soon!
• application_erlang –Coming soon!

Chef 12 or newer is required.

Theapplication resource has top-level configuration properties for eachdeployment and acts as a container for other deployment plugin resources.

application'/opt/test_sinatra'dogit'https://github.com/example/my_sinatra_app.git'bundle_installdodeploymenttrueendunicorndoport9000endend

• :deploy – Deploy the application.(default)
• :start - Run:start on all subresources that support it.
• :stop - Run:stop on all subresources that support it.
• :restart - Run:restart on all subresources that support it.
• :reload - Run:reload on all subresources that support it.

• path – Path to deploy the application to.(name attribute)
• environment – Environment variables for all application deployment steps.
• group – System group to deploy the application as.
• owner – System user to deploy the application as.
• action_on_update – Action to run on the application resource when anysubresource is updated.(default: restart)
• action_on_update_immediately – Run theaction_on_update notification with:immediately.(default: false)

Theapplication_cookbook_file,application_directory,application_file, andapplication_templateresources extend the core Chef resources to take some application-levelconfiguration in to account:

application'/opt/myapp'dotemplate'myapp.conf'dosource'myapp.conf.erb'enddirectory'logs'end

If the resource name is a relative path, it will be expanded relative to theapplication path. If an owner or group is declared for the application, thosewill be the default user and group for the resource.

All other actions and properties are the same as the similar resource in core Chef.

Some test recipes are available as examples for common application frameworks:

• Sinatra
• Rails
• Flask
• Django
• Express

While the overall design of the revamped application resource is similar to the4.x version, some changes will need to be made. Thename property no longerexists, with the name attribute being used as the path to the deployment.Thepackages property has been removed as this is more easily handled vianormal recipe code.

The SCM-related properties likerepository andrevision are now handled bynormal plugins. If you were deploying from a private git repository you willlikely want to use theapplication_git cookbook, otherwise just use thebuilt-ingit orsvn resources as per normal.

The properties related to thedeploy resource likestrategy andsymlinkshave been removed. Thedeploy resource is no longer used so these aren'trelevant. As a side effect of this, you'll likely want to point the upgradeddeployment at a new folder or manually clean thecurrent andshared foldersfrom the existing folder. The pseudo-Capistrano layout used by thedeployresource has few benefits in a config-managed world and introduced a lot ofcomplexity and moving pieces that are no longer required.

With the removal of thedeploy resource, the callback properties and commandsare no longer used as well. Subresources no longer use the complexactions-as-callbacks arrangement as existed before, instead following normalChef recipe flow. Individual subresources may need to be tweaked to work withnewer versions of the cookbooks they come from, though most have stayed similarin overall approach.

Several of the web application deployment plugins include optional support torun database migrations from Chef. For "toy" applications where the app anddatabase run together on a single machine, this is fine and is a nice timesaver. For anything more complex I highly recommend not running databasemigrations from Chef. Some initial operations like creating the database and/ordatabase user are more reasonable as they tend to be done only once and by theirnature the application does not yet have users so some level of eventualconsistency is more acceptable. With migrations on a production application, Iencourage using Chef and the application cookbooks to handle deploying the codeand writing configuration files, but use something more specific to run theactual migration task.Fabric,Capistrano, andRundeck areall good choices for this orchestration tooling.

Migrations can generally be applied idempotently but they have uniqueconstraints (pun definitely intended) that make them tricky in a Chef-like,convergence-based system. First and foremost is that many table alterationslock the table for updating for at least some period of time. That can mean thatwhile staging the new code or configuration data can happen within a window, themigration itself needs to be run in careful lockstep with the rest of thedeployment process (eg. moving things in and out of load balancers). Beyondthat, while most web frameworks have internal idempotence checks for migrations,running the process on two servers at the same time can have unexpected effects.

Overall migrations are best thought of as a procedural step rather than adeclaratively modeled piece of the system.

Theapplication resource exposesstart,stop,restart, andreloadactions which will dispatch to any subresources attached to the application.This allows for generic application-level restart or reload signals that willwork with any type of deployment.

Additionally theaction_on_update property is used to set a defaultnotification so any subresource that updates will trigger an applicationrestart or reload. This can be disabled by settingaction_on_update false ifyou want to take manual control of service restarts.

Development sponsored byChef Software,Symonds & Son, andOrion.

The Poise test server infrastructure is sponsored byRackspace.

Copyright 2015-2016, Noah Kantrowitz

Licensed under the Apache License, Version 2.0 (the "License");you may not use this file except in compliance with the License.You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, softwaredistributed under the License is distributed on an "AS IS" BASIS,WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.See the License for the specific language governing permissions andlimitations under the License.