How to deploy Ohana Web Search to your Heroku account
-
Your computer is already configured to deploy apps to Heroku (i.e. you have successfully deployed apps to Heroku in the past).
-
You have already deployed your own instance of Ohana API with your own data.
-
You will want to customize your app first before deploying to Heroku, otherwise your deployment will look just like the generic demo version.
Follow these installation instructions if you haven't already installed the app.
Read carefully through all the options in settings.yml and make any customizations that suit your needs.
$ git push origin master$ heroku apps:create your_app_name$ script/setup_heroku -a your_app_name -o your_api_endpoint
your_api_endpoint is the URL to your instance of Ohana API, such as http://ohana-api-demo.herokuapp.com/api. It's always a good idea to read the script so you know what it will install.
The setup_heroku script above will take a few minutes to run, and when it's done, you'll see the following messages:
All done pushing code.
You can now visit your site at http://your_app_name.herokuapp.com
Visit your site to make sure everything went well.
If something went wrong and you see a placeholder site that looks like the screenshot below, then jump to the pushing your code to Heroku section.
Jump to the Google Analytics section if you want to set that up for your instance.
Jump to the Time Zone configuration section if you want to set that up for your instance.
Don't be daunted by the length of this tutorial. I'm very thorough and I explain things along the way so you're not just blindly running commands.
- Go to http://heroku.com and sign up for an account.
- Click on the link in the email from Heroku to confirm your account.
- Visit your Heroku account page.
- Scroll all the way down to the Billing section, and click on "Add Credit Card." A credit card is required to be able to add the necessary add-ons (even the free ones).
Instructions for Windows: https://toolbelt.heroku.com/windows
Instructions for Mac: https://toolbelt.heroku.com/osx
Launch the command line application on your computer.
Mac: Launch the application called Terminal, which is installed by default on all Macs. You can find it in the Utilities folder inside the Applications folder (screenshot). You can also use Spotlight (click on the magnifying glass icon at the top right of your Mac's screen) to search for "Terminal", then press return to launch it. iTerm2 is another popular command line application for Mac.
Windows: Launch the Git Bash application that was installed by the Heroku toolbelt. There should be a shortcut to the Git Bash app on your Desktop (screenshot of the icon). If the commands in the sections below don't work in Git Bash, you might have to use cmd.exe. To launch cmd.exe (or MS-DOS), follow the instructions here for the version of Windows you are using.
From now on, you will be copying and pasting (or typing) a lot of commands in your command line app. They will be designated in this tutorial like so:
$ some command you will run
Whether you're using Terminal on a Mac or Git Bash on Windows, the $ will appear automatically at the end of the command prompt after every command that you run. If you're using cmd.exe on Windows instead of Git Bash, the prompt will end with the > sign. For example, C:\WINDOWS>, as seen in this screenshot.
You will not be copying and pasting or typing the $, only what comes after it. After entering the command, you will press "return" or "enter" on your keyboard to execute the command.
$ heroku login
Enter your Heroku email and password.
Press Y if you see this message about a public key:
Could not find an existing public key.
Would you like to generate one? [Yn]
You can either do this via the command line or via github.com. If you don't already have a GitHub account or the GitHub application for Mac or Windows, then the command line will probably be faster.
Command Line:
Go to the directory (or folder) where you want to save the code for the ohana-web-search repository. I like to save all the projects I'm working on in a folder called "projects." Whether you're using Terminal on a Mac, or Git Bash on Windows, if your "projects" folder is in your "Documents" folder, you would go to it with this command:
$ cd ~/Documents/projects
cd stands for "change directory", and the tilde ~ is a Unix shortcut for your user's home directory.
If you don't already have a folder called "projects," you can create it with this command:
$ mkdir projects
If you're not already in the "Documents" folder, you can go to the "Documents" folder and create the "projects" folder in it with one command by using the handy && in Unix, which lets you combine commands like so:
$ cd ~/Documents && mkdir projects
To see which folder you're in at any given time, use this command:
$ pwd
pwd stands for "print working directory."
To view the contents of a directory:
$ ls
Now that we've covered a few Unix basics, you can clone the app:
$ git clone https://github.com/codeforamerica/ohana-web-search && cd ohana-web-search
You can skip to the create an app on Heroku section now.
GitHub:
If you don't already have a GitHub account, sign up for one, then sign in.
Go to https://github.com/codeforamerica/ohana-web-search and click on the Clone in Desktop button (see screenshot below). If prompted to download "GitHub for Mac" or "GitHub for Windows," do so and install the app.
Once GitHub is installed and running, log in with your GitHub credentials.
If GitHub for Mac or Windows doesn't automatically start cloning ohana-web-search, go back to https://github.com/codeforamerica/ohana-web-search and click on the Clone in Desktop button. On Windows, if you get a prompt asking you if you want to allow the website to open a program, click Allow. On Windows, the GitHub app should now start cloning ohana-web-search. When it's done, you will have an ohana-web-search folder under /Documents/GitHub in your user's home directory. On a Mac, GitHub lets you choose the destination folder.
On Windows, go to the "ohana-web-search" folder by entering this command in Git Bash:
$ cd ~/Documents/GitHub/ohana-web-search
On a Mac, if you chose a different destination, cd to it in Terminal.
$ heroku create
This will create an app with a random name, Make a note of your app name, as you will need it in the next step. If you prefer to name your app yourself, specify it with this command:
$ heroku create:apps your_app_name
From now on, all the Heroku commands you will run will assume that you only have one app in your Heroku account. If you have multiple apps in your Heroku account, you will need to append the app name to the end of the command, like this:
$ heroku command --app your_app_name
Environment variables allow you to keep sensitive and confidential information such as passwords, API keys, and secret tokens out of your public GitHub repository. They also allow you to define parameters that could change depending on the environment. For example, since the Ohana API is an open-source project that can be deployed by different people on different domain names, we wouldn't want to hardcode the URL for the API. So, in the ohanapi.rb file, instead of setting config.api_endpoint to http://ohanapi.herokuapp.com/api (which is the URL of the original Ohana API), we tell it to look first in ENV["OHANA_API_ENDPOINT"] to let people like you, who want to deploy their own version of the API, to set the OHANA_API_ENDPOINT environment variable to their own API URL. Read more about this recommended practice in the Config section of The Twelve-Factor App.
Now that we understand why, let's set our first environment variable, OHANA_API_ENDPOINT:
$ heroku config:set OHANA_API_ENDPOINT=your_api_url/api
your_api_url/api would be something like http://ohanapi.herokuapp.com/api
The next one will set the DOMAIN_NAME variable that is used to set a cookie for the Google Translate feature:
$ heroku config:set DOMAIN_NAME=herokuapp.com
Next, we will set the CANONICAL_URL variable that will come in handy if you ever set up a custom domain name for your Heroku app. You can read more about this variable in production.rb:
$ heroku config:set CANONICAL_URL=your_app_name.herokuapp.com
Note that even if you're still using the herokuapp.com domain, you still need to set CANONICAL_URL, otherwise your site will never load.
The next variable requires that you generate a random 128-character string. There are many ways to generate a random string from the command line. Here is one of them that should work on both Mac and Windows:
$ cat /dev/random | LC_CTYPE=C tr -dc "[:alnum:]" | head -c 128 && echo
If that doesn't work, you can generate a random string on the Random String Generator website. Type in "128" in the "String Length" field, uncheck the "Uppercase Letters (A-Z)" checkbox, then click the "Generate" button, as seen in the screenshot below.
Whether you generated the string from the command line or the website, copy the string, then paste it after the = in the command below:
$ heroku config:set SECRET_TOKEN=your_other_random_string
Heroku add-ons provide a very convenient and easy way to use various development tools. Mandrill by MailChimp is used to send emails to you when people submit feedback from the site. Memcachier allows you to cache various portions of the site to speed it up, and so you don't have to make a new API request for every page visit. New Relic is a great monitoring tool that can also be used to make sure your Heroku app never goes to sleep, even if it's only using 1 dyno.
$ heroku addons:add memcachier
$ heroku addons:add newrelic
$ heroku addons:add mandrill
You are now finally ready to push to Heroku:
$ git push heroku master
If you get a message that the authenticity of the host heroku.com can't be established, type yes.
If it starts pushing, you can skip to the next step.
If instead, you get Permission denied (publickey), it means Heroku can't find your SSH key. Generate a new key by running this command:
$ ssh-keygen -t rsa -C "[email protected]"
Press enter when you see this prompt:
Enter file in which to save the key:
Enter a passphrase when prompted, and then enter it again to confirm. Your passphrase can, and should, include spaces to make it harder to crack. See this GitHub article on working with SSH key passphrases.
Add your SSH key to your Heroku account:
$ heroku keys:add ~/.ssh/id_rsa.pub
Then try to push again. Press the up arrow key until you get to git push heroku master, then press return.
On a Mac, follow the aforementioned GitHub article to avoid having to enter the passphrase every time you want to push to Heroku or GitHub.
On Windows, it doesn't seem to be as user-friendly (for development in general, OS X is recommended over Windows). Once you've launched Git Bash, you can set your passphrase once, and it will remember it as long as you keep Git Bash running. Once you quit and relaunch Git Bash, you will need to enter your passphrase again. If you know a way around this, please feel free to edit this Wiki page.
Tell Git Bash to remember your passphrase for the session:
$ eval $(ssh-agent)
$ ssh-add
Once the setup is done, launch the app:
$ heroku open
If all went well, you should see a web page like this:
Congrats!
If you have a Google Analytics account you want to use with your app, just set your ID and your domain name as environment variables on Heroku:
$ heroku config:set GOOGLE_ANALYTICS_ID=your_id -a your_heroku_app_name
$ heroku config:set GOOGLE_ANALYTICS_DOMAIN=your_domain_name -a your_heroku_app_name
An example ID is UA-40905632-1, and an example domain is smc-connect.org.
Note that you must have a Universal Analytics property for the tracking to work.
When you visit a location (example), the Last updated time that is displayed at the bottom right of the page is set to UTC by default. If you would like to set it to a more appropriate time zone where most of your visitors live, you can set the TZ environment variable on Heroku to one of the accepted values. For example, to set the Heroku time zone to Eastern Time, you would run the following command:
$ heroku config:set TZ=America/New_York -a your_heroku_app_name