engineyard / ey-docs

Engine Yard Docs

The Engine Yard Docs

This repo holds all the content (and other bits) for the Engine Yard docs, located at EY Docs.

The inspiration of this method of documentation came from the awesome guys at Basho who have the Basho Wiki setup with Gollum.

We are using Gollum and Gollum-Site to generate the documentation. Gollum is a great piece of open source software released by the GitHub team that lets you maintain and build wikis from the contents of a Git repo.

gollum-site generates html from pages written in any format supported by Gollum (ASCIIDoc, Creole, Markdown, Textile, etc.).

## How to Contribute

Part of the reason we switched to Gollum and GitHub for the EY Docs was to make it easier for people to contribute. Just treat it like a code repo: If you have anything to change or add, simply:

1. Fork this repo

2. Build a local copy

3. Create a new Branch:

    git checkout -b <branch-name>
   

4. Add your changes

5. Commit changes to your branch

6. Send us a pull request

If it's a small or obvious change, we're likely to merge it right away. If we have questions, we'll communicate with you using the pull request's issue page.

The Gollum README provides a great introduction to using the wiki system.

## Building the Docs Locally

If you want to build and view the EY Docs locally, here is what you need to do:

1. Clone this repo:

    git clone git://github.com/engineyard/ey-docs.git
   

2. Ensure that you have Bundler installed:

    gem install bundler
   

3. Install all pre-requisite gems:

    bundle install
   

