README.md

opsworks_ruby Cookbook

A chef cookbook to deploy Ruby applications to Amazon OpsWorks.

Quick Start

This cookbook is designed to "just work". So in base case scenario, all you have to do is create a layer and application with an optional assigned RDS data source, then add recipes to the corresponding OpsWorks actions.

Support

• Database
  • MariaDB
  • MySQL
  • PostgreSQL
  • Sqlite3
• SCM
  • git
• Framework
  • Null (no framework)
  • hanami.rb
  • Ruby on Rails
• App server
  • Null (no appserver)
  • Puma
  • Thin
  • Unicorn
• Web server
  • Null (no webserver)
  • Apache2
  • nginx
• Worker
  • Null (no worker)
  • delayed_job
  • resque
  • sidekiq

Requirements

Cookbooks

• deployer
• ruby-ng
• nginx (~> 2.7)

Platform

This cookbook was tested on the following OpsWorks platforms:

• Amazon Linux 2016.03
• Amazon Linux 2015.09
• Amazon Linux 2015.03
• Ubuntu 14.04 LTS
• Ubuntu 12.04 LTS

In addition, all recent Debian family distrubutions are assumed to work.

Attributes

Attributes format follows the guidelines of old Chef 11.x based OpsWorks stack. So all of them, need to be placed under node['deploy'][<application_shortname>]. Attributes (and whole logic of this cookbook) are divided to six sections. Following convention is used: app == node['deploy'][<application_shortname>] so for example app['framework']['adapter'] actually means node['deploy'][<application_shortname>]['framework']['adapter'].

basic

• node['applications']
  • An array of application shortnames which should be deployed to given layer. If not provided, all detected applications will be deployed.

global

Global parameters apply to the whole application, and can be used by any section (framework, appserver etc.).

• app['environment']
  • Default: production
  • Sets the "deploy environment" for all the app-related (for example RAILS_ENV in Rails) actions in the project (server, worker, etc.)

database

Those parameters will be passed without any alteration to the database.yml file. Keep in mind, that if you have RDS connected to your OpsWorks application, you don't need to use them. The chef will do all the job, and determine them for you.

• app['database']['adapter']
  • Supported values: mariadb, mysql, postgresql, sqlite3
  • Default: sqlite3
  • ActiveRecord adapter which will be used for database connection.
• app['database']['username']
  • Username used to authenticate to the DB
• app['database']['password']
  • Password used to authenticate to the DB
• app['database']['host']
  • Database host
• app['database']['database']
  • Database name
• app['database'][<any other>]
  • Any other key-value pair provided here, will be passed directly to the database.yml

scm

Those parameters can also be determined from OpsWorks application, and usually you don't need to provide them here. Currently only git is supported.

• app['scm']['scm_provider']
  • Supported values: git
  • Default: git
  • SCM used by the cookbook to clone the repo.
• app['scm']['remove_scm_files']
  • Supported values: true, false
  • Default: true
  • If set to true, all SCM leftovers (like .git) will be removed.
• app['scm']['repository']
  • Repository URL
• app['scm']['revision']
  • Branch name/SHA1 of commit which should be use as a base of the deployment.
• app['scm']['ssh_key']
  • A private SSH deploy key (the key itself, not the file name), used when fetching repositories via SSH.
• app['scm']['ssh_wrapper']
  • A wrapper script, which will be used by git when fetching repository via SSH. Essentially, a value of GIT_SSH environment variable. This cookbook provides one of those scripts for you, so you shouldn't alter this variable unless you know what you're doing.
• app['scm']['enabled_submodules']
  • If set to true, any submodules included in the repository, will also be fetched.

framework

Pre-optimalization for specific frameworks (like migrations, cache etc.). Currently hanami.rb and Rails are supported.

• app['framework']['adapter']
  • Supported values: null, rails
  • Default: rails
  • Ruby framework used in project.
• app['framework']['migrate']
  • Supported values: true, false
  • Default: true
  • If set to true, migrations will be launch during deployment.
• app['framework']['migration_command']
  • A command which will be invoked to perform migration. This cookbook comes with predefined migration commands, well suited for the task, and usually you don't have to change this parameter.
• app['framework']['assets_precompile']
  • Supported values: true, false
  • Default: true
• app['framework']['assets_precompilation_command']
  • A command which will be invoked to precompile assets.

rails

• app['framework']['envs_in_console']
  • Supported values: true, false
  • Default: false
  • If set to true, rails console will be invoked with all application-level environment variables set.

appserver

Configuration parameters for the ruby application server. Currently Puma, Thin and Unicorn are supported.

• app['appserver']['adapter']
  • Default: puma
  • Supported values: puma, thin, unicorn, null
  • Server on the application side, which will receive requests from webserver in front. null means no appserver enabled.
• app['appserver']['application_yml']
  • Supported values: true, false
  • Default: false
  • Creates a config/application.yml file with all pre-configured environment variables. Useful for gems like figaro
• app['appserver']['dot_env']
  • Supported values: true, false
  • Default: false
  • Creates a .env file with all pre-configured environment variables. Useful for gems like dotenv

unicorn

• app['appserver']['accept_filter']
  • Default: httpready
• app['appserver']['backlog']
  • Default: 1024
• app['appserver']['delay']
  • Default: 0.5
• app['appserver']['preload_app']
  • Supported values: true, false
  • Default: true
