application/metadata.json

{
  "name": "application",
  "description": "Deploys and configures a variety of applications defined from databag 'apps'",
  "long_description": "Application cookbook\n====================\n\nThis cookbook is initially designed to be able to describe and deploy web applications. Currently supported:\n\n* Rails\n* Java\n* Django\n\nOther application stacks (PHP, etc) will be supported as new recipes at a later date.\n\nThis cookbook aims to provide primitives to install/deploy any kind of application driven entirely by data defined in an abstract way through a data bag.\n\n---\nRequirements\n============\n\nChef 0.8 or higher required.\n\nThe following Opscode cookbooks are dependencies:\n\n* runit\n* unicorn\n* passenger_apache2\n* tomcat\n* python\n* gunicorn\n\nThe following are also dependencies, though the recipes are considered deprecated, may be useful for future development.\n\n* `ruby_enterprise`\n* `passenger_enterprise`\n\n---\nRecipes\n=======\n\nThe application cookbook contains the following recipes.\n\ndefault\n-------\n\nSearches the `apps` data bag and checks that a server role in the app exists on this node, adds the app to the run state and uses the role for the app to locate the recipes that need to be used. The recipes listed in the \"type\" part of the data bag are included by this recipe, so only the \"application\" recipe needs to be in the node or role `run_list`.\n\nSee below regarding the application data bag structure.\n\ndjango\n------\n\nUsing the node's `run_state` that contains the current application in the search, this recipe will:\n\n* create an application specific virtualenv\n* install required packages and pips\n* set up the deployment scaffolding\n* creates settings_local.py file with the database connection information if required\n* performs a revision-based deploy\n\nThis recipe can be used on nodes that are going to run the application, or on nodes that need to have the application code checkout available such as supporting utility nodes or a configured load balancer that needs static assets stored in the application repository.\n\nFor pip requirements.txt files: ensure the requirements.txt file is present in the root of the application code (APP_ROOT/requirements.txt) or named after the node's current app_environment in a directory named requirements (requirements/production.txt) and `pip install -r` will be run before migrations.\n\nIn order to manage running database migrations (python manage.py migrate), you can use a role that sets the `run_migrations` attribute for the application (`my_app`, below) in the correct environment (production, below). Note the data bag item needs to have migrate set to true. See the data bag example below.\n\n    {\n      \"name\": \"my_app_run_migrations\",\n      \"description\": \"Run db:migrate on demand for my_app\",\n      \"json_class\": \"Chef::Role\",\n      \"default_attributes\": {\n      },\n      \"override_attributes\": {\n        \"apps\": {\n          \"my_app\": {\n            \"production\": {\n              \"run_migrations\": true\n            }\n          }\n        }\n      },\n      \"chef_type\": \"role\",\n      \"run_list\": [\n      ]\n    }\n\nSimply apply this role to the node's run list when it is time to run migrations, and the recipe will remove the role when done.  Since Django does not have a standard database migration function built into the core framework, we assume the popular [South framework](http://south.aeracode.org/) is being used.\n\ngunicorn\n--------\n\nRequires `gunicorn` cookbook.\n\nGunicorn is installed, default attributes are set for the node and an app specific gunicorn config and runit service are created.\n\n`java_webapp`\n-----------\n\nUsing the node's `run_state` that contains the current application in the search, this recipe will:\n\n* install required packages\n* set up the deployment scaffolding\n* create the context configuration for the servlet container\n* performs a `remote_file` deploy.\n\nThe servlet container context configuration (`context.xml`) exposes the following JNDI resources which can be referenced by the webapp's deployment descriptor (web.xml):\n\n* A JDBC datasource for all databases in the node's current `app_environment`.  The datasource uses the information (including JDBC driver) specified in the data bag item for the application.\n* An Environment entry that matches the node's current `app_environment` attribute value.  This is useful for loading environment specific properties files in the web application. \n\nThis recipe assumes some sort of build process, such as Maven or a Continuous Integration server like Hudson, will create a deployable artifact and make it available for download via HTTP (such as S3 or artifactory).\n\n`passenger_apache2`\n-------------------\n\nRequires `apache2` and `passenger_apache2` cookbooks. The `recipe[apache2]` entry should come before `recipe[application]` in the run list.\n\n    \"run_list\": [\n      \"recipe[apache2]\",\n      \"recipe[application]\"\n    ],\n\nSets up a passenger vhost template for the application using the `apache2` cookbook's `web_app` definition. Use this with the `rails` recipe, in the list of recipes for a specific application type. See data bag example below.\n\nrails\n-----\n\nUsing the node's `run_state` that contains the current application in the search, this recipe will:\n\n* install required packages and gems\n* set up the deployment scaffolding\n* creates database and memcached configurations if required\n* performs a revision-based deploy.\n\nThis recipe can be used on nodes that are going to run the application, or on nodes that need to have the application code checkout available such as supporting utility nodes or a configured load balancer that needs static assets stored in the application repository.\n\nFor Gem Bundler: include `bundler` or `bundler08` in the gems list.  `bundle install` or `gem bundle` will be run before migrations.  The `bundle install` command is invoked with the `--deployment` and `--without` flags following [Bundler best practices](http://gembundler.com/deploying.html).\n\nFor config.gem in environment: `rake gems:install RAILS_ENV=<node environment>` will be run when a Gem Bundler command is not.\n\nIn order to manage running database migrations (rake db:migrate), you can use a role that sets the `run_migrations` attribute for the application (`my_app`, below) in the correct environment (production, below). Note the data bag item needs to have migrate set to true. See the data bag example below.\n\n    {\n      \"name\": \"my_app_run_migrations\",\n      \"description\": \"Run db:migrate on demand for my_app\",\n      \"json_class\": \"Chef::Role\",\n      \"default_attributes\": {\n      },\n      \"override_attributes\": {\n        \"apps\": {\n          \"my_app\": {\n            \"production\": {\n              \"run_migrations\": true\n            }\n          }\n        }\n      },\n      \"chef_type\": \"role\",\n      \"run_list\": [\n      ]\n    }\n\nSimply apply this role to the node's run list when it is time to run migrations, and the recipe will remove the role when done.\n\ntomcat\n-------\n\nRequires `tomcat` cookbook.\n\nTomcat is installed, default attributes are set for the node and the app specific context.xml is symlinked over to Tomcat's context directory as the root context (ROOT.xml).\n\nunicorn\n-------\n\nRequires `unicorn` cookbook.\n\nUnicorn is installed, default attributes are set for the node and an app specific unicorn config and runit service are created.\n\n---\nDeprecated Recipes\n==================\n\nThe following recipes are deprecated and have been removed from the cookbook. To retrieve an older version, reference commit 4396ce6.\n\n`passenger-nginx`\n`rails_nginx_ree_passenger`\n\n---\nApplication Data Bag \n=====================\n\nThe applications data bag expects certain values in order to configure parts of the recipe. Below is a paste of the JSON, where the value is a description of the key. Use your own values, as required. Note that this data bag is also used by the `database` cookbook, so it will contain database information as well. Items that may be ambiguous have an example.\n\nThe application used in examples is named `my_app` and the environment is `production`. Most top-level keys are Arrays, and each top-level key has an entry that describes what it is for, followed by the example entries. Entries that are hashes themselves will have the description in the value.\n\nNote about \"type\": the recipes listed in the \"type\" will be included in the run list via `include_recipe` in the application default recipe based on the type matching one of the `server_roles` values.\n\nNote about packages, the version is optional. If specified, the version will be passed as a parameter to the resource. Otherwise it will use the latest available version per the default `:install` action for the package provider.\n\nRail's version additional notes\n-------------------------------\n\nNote about `databases`, the data specified will be rendered as the `database.yml` file. In the `database` cookbook, this information is also used to set up privileges for the application user, and create the databases.\n\nNote about gems, the version is optional. If specified, the version will be passed as a parameter to the resource. Otherwise it will use the latest available version per the default `:install` action for the package provider.\n\nAn example is data bag item is included in this cookbook at `examples/data_bags/apps/rails_app.json`.\n\nJava webapp version additional notes\n------------------------------------\n\nNote about `databases`, the data specified will be rendered as JNDI Datasource `Resources` in the servlet container context confiruation (`context.xml`) file. In the `database` cookbook, this information is also used to set up privileges for the application user, and create the databases.\n\nAn example is data bag item is included in this cookbook at `examples/data_bags/apps/java_app.json`.\n\nDjango version additional notes\n-------------------------------\n\nNote about `databases`, the data specified will be rendered as the `settings_local.py` file. In the `database` cookbook, this information is also used to set up privileges for the application user, and create the databases.\n\nNote about pips, the version is optional. If specified, the version will be passed as a parameter to the resource. Otherwise it will use the latest available version per the default `:install` action for the python_pip package provider.\n\nThe `local_settings_file_name` value may be used to supply an alternate name for the environment specific `settings_local.py`, since Django projects do not have a standard name for this file.\n\nAn example is data bag item is included in this cookbook at `examples/data_bags/apps/django_app.json`.\n\n---\nUsage\n=====\n\nTo use the application cookbook, we recommend creating a role named after the application, e.g. `my_app`. This role should match one of the `server_roles` entries, that will correspond to a `type` entry, in the databag. Create a Ruby DSL role in your chef-repo, or create the role directly with knife.\n\n    % knife role show my_app\n    {\n      \"name\": \"my_app\",\n      \"chef_type\": \"role\",\n      \"json_class\": \"Chef::Role\",\n      \"default_attributes\": {\n      },\n      \"description\": \"\",\n      \"run_list\": [\n        \"recipe[application]\"\n      ],\n      \"override_attributes\": {\n      }\n    }\n\nAlso recommended is a cookbook named after the application, e.g. `my_app`, for additional application specific setup such as other config files for queues, search engines and other components of your application. The `my_app` recipe can be used in the run list of the role, if it includes the `application` recipe.\n\nYou should also have a role for the environment(s) you wish to use this cookbook. Similar to the role above, create the Ruby DSL file in chef-repo, or create with knife directly.\n\n    % knife role show production\n    {\n      \"name\": \"production\",\n      \"chef_type\": \"role\",\n      \"json_class\": \"Chef::Role\",\n      \"default_attributes\": {\n        \"app_environment\": \"production\"\n      },\n      \"description\": \"production environment role\",\n      \"run_list\": [\n\n      ],\n      \"override_attributes\": {\n      }\n    }\n\nThis role uses a default attribute so nodes can be moved into other environments on the fly simply by modifying their node object directly on the Chef Server.\n\n---\nLicense and Author\n==================\n\nAuthor:: Adam Jacob (<adam@opscode.com>)\nAuthor:: Joshua Timberman (<joshua@opscode.com>)\nAuthor:: Seth Chisamore (<schisamo@opscode.com>)\n\nCopyright 2009-2011, Opscode, Inc.\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\n    http://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": "Opscode, Inc.",
  "maintainer_email": "cookbooks@opscode.com",
  "license": "Apache 2.0",
  "platforms": {
  },
  "dependencies": {
    "runit": [

    ],
    "unicorn": [

    ],
    "apache2": [

    ],
    "passenger_apache2": [

    ],
    "tomcat": [

    ],
    "python": [

    ],
    "gunicorn": [

    ]
  },
  "recommendations": {
  },
  "suggestions": {
  },
  "conflicting": {
  },
  "providing": {
  },
  "replacing": {
  },
  "attributes": {
  },
  "groupings": {
  },
  "recipes": {
    "application": "Loads application databags and selects recipes to use",
    "application::django": "Deploys a Django application specified in a data bag with the deploy_revision resource",
    "application::gunicorn": "Sets up the deployed Django application with Gunicorn as the web server",
    "application::java_webapp": "Deploys a Java web application WAR specified in a data bag with the remote_file resource",
    "application::passenger_apache2": "Sets up a deployed Rails application as a Passenger virtual host in Apache2",
    "application::rails": "Deploys a Rails application specified in a data bag with the deploy_revision resource",
    "application::tomcat": "Sets up the deployed Java application with Tomcat as the servlet container",
    "application::unicorn": "Sets up the deployed Rails application with Unicorn as the web server"
  },
  "version": "0.99.4"
}