1 line
11 KiB
JSON
1 line
11 KiB
JSON
{"name":"application","version":"5.1.0","description":"A Chef cookbook for deploying application code.","long_description":"# Application cookbook\n\n[](https://travis-ci.org/poise/application)\n[](https://rubygems.org/gems/poise-application)\n[](https://supermarket.chef.io/cookbooks/application)\n[](https://codeclimate.com/github/poise/application)\n[](https://gemnasium.com/poise/application)\n[](https://www.apache.org/licenses/LICENSE-2.0)\n\nA [Chef](https://www.chef.io/) cookbook to deploy applications.\n\n## Getting Started\n\nThe application cookbook provides a central framework to deploy applications\nusing Chef. Generally this will be web applications using things like Rails,\nDjango, or NodeJS, but the framework makes no specific assumptions. The core\n`application` resource provides DSL support and helpers, but the heavy lifting\nis all done in specific plugins detailed below. Each deployment starts with\nan `application` resource:\n\n```ruby\napplication '/path/to/deploy' do\n owner 'root'\n group 'root'\n\n # ...\nend\n```\n\nThe `application` resource uses the Poise subresource system for plugins. This\nmeans you configure the steps of the deployment like normal recipe code inside\nthe `application` resource, with a few special additions:\n\n```ruby\napplication '/path/to/deploy' do\n # Application resource properties.\n owner 'root'\n group 'root'\n\n # Subresources, like normal recipe code.\n package 'ruby'\n git '/path/to/deploy' do\n repository 'https://github.com/example/myapp.git'\n end\n application_rails '/path/to/deploy' do\n database 'mysql://dbhost/myapp'\n end\nend\n```\n\nWhen evaluating the recipe inside the `application` resource, it first checks\nfor `application_#{resource}`, as well as looking for an LWRP of the same name\nin any cookbook starting with `application_`. This means that a resource named\n`application_foo` can be used as `foo` inside the `application` resource:\n\n```ruby\napplication '/path/to/deploy' do\n owner 'root'\n group 'root'\n\n rails '/path/to/deploy' do\n database 'mysql://dbhost/myapp'\n end\nend\n```\n\nAdditionally if a resource inside the `application` block doesn't have a name,\nit uses the same name as the application resource itself:\n\n```ruby\napplication '/path/to/deploy' do\n owner 'root'\n group 'root'\n\n rails do\n database 'mysql://dbhost/myapp'\n end\nend\n```\n\nOther than those two special features, the recipe code inside the `application`\nresource is processed just like any other recipe.\n\n## Available Plugins\n\n* [`application_git`](https://github.com/poise/application_git) – Deploy\n application code from a git repository.\n* [`application_ruby`](https://github.com/poise/application_ruby) – Manage Ruby\n deployments, such as Rails or Sinatra applications.\n* [`application_python`](https://github.com/poise/application_python) – Manage\n Python deployments, such as Django or Flask applications.\n* [`application_javascript`](https://github.com/poise/application_javascript) –\n Manage server-side JavaScript deployments using Node.js or io.js.\n* `application_java` – *Coming soon!*\n* `application_go` – *Coming soon!*\n* `application_erlang` – *Coming soon!*\n\n## Requirements\n\nChef 12 or newer is required.\n\n## Resources\n\n### `application`\n\nThe `application` resource has top-level configuration properties for each\ndeployment and acts as a container for other deployment plugin resources.\n\n```ruby\napplication '/opt/test_sinatra' do\n git 'https://github.com/example/my_sinatra_app.git'\n bundle_install do\n deployment true\n end\n unicorn do\n port 9000\n end\nend\n```\n\n#### Actions\n\n* `:deploy` – Deploy the application. *(default)*\n* `:start` - Run `:start` on all subresources that support it.\n* `:stop` - Run `:stop` on all subresources that support it.\n* `:restart` - Run `:restart` on all subresources that support it.\n* `:reload` - Run `:reload` on all subresources that support it.\n\n#### Properties\n\n* `path` – Path to deploy the application to. *(name attribute)*\n* `environment` – Environment variables for all application deployment steps.\n* `group` – System group to deploy the application as.\n* `owner` – System user to deploy the application as.\n* `action_on_update` – Action to run on the application resource when any\n subresource is updated. *(default: restart)*\n* `action_on_update_immediately` – Run the `action_on_update` notification with\n `:immediately`. *(default: false)*\n\n### `application_cookbook_file`, `application_file`, `application_template`\n\nThe `application_cookbook_file`, `application_file`, and `application_template`\nresources extend the core Chef resources to take some application-level\nconfiguration in to account:\n\n```ruby\napplication '/opt/myapp' do\n template 'myapp.conf' do\n source 'myapp.conf.erb'\n end\nend\n```\n\nIf the resource name is a relative path, it will be expanded relative to the\napplication path. If an owner or group is declared for the application, those\nwill be the default user and group for the resource.\n\nAll other actions and properties are the same as the similar resource in core Chef.\n\n## Examples\n\nSome test recipes are available as examples for common application frameworks:\n\n* [Sinatra](https://github.com/poise/application_ruby/blob/master/test/cookbooks/application_ruby_test/recipes/sinatra.rb)\n* [Rails](https://github.com/poise/application_ruby/blob/master/test/cookbooks/application_ruby_test/recipes/rails.rb)\n* [Flask](https://github.com/poise/application_python/blob/master/test/cookbooks/application_python_test/recipes/flask.rb)\n* [Django](https://github.com/poise/application_python/blob/master/test/cookbooks/application_python_test/recipes/django.rb)\n* [Express](https://github.com/poise/application_javascript/blob/master/test/cookbooks/application_javascript_test/recipes/express.rb)\n\n## Upgrading From 4.x\n\nWhile the overall design of the revamped application resource is similar to the\n4.x version, some changes will need to be made. The `name` property no longer\nexists, with the name attribute being used as the path to the deployment.\nThe `packages` property has been removed as this is more easily handled via\nnormal recipe code.\n\nThe SCM-related properties like `repository` and `revision` are now handled by\nnormal plugins. If you were deploying from a private git repository you will\nlikely want to use the `application_git` cookbook, otherwise just use the\nbuilt-in `git` or `svn` resources as per normal.\n\nThe properties related to the `deploy` resource like `strategy` and `symlinks`\nhave been removed. The `deploy` resource is no longer used so these aren't\nrelevant. As a side effect of this, you'll likely want to point the upgraded\ndeployment at a new folder or manually clean the `current` and `shared` folders\nfrom the existing folder. The pseudo-Capistrano layout used by the `deploy`\nresource has few benefits in a config-managed world and introduced a lot of\ncomplexity and moving pieces that are no longer required.\n\nWith the removal of the `deploy` resource, the callback properties and commands\nare no longer used as well. Subresources no longer use the complex\nactions-as-callbacks arrangement as existed before, instead following normal\nChef recipe flow. Individual subresources may need to be tweaked to work with\nnewer versions of the cookbooks they come from, though most have stayed similar\nin overall approach.\n\n## Database Migrations and Chef\n\nSeveral of the web application deployment plugins include optional support to\nrun database migrations from Chef. For \"toy\" applications where the app and\ndatabase run together on a single machine, this is fine and is a nice time\nsaver. For anything more complex I highly recommend not running database\nmigrations from Chef. Some initial operations like creating the database and/or\ndatabase user are more reasonable as they tend to be done only once and by their\nnature the application does not yet have users so some level of eventual\nconsistency is more acceptable. With migrations on a production application, I\nencourage using Chef and the application cookbooks to handle deploying the code\nand writing configuration files, but use something more specific to run the\nactual migration task. [Fabric](http://www.fabfile.org/),\n[Capistrano](http://capistranorb.com/), and [Rundeck](http://rundeck.org/) are\nall good choices for this orchestration tooling.\n\nMigrations can generally be applied idempotently but they have unique\nconstraints (pun definitely intended) that make them tricky in a Chef-like,\nconvergence-based system. First and foremost is that many table alterations\nlock the table for updating for at least some period of time. That can mean that\nwhile staging the new code or configuration data can happen within a window, the\nmigration itself needs to be run in careful lockstep with the rest of the\ndeployment process (eg. moving things in and out of load balancers). Beyond\nthat, while most web frameworks have internal idempotence checks for migrations,\nrunning the process on two servers at the same time can have unexpected effects.\n\nOverall migrations are best thought of as a procedural step rather than a\ndeclaratively modeled piece of the system.\n\n## Application Signals and Updates\n\nThe `application` resource exposes `start`, `stop`, `restart`, and `reload`\nactions which will dispatch to any subresources attached to the application.\nThis allows for generic application-level restart or reload signals that will\nwork with any type of deployment.\n\nAdditionally the `action_on_update` property is used to set a default\nnotification so any subresource that updates will trigger an application\nrestart or reload. This can be disabled by setting `action_on_update false` if\nyou want to take manual control of service restarts.\n\n## Sponsors\n\nDevelopment sponsored by [Chef Software](https://www.chef.io/), [Symonds & Son](http://symondsandson.com/), and [Orion](https://www.orionlabs.co/).\n\nThe Poise test server infrastructure is sponsored by [Rackspace](https://rackspace.com/).\n\n## License\n\nCopyright 2015, Noah Kantrowitz\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\nhttp://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n","maintainer":"Noah Kantrowitz","maintainer_email":"noah@coderanger.net","license":"Apache 2.0","platforms":{},"dependencies":{"poise":"~> 2.4","poise-service":"~> 1.0"},"recommendations":{},"suggestions":{},"conflicting":{},"providing":{},"replacing":{},"attributes":{},"groupings":{},"recipes":{}} |