• app['appserver']['tcp_nodelay']
  • Supported values: true, false
  • Default: true
• app['appserver']['tcp_nopush']
  • Supported values: true, false
  • Default: false
• app['appserver']['tries']
  • Default: 5
• app['appserver']['timeout']
  • Default: 50
• app['appserver']['worker_processes']
  • Default: 4

puma

• app['appserver']['preload_app']
  • Supported values: true, false
  • Default: true
• app['appserver']['log_requests']
  • Supported values: true, false
  • Default: false
• app['appserver']['thread_max']
  • Default: 16
• app['appserver']['thread_min']
  • Default: 0
• app['appserver']['timeout']
  • Default: 60
• app['appserver']['worker_processes']
  • Default: 4

thin

• app['appserver']['max_connections']
  • Default: 1024
• app['appserver']['max_persistent_connections']
  • Default: 512
• app['appserver']['timeout']
  • Default: 60
• app['appserver']['worker_processes']
  • Default: 4

webserver

Webserver configuration. Proxy passing to application is handled out-of-the-box. Currently Apache2 and nginx is supported.

• app['webserver']['adapter']
  • Default: nginx
  • Supported values: apache2, nginx, null
  • Webserver in front of the instance. It runs on port 80, and receives all requests from Load Balancer/Internet. null means no webserver enabled.
• app['webserver']['dhparams']
  • If you wish to use custom generated DH primes, instead of common ones (which is a very good practice), put the contents (not file name) of the dhparams.pem file into this attribute. Read more here.
• app['webserver']['ssl_for_legacy_browsers']
  • Supported values: true, false
  • Default: false
  • By default webserver is configured to follow strict SSL security standards, covered in this article. However, old browsers (like IE < 9 or Android < 2.2) wouldn't work with this configuration very well. If your application needs a support for those browsers, set this parameter to true.

apache

• app['webserver']['extra_config']
  • Raw Apache2 configuration, which will be inserted into <Virtualhost *:80> section of the application.
• app['webserver']['extra_config_ssl']
  • Raw Apache2 configuration, which will be inserted into <Virtualhost *:443> section of the application. If set to true, the extra_config will be copied.
• app['webserver']['limit_request_body']
  • Default: 1048576
• app['webserver']['keepalive_timeout']
  • Default: 15
• app['webserver']['log_level']
  • Default: info
• app['webserver']['log_dir']
  • Default: /var/log/apache2 (debian) or /var/log/httpd (rhel)
  • A place to store application-related Apache2 logs.
• app['webserver']['proxy_timeout']
  • Default: 60

nginx

• app['webserver']['build_type']
  • Supported values: default or source
  • Default: default
  • The way the nginx cookbooks handles nginx installation. Check out the corresponding docs for more details. Never use node['nginx']['install_method'], as it will be always overwritten by this attribute.
• app['webserver']['client_body_timeout']
  • Default: 12
• app['webserver']['client_header_timeout']
  • Default: 12
• app['webserver']['client_max_body_size']
  • Default: 10m
• app['webserver']['extra_config']
  • Raw nginx configuration, which will be inserted into server section of the application for HTTP port.
• app['webserver']['extra_config_ssl']
  • Raw nginx configuration, which will be inserted into server section of the application for HTTPS port. If set to true, the extra_config will be copied.
• app['webserver']['log_dir']
  • Default: /var/log/nginx
  • A place to store application-related nginx logs.
• app['webserver']['keepalive_timeout']
  • Default: 15
• app['webserver']['proxy_read_timeout']
  • Default: 60
• app['webserver']['proxy_send_timeout']
  • Default: 60
• app['webserver']['send_timeout']
  • Default: 10

Since this driver is basically a wrapper for nginx cookbook, you can also configure node['nginx'] attributes as well (notice that node['deploy'][<application_shortname>] logic doesn't apply here.)

worker

Configuration for ruby workers. Currenty delayed_job, Resque and Sidekiq are supported. Every worker is covered by monitd daemon out-of-the-box.

• app['worker']['adapter']
  • Default: null
  • Supported values: null, delayed_job, resque, sidekiq
  • Worker used to perform background tasks. null means no worker enabled.
• app['worker']['process_count']
  • ** Default:** 2
  • How many separate worker processes will be launched.
• app['worker']['syslog']
  • Default: true
  • Supported values: true, false
  • Log worker output to syslog?

sidekiq

• app['worker']['config']
  • Configuration parameters which will be directly passed to the worker. For example, for sidekiq they will be serialized to sidekiq.yml config file.

delayed_job

• app['worker']['queues']
  • Array of queues which should be processed by delayed_job

resque

• app['worker']['workers']
  • Default: 2
  • Number of resque workers
• app['worker']['queues']
  • Default: *
  • Array of queues which should be processed by resque

Recipes

This cookbook provides five main recipes, which should be attached to corresponding OpsWorks actions.

• opsworks_ruby::setup - attach to Setup
• opsworks_ruby::configure - attach to Configure
• opsworks_ruby::deploy - attach to Deploy
• opsworks_ruby::undeploy - attach to Undeploy
• opsworks_ruby::shutdown - attach to Shutdown

Contributing

Please see CONTRIBUTING for details.

Author and Contributors

Author: Igor Rzegocki <igor@rzegocki.pl>

Contributors

• Phong Si (@phongsi)
• Nathan Flood (@npflood)
• Marcos Beirigo (@marcosbeirigo)

License

License: MIT