4. Generate the site and start a local server (This will take a minute. Don't fret.)

    bundle exec rake generate   # Will generate the files
    bundle exec rake serve      # Will start the gollum-site server
   

   bundle exec rake dev # Generate and run the gollum site in development mode

5. Navigate to http://localhost:3011/Home.html (Default) to access a fully-functional copy of the EY Docs.

Sanitization

You can customize sanitization with three options:

• --allow_elements: custom elements allowed, comma separated

• --allow_attributes: custom attributes allowed, comma separated

• --allow_protocols: custom protocols in href allowed, comma separated

   `$ gollum-site generate --allow_elements embed,object --allow_attributes src --allow_protocols irc`
  

## Issues, Questions, Comments, Etc.

• Create a new Issue

ey-docs's Issues

Move ruby 1.9.2 from alpha to beta

Ruby 1.9.2 is now publicly available to all customers in beta

Link to this repo from each docs page

Add 404 Page

In case people try to access a page that doesn't exist anymore.

Why is 3.0.3 the recommended Rails version?

At first I thought it was because 3.1.0 was too new, but then I remembered that the 3.0 branch was up to 3.0.10. So why do your docs on this page recommend an older version of Rails?

And why version 1.0.1 of unicorn when it is presently at version 4.1.1? Amongst others.

http://docs.engineyard.com/appcloud-tech-stack.html

Move tech stack page over

Move http://www.engineyard.com/products/technology/stack to docs.engineyard.com

404 Not Found nginx/0.7.65

Hi,

I am getting "404 Not Found nginx/0.7.65" error at the time of deploy my application. whats the solution for this problem?

Loading yml data - using yaml_db gem

Hello,

I am attempting to use the yaml_db gem to load data I exported locally. (btw if there's a better alternate to doing this let me know).

I successfully deploy and run my rake db:migrate. But I cannot run

rake db:data:load

When I do I get this:

rake aborted!
You have a nil object when you didn't expect it!
You might have expected an instance of Array.
The error occurred while evaluating nil.each
/data/spreecart/shared/bundled_gems/ruby/1.9.1/gems/yaml_db-0.2.1/lib/serialization_helper.rb:85:in `load_records'
/data/spreecart/shared/bundled_gems/ruby/1.9.1/gems/yaml_db-0.2.1/lib/serialization_helper.rb:74:in `load_table'
/data/spreecart/shared/bundled_gems/ruby/1.9.1/gems/yaml_db-0.2.1/lib/yaml_db.rb:63:in `block (2 levels) in load_documents'
/data/spreecart/shared/bundled_gems/ruby/1.9.1/gems/yaml_db-0.2.1/lib/yaml_db.rb:61:in `each'
/data/spreecart/shared/bundled_gems/ruby/1.9.1/gems/yaml_db-0.2.1/lib/yaml_db.rb:61:in `block in load_documents'
/usr/lib/ruby/1.9.1/syck.rb:235:in `call'
/usr/lib/ruby/1.9.1/syck.rb:235:in `load_documents'
/usr/lib/ruby/1.9.1/syck.rb:235:in `load_documents'
/data/spreecart/shared/bundled_gems/ruby/1.9.1/gems/yaml_db-0.2.1/lib/yaml_db.rb:60:in `load_documents'
/data/spreecart/shared/bundled_gems/ruby/1.9.1/gems/yaml_db-0.2.1/lib/serialization_helper.rb:57:in `block in load'
/data/spreecart/shared/bundled_gems/ruby/1.9.1/gems/activerecord-3.0.9/lib/active_record/connection_adapters/abstract/database_statements.rb:139:in `transaction'
/data/spreecart/shared/bundled_gems/ruby/1.9.1/gems/yaml_db-0.2.1/lib/serialization_helper.rb:56:in `load'
/data/spreecart/shared/bundled_gems/ruby/1.9.1/gems/yaml_db-0.2.1/lib/serialization_helper.rb:31:in `load'
/data/spreecart/shared/bundled_gems/ruby/1.9.1/gems/yaml_db-0.2.1/lib/tasks/yaml_db_tasks.rake:35:in `block (3 levels) in <top (required)>'
/usr/lib/ruby/gems/1.9.1/gems/rake-0.9.2/lib/rake/task.rb:205:in `call'
/usr/lib/ruby/gems/1.9.1/gems/rake-0.9.2/lib/rake/task.rb:205:in `block in execute'
/usr/lib/ruby/gems/1.9.1/gems/rake-0.9.2/lib/rake/task.rb:200:in `each'
/usr/lib/ruby/gems/1.9.1/gems/rake-0.9.2/lib/rake/task.rb:200:in `execute'
/usr/lib/ruby/gems/1.9.1/gems/rake-0.9.2/lib/rake/task.rb:158:in `block in invoke_with_call_chain'
/usr/lib/ruby/1.9.1/monitor.rb:201:in `mon_synchronize'
/usr/lib/ruby/gems/1.9.1/gems/rake-0.9.2/lib/rake/task.rb:151:in `invoke_with_call_chain'
/usr/lib/ruby/gems/1.9.1/gems/rake-0.9.2/lib/rake/task.rb:144:in `invoke'
/usr/lib/ruby/gems/1.9.1/gems/rake-0.9.2/lib/rake/application.rb:112:in `invoke_task'
/usr/lib/ruby/gems/1.9.1/gems/rake-0.9.2/lib/rake/application.rb:90:in `block (2 levels) in top_level'
/usr/lib/ruby/gems/1.9.1/gems/rake-0.9.2/lib/rake/application.rb:90:in `each'
/usr/lib/ruby/gems/1.9.1/gems/rake-0.9.2/lib/rake/application.rb:90:in `block in top_level'
/usr/lib/ruby/gems/1.9.1/gems/rake-0.9.2/lib/rake/application.rb:129:in `standard_exception_handling'
/usr/lib/ruby/gems/1.9.1/gems/rake-0.9.2/lib/rake/application.rb:84:in `top_level'
/usr/lib/ruby/gems/1.9.1/gems/rake-0.9.2/lib/rake/application.rb:62:in `block in run'
/usr/lib/ruby/gems/1.9.1/gems/rake-0.9.2/lib/rake/application.rb:129:in `standard_exception_handling'
/usr/lib/ruby/gems/1.9.1/gems/rake-0.9.2/lib/rake/application.rb:59:in `run'
/usr/lib/ruby/gems/1.9.1/gems/rake-0.9.2/bin/rake:32:in `<top (required)>'
/usr/bin/rake:19:in `load'
/usr/bin/rake:19:in `<main>'
Tasks: TOP => db:data:load

Why setup ssmtp when using external smtp relay inside rails?

The only reason I can think you might want to use ssmtp is if you cron/other jobs running on the load machine and you want to relay those messages somewhere else. Other that that, if you're using something like sendgrid, why wouldnt' you just use :smtp deliver mode? Even in that case, it doesn't make sense to use :sendmail inside the rails app to me, you should just use :smtp.

Any ideas?

"Terminate" no longer used

Need to change all phrasing that has "Terminate" to "Stop".

Add rubinius to alpha features

Can you add back "rubinius" to the list of alpha features?

Update "Getting Started" Page

Revise the "Getting Started" Page to reflect the new UI changes in AppCloud.

Remove JRuby from list of alpha features

JRuby is currently not offered

Example ey.yml snippets to be code blocks

On http://docs.engineyard.com/customize-your-deployment.html, in section "Using ey.yml to customize your deployment ", instead of environments: myapp_staging: copy_exclude: - .git I think it should be:

environments:
    myapp_staging:
      copy_exclude:
        - .git

This issue is in 3 places within this section.

The HTML looks ok, but the parent tag should be a <pre> or a <code> perhaps so it keeps its YAML structure?

Update the "BETA" sidebar

JRuby isn't in beta for example

update method signature for bundler_10_installer

The current documentation takes one parameter, but v1.4.10 of the engineyard-serverside gem takes two parameters: version, options

This is on the bottom of http://docs.engineyard.com/bundler-tips-for-appcloud.html

Move footnotes from technology stack page

We ported over the tech stage page, but we have the footnote references from the previous layout in the new one. We should remove the footnote references since we actually don't have footnotes up.

Update the Section on Keep files

Our documentation on using 'keep' files is very unclear. We need to highlight when it can be used, how it can be used, and what are the alternatives if it cannot be used for a file.

Line of code in documentation page needs to be updated

On page: http://docs.engineyard.com/asset-pipeline.html

The line:

run "cd #{release_path}; RAILS_ENV=#{rails_env} bundle exec rake assets:precompile"

should be updated to

run "cd #{release_path}; RAILS_ENV=#{framework_env} bundle exec rake assets:precompile"

collaboration_info Page

docs.engineyard.com/collaboration_info.html needs to be corrected:

• Missing images
• Bulleted list under "Are there other caveats we should be aware of during the beta program?" isn't formatted correctly.

Rubinius link 404s

Fix the link to the Rubinius homepage

How to specify specific bundler version?

Currently we use bundler 1.0.10 during deployments. If a customer wants to use a specific version of bundler, they can add the following to their application Gemfile:

gem "bundler", "1.0.18"

Then ensure you've locked your Gemfile (updated your Gemfile.lock) before deployment.

Want to confirm it's picking up your alternate bundler version? Look in your deploy logs for "1.0.18"

RSS Feed for Release Notes

Hey

For easier tracking of what is happening on the ey-cloud, it would be very with a RSS feed with the release notes on http://docs.engineyard.com/release_notes.html

"boot instances" should be changed to "boot"

I found it in "http://docs.engineyard.com/ip-addresses.html".
I found it in other pages within "docs.engineyard.com"

Sphinx version

The "Technology Stack" page specifies sphinx 0.9.9 but the system has 0.9.8.1?

http://docs.engineyard.com/appcloud-tech-stack.html

searchd --version
Sphinx 0.9.8.1-release (r1533)

Image Manipulation with CarrierWave

We are currently using CarrierWave for image uploading and resizing, what libraries are supported for resizing? I am currently using MiniMagick.

P.S. - We are hosting on the new JRuby platform.

Collaboration screenshots out of date

http://docs.engineyard.com/collaboration_info.html

Screenshots on collaboration docs are not up to date

MongoDB

Page about how to set it up with an AppCloud Account

No mention of cron jobs not being recreated in cloned environments

http://docs.engineyard.com/environment-clone.html

We should mention in this doc that we don't recreate cron jobs when an environment is cloned. We should explain that this is a conservative measure to make sure that something that should only be done in a live environment isn't carried out by mistake. E.g.: you don't want a clone emailing all your customers again mentioning daily updates that have happened, or similar.

More reasons for rebuilding-an-environment.html

Currently, we have the following:

"Why would you need to rebuild an environment?

When upgrading a Database Instance there is no way to "terminate" the separate DB instance."

We should also add:

• You want to increase the size of your /data or /db volumes
• You have a frozen/crashed app master instance in a cluster with only the one app instance (link to frozen-instances.html ?)
• You have been advised of a degraded instance or maintenance window that requires a DB master or app master in a cluster with only one app instance

ey deploy --extra-deploy-hook-options option not documented

Customer on IRC was trying to figure out how to access things set via this option. Looking at the source it seems you eventually just reference your key as if it were a method in your deploy hooks.

sendmail instructions leads to unsupported option

http://docs.engineyard.com/setup-ssmtp-for-mail-relay-to-authsmtp.html

Following this I get:
sendmail: recipients with -t option not supported

Sphinx packages / admin

I see the following are available to install under Unix packages:

app-accessibility/SphinxTrain
app-accessibility/sphinx2
app-misc/sphinx

Are there more details on these packages, ie. version? We have been using Sphinx 2.0.2 locally as 2.0.1 beta has known problems on OS/X. Also, do you have any recommended practices for Sphinx index and daemon tasks? Thanks.

Github linked account

I have followed the instructions at: http://docs.engineyard.com/linking-github-to-appcloud.html#topic2 and I cannot deploy. Each time it states: Permission denied (publickey). If it is linked why is this not working?

New Relic documentation page

I could be mistaken, but I think customers who are using Gemfiles do not need to go and add the newrelic gem through the dashboard. If so we should probably state that in the documentation that if you are using bundler and Gemiles you don't need to go through that step.

http://docs.engineyard.com/monitoring-new-relic.html

404 link on How To Use Deploy Hooks with AppCloud page

http://docs.engineyard.com/use-deploy-hooks-with-engine-yard-appcloud.html

More information link Deploy Hooks API gives 404:
http://docs.engineyard.com/deploy_hooks_api.html

Fixes to keep file list

Anal retentive changes to docs:

In the list "Files that can be keep files" on http://docs.engineyard.com/configuration-keep-files.html, change the following:

/etc/monit.d/#{name}#{appname}.monitrc --> /etc/monit.d/#{name}.#{appname}.monitrc

/etc/monit.d/unicorn_#{app.name}.monitrc --> /etc/monit.d/unicorn_#{appname}.monitrc

Also, group all the /etc/ together after all the /data/... items. I guess, I mean, sort the list alphabetically :)

Error 102: Optimistic locking failure

After a push, I get this error
Staging Application: ............Error 102: Optimistic locking failure

when I go to my homepage, I can see this one
VCAP ROUTER: 404 - DESTINATION NOT FOUND

Update Resque page

http://docs.engineyard.com/appcloud/howtos/configure-and-deploy-resque

The resque page asks customers to contact support to request the resque script, but that script is already part of ey_monit

Technology stack and AppCloud FAQ don't agree on unicorn version

http://docs.engineyard.com/technology_stack.html

unicorn
1.0.1
1.0.1
1.0.1

http://docs.engineyard.com/appcloud_faq.html#FAQ24

gem 'unicorn', '1.1.5'

If 1.0.1 is the supported version then FAQ should have '1.0.1' instead of '1.1.5'

'Node' hash in Chef recipes

On http://docs.engineyard.com/custom-chef-recipes.html, it would be useful if readers saw the keys in the 'node' hash that is available to every recipe. The Deploy Hooks API page (http://docs.engineyard.com/deploy_hooks_api.html) already has a section on how to obtain it:

"node(): Various information about the current instance and other instances in the environment. See /etc/chef/dna.json on an instance for an example of what node will return."

But for the sake of convenience, it would be nice if you had a reference page listing out all of the keys in dna.json.

ssh doesnt work for me

1. i read twice article that describe how to use ssh
2. issued public key without passphrase
3. added it to ssh public keys in admin
4. updated instance
5. tried to connect to remote instance
6. failed auth

http://my.jetscreenshot.com/2777/20110725-a20d-195kb.jpg

what can i do in this case?

http://docs.engineyard.com/amazon-out-of-capacity.html iframe issue

Video for http://docs.engineyard.com/amazon-out-of-capacity.html doesn't appear due to the iframe/markdown issue.

Incorrect Nginx paths in appcloud_update_2011_05_18.html

Multiple references to /etc/nginx/{application} should all be /etc/nginx/servers/{application}

redis on a cluster seems to think it's on localhost

I'm trying to figure out how to get redis configured to point to the db server. For some reason all my servers think it's on their machines.

Broken Link in Monitoring AppCloud Page

The link for the FitterHappier plugin is broken on http://docs.engineyard.com/monitoring_appcloud.html

Cronjobs on Utility server

Hi,

I'm having difficulty adding a custom cron job to our utility server. I've followed everything on this page:
http://docs.engineyard.com/adding-cron-jobs.html

This page says to add a new chef recipe to add the custom cron job specifically to the utility server.

Has anyone had experience doing this?

Below is the recipe:

if node[:name] == 'name_of_utility_server'
cron "centricity_checker" do
minute '*/05'
user 'deploy'
command "/data/app_name/current/lib/centricity_checker.rb >> /data/app_name/shared/log/centricity_checker.log"
end
end

AuthSMTP set up control panel step

On the page http://docs.engineyard.com/setup-ssmtp-for-mail-relay-to-authsmtp.html, I see the following line:

NOTE: If using AuthSMTP, go into the control panel and enable SSL access to your mail relay.

I don't understand this line. I've just received my account setup email from AuthSMTP, after signing up for an account with them, but can't find out where or how on the control panel to complete this step.

Thanks,
Brian

Document if before_migrate.rb runs when migrations are not selected on deploy

I was wondering if the hook will be run if you don't select the migration check box in the web UI. It's probably best to document to fact the documentation as others might wonder the same thing:
http://docs.engineyard.com/use-deploy-hooks-with-engine-yard-appcloud.html

Connecting MySQL Workbench to my hosted db

Since MySQL Query Browser is no longer available (replaced by MySQL Workbench), I can't seem to interpret correctly the data in each field of MySQL Workbench to connect to by EY database.

The fields are:
Connection Method: Standard TCP/IP over SSH

SSH Hostname - SSH server hostname, with optional port number
SSH Username - Name of the SSH user to connect with.
SSH Password - Password for the SSH tunnel.
SSH Key file - Path to SSH public key file.
MySQL Hostname - MySQL server host relative to the SSH server
MySQL Port - TCP/IP port of the MySQL server
Username - Name of the user to connect with.
Password - The MySQL user's password.
Default schema - The schema that will be used as default schema

Any ideas?

Incorrect format for deploy hooks folder structure

From http://docs.engineyard.com/use-deploy-hooks-with-engine-yard-appcloud.html under "Structure"

Instead of:

  APP_ROOT/
  deploy/
    before_migrate.rb
    before_symlink.rb
    before_restart.rb
    after_restart.rb

Remove the first line indent:

APP_ROOT/
  deploy/
    before_migrate.rb
    before_symlink.rb
    before_restart.rb
    after_restart.rb