From 8639b8c1785578524fa49ca961f4ae8633e986a5 Mon Sep 17 00:00:00 2001 From: Will Farrington Date: Wed, 6 Feb 2013 21:24:28 -0800 Subject: [PATCH] get doc-wild --- docs/personal-configuration.md | 29 +++++++ docs/rails.md | 188 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 217 insertions(+) create mode 100644 docs/personal-configuration.md create mode 100644 docs/rails.md diff --git a/docs/personal-configuration.md b/docs/personal-configuration.md new file mode 100644 index 0000000..f76a453 --- /dev/null +++ b/docs/personal-configuration.md @@ -0,0 +1,29 @@ +# Personal Configuration + +One of the design choices of Boxen very early on was that we didn't want to +dictate down to users "you can do this, but you can't do that". +We do so as little as possible in the core, and we don't do it at all for +per-user configurations. + +How? The personal manifest. + +Personal manifests live in `modules/people/manifests/.pp`, +where `` is your GitHub username. +A basic personal manifest might look like so: + +``` puppet +class people::wfarr { + notify { 'hello world': } +} +``` + +Now, each time `wfarr` runs Boxen it'll automatically print out "hello world" +somewhere during the run. +You can even run `boxen-my-config` to generate a default template for you +and open it up in your editor. +When you're done, you can simply run `boxen` and it'll include your changes +in your personal manifest. +**You should always keep your manifest committed and pushed to your repository**. +Otherwise, auto-updates won't work! + +You can check out the [projects README](../modules/projects/README.md) for further examples. diff --git a/docs/rails.md b/docs/rails.md new file mode 100644 index 0000000..35cd487 --- /dev/null +++ b/docs/rails.md @@ -0,0 +1,188 @@ +# Using Boxen with Rails Projects + +Boxen is designed to work extremely well with Rails. +Let's break down some of the basics: + +## Project Management + +We make a few assumptions about how you run Rails in development for ease and consistency: + +* You use a web server that listens on a socket +* You use environment variables and something like [dotenv](https://github.com/bkeepers/dotenv) for managing secrets + +A typical Rails app that uses things like MySQL, Resque, and phantomjs +might have a [project definition](../modules/projects/README.md) like so: + +``` puppet +class projects::rails_app { + include phantomjs + + boxen::project { 'rails_app': + source => 'mycompany/rails_app', + ruby => '1.9.3', + mysql => true, + redis => true, + nginx => true, + } +} +``` + +This does a few things for you: + +* Clones `https://github.com/mycompany/rails_app.git` to `~/src/rails_app` +* Ensures the default 1.9.3 version of Ruby is installed +* Creates `~/src/rails_app/.ruby-version` with `1.9.3` in it +* Ensures mysql is installed and running +* Creates two mysql databases: `rails_app_test` and `rails_app_development` +* Ensures redis is installed and running +* Ensures nginx is installed and running +* Copies the [template nginx config](../modules/projects/templates/shared/nginx.conf.erb) into the nginx config dir + +It won't necessarily do all of them in that order, but it will gaurantee +that if they run successfully they're all done in a correct order. + +See the section below for some handy configuration tips on how to configure +your app best to work with Boxen. + +## Configuration + +### MySQL + +``` yaml +# config/database.yml + +<% + def boxen?; ENV['BOXEN_HOME']; end + + socket = [ + ENV["BOXEN_MYSQL_SOCKET"], + "/var/run/mysql5/mysqld.sock", + "/tmp/mysql.sock" + ].compact.detect { |f| File.exist? f } + + port = ENV["BOXEN_MYSQL_PORT"] || "3306" +%> + +development: + adapter: mysql2 + database: rails_app_development + username: root + password: +<% if socket %> + host: localhost + socket: <%= socket %> +<% else %> + host: 127.0.0.1 + port: <%= port %> +<% end %> + +test: + adapter: mysql2 + database: rails_app_test + username: root + password: +<% if socket %> + host: localhost + socket: <%= socket %> +<% else %> + host: 127.0.0.1 + port: <%= port %> +<% end %> +``` + +### PostgreSQL + +``` yaml +# config/database.yml + +development: + adapter: postgresql + database: rails_app_development + encoding: unicode + port: <%= ENV["BOXEN_POSTGRESQL_PORT"] || 5432 %> + host: localhost + +test: + adapter: postgresql + database: rails_app_test + encoding: unicode + port: <%= ENV["BOXEN_POSTGRESQL_PORT"] || 5432 %> + host: localhost +``` + +### Redis + +``` ruby +# config/initializers/redis.rb + +$redis = Redis.new(ENV['BOXEN_REDIS_URL'] || 'redis://localhost:6379/') +``` + +### Elasticsearch + +``` ruby +# config/initializers/elasticsearch.rb + +Tire.configure do + url (ENV['BOXEN_ELASTICSEARCH_URL'] || 'http://localhost:9200/') +end +``` + +### MongoDB + +``` yaml +# config/mongo.yml + +development: + host: 127.0.0.1 + port: <%= ENV['GH_MONGODB_PORT'] || 27017 %> + database: rails_app_development + +test: + host: 127.0.0.1 + port: <%= ENV['GH_MONGODB_PORT'] || 27017 %> + database: rails_app_test +``` + +### Memcached + +``` ruby +# config/initializers/memcached.rb + +$memcached = Dalli::Client.new( + ENV['BOXEN_MEMCACHED_URL'] || 'memcached://localhost:11211/' +) +``` + +### Unicorn + +``` ruby +# config/unicorn.rb + +if ENV['RACK_ENV'] == 'development' + worker_processes 1 + listen "#{ENV['BOXEN_SOCKET_DIR']}/rails_app", :backlog => 1024 + timeout 120 +end + +after_fork do |server, worker| + ActiveRecord::Base.establish_connection if defined?(ActiveRecord) +end +``` + +``` shell +# script/server + +#!/bin/sh + +set -e + +cd $(dirname "$0")/.. +: ${RAILS_ENV:=development} +: ${RACK_ENV:=development} + +export RAILS_ENV RACK_ENV + +bin/unicorn_rails -E "$RAILS_ENV" -c config/unicorn.rb +``` + -- 1.8.5.3