Guide Template

Use this template to structure your READMEs for guides. Remove text from this section, or use it to frame the guide. Good framing answers the question "Why am I learning/doing this?".

Be sure to include a recent LICENSE and Markdown linter configuration (.remarkrc). Also, include an appropriate .gitignore; these are usually found in specific technology templates, for example js-template.

Prerequisites

ga-wdi-boston/rails-api
ga-wdi-boston/rails-activerecord-crud
This guide assumes you have followed these installation instructions unequivocally.

Objectives

By the end of this, developers should be able to:

Write objectives that focus on demonstrating knowledge.
Write learning objectives that begin with an imperative verb.
Avoid objectives that start with "Use" or "Understand".
Rewrite objectives that begin with "Use" by inverting sentence structure.
End each objective with a period.

Getting Set Up

Often there will be setup instructions preceding the core objectives of the setup guide, such as create an account on foo or bar The following is an example using heroku.

Create a Heroku account, at https://www.heroku.com. You will be sent an activation email, so be sure to check your inbox so that you can activate your account.
Install the Heroku Command Line Tools: run brew install heroku.
Log into Heroku by running heroku login from the console and providing your Heroku credentials when asked. Once you log in, if you're prompted to add these credentials to your keychain, say yes. You will not be able to see your password

Create a New Heroku App

Go to the root of your repo and run heroku create. This will create an autogenerated name for your app, and add a new remote repository to your repo called heroku. View your remotes by typing git remote -v. You should see something like:

    heroku  git@heroku.com:agile-badlands-7658.git (fetch)
    heroku  git@heroku.com:agile-badlands-7658.git (push)
    origin  git@github.com:tdyer/wdi_4_rails_hw_tdd_hacker_news.git (fetch)
    origin  git@github.com:tdyer/wdi_4_rails_hw_tdd_hacker_news.git (push)

Push `master` to Heroku

Only keep clean, working code on master. After you complete a feature merge it onto master. Push your updated master to GitHub, then to Heroku.

git checkout master
git merge my-feature # merge your working code
git push # update GitHub
git push heroku master # udpate heroku

Update Heroku's Database

Once you've deployed your code, you can safely run new migrations. You'll need to do this step every time you have new migrations.

heroku run rake db:migrate

If you have seeds or examples, or if you've updated seeds or examples, you should also run them on heroku.

heroku run rake db:seed
heroku run rake db:examples

Set your Secrets

Set your environmental variables in your heroku app.

heroku config:set SECRET_KEY_BASE=$(rake secret)

heroku config:set SECRET_TOKEN=$(rake secret)

heroku config:set CLIENT_ORIGIN=https://yourgithubname.github.io

Check Your Work

Restart your application and check it out in the browser.

heroku restart
heroku open

You'll probably see something like this:

That's normal, unless you have defined a root route.

Change Your App's Name (optional)

If you wish you can rename your app at any time. It must be unique across all apps deployed to heroku.

heroku apps:rename newname

Your app will become immediately available at it's new subdomain, newname.herokuapp.com.

Heroku Command Reference

A full list of Heroku commands can be access by running heroku --help; below are some of the more common ones.

Commands	Behavior
`heroku apps:info`	Get info about ALL of our Heroku apps.
`heroku apps:info --app {name_of_app}`	Get info about a specific Heroku app.
`heroku apps:open --app {name_of_app}`	Open any given Heroku app (other than the one we're currently working with.)
`heroku logs`	Logs from the currently running app.
`heroku ps`	Processes running in your heroku application.
`heroku releases`	Each time you deploy to heroku you are creating a "release". This command shows all releases.
`heroku pg:info`	Access Postgres from within Heroku and show the heroku plan, connections, pg version, data size, tables.
`heroku pg:psql`	... and open a `psql` console.
`heroku run ...`	Run a program from within Heroku.
`heroku config`	Environmental variables in your current Heroku app.
`heroku config:set SECRET_KEY_BASE=$(rake secret)`	Set Secret Key
`heroku config:set SECRET_TOKEN=$(rake secret)`	Set TOKEN
`heroku config:set CLIENT_ORIGIN=https://yourgithubname.github.io`	Set CLIENT_ORIGIN
`heroku apps:rename newname (optional)`	Rename heroku app name (entirely optional)
`heroku restart`	restart heroku
`heroku open`	Open your heroku app in default browser
`heroku --help`	Displays a heroku CLI usage summary.

WARNING: Ephemeral Filesystem.

One serious limitation of Heroku is that it provides an 'ephemeral filesystem'; in other words, if you try to save a new file inside the repo (e.g. an uploaded image file), it will disappear when your app is restarted or redeployed.

As an example, try running the following commands:

heroku run bash
touch happy.txt; echo 'is happy' > happy.txt
cat happy.txt

Then, hit Ctrl-D to get out of heroku bash shell. If you re-open the shell and run ls -l, happy.txt will be missing!

The typical workaround is to save files in cloud storage such as Amazon S3; more on this in the near future.

Setup Guide: Checklist

Provide checklist of steps outlined above.

Run heroku create in the command line in the root of your Rails API to create a new (blank) app on Heroku.
Push your latest code to Heroku (git push heroku master)
Update your heroku database by telling Heroku to run your migration files (heroku run rake db:migrate). If you have any other rake tasks that need to run (e.g. rake db:seed), run those with heroku run as well.
Set your secrets. (Either by using the command line or by using the heroku app panel in your browser)
Check your work by restarting heroku and opening your heroku application.

Troubleshooting

Provide troubleshooting resources/gotchas if needed.

These are the commands required for deploying to heroku with rails. If your heroku deployment isn't working as expected, review these steps carefully.

heroku create
git push heroku master
heroku run rake db:migrate
heroku run rake db:seed
heroku config:set SECRET_KEY_BASE=$(rake secret)
heroku config:set SECRET_TOKEN=$(rake secret)
heroku config:set CLIENT_ORIGIN=https://yourgithubname.github.io
heroku apps:rename newname (optional)
heroku restart
heroku open

Additional Resources

License

All content is licensed under a CCBYNCSA 4.0 license.
All software code is licensed under GNU GPLv3. For commercial use or alternative licensing, please contact legal@ga.co.

ga-wdi-boston/guide-template