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 the customization documentation and make any changes 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 https://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.
Learn how to allow search engines to index your site.
Jump to the Google Analytics section if you want to set that up for your instance.
Learn how to set up SSL for your custom domain.
If you want to precompile production assets locally, you'll want to make sure your production DOMAIN_NAME config var is set correctly in application.yml. Because the DOMAIN_NAME variable is used inside a JS file, it will get set at precompilation time, which means that the app will only work properly on that same domain name. Therefore, to be able to test the app on a staging server, you'll need to set up a subdomain for your staging server. For example, if your production DOMAIN_NAME is smc-connect.org, you would host your staging server at staging.smc-connect.org.
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).
The Heroku Command Line Interface (CLI) was formerly known as the Heroku Toolbelt.
Heroku CLI Installation instructions for Windows and Mac: https://devcenter.heroku.com/articles/heroku-cli
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. Another advantage is that you can make changes in a production environment (such as Heroku) by simply changing the value of the environment variable, as opposed to making code changes and having to push them to apply the new setting. Read more about this recommended practice in the Config section of The Twelve-Factor App.
To learn about all the environment variables you can configure, read the comments in application.example.yml.
Setting an environment variable on Heroku is very easy, and always follows the same pattern:
$ heroku config:set ENV_VAR=value
For example, to set the OHANA_API_ENDPOINT environment variable to http://ohana-api-demo.herokuapp.com/api, run the following commmand:
$ heroku config:set OHANA_API_ENDPOINT=http://ohana-api-demo.herokuapp.com/api
Repeat this for any environment variable you want to set, making sure to at least set the required ones: OHANA_API_ENDPOINT, DOMAIN_NAME, and CANONICAL_URL.
In addition to the variables listed in application.example.yml, you'll also need to set SECRET_TOKEN
to 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.
$ heroku addons:add memcachier
$ 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 "your_email@example.com"
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!
Note that search engines are blocked by default so that they don't index your site until it's ready.
Once your site is serving your own data from your own instance of Ohana API, and once you're satisfied with the content on your site, then you can invite search engines to index your site by commenting out lines 4 and 5 in public/robots.txt, like so:
# User-agent: *
# Disallow: /
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.
Once you've deployed your app to Heroku and verified that it works, you'll most likely want to use a custom domain name to make your site look more official. Because the app is configured to use SSL by default, you'll need to obtain and configure an SSL certificate first. This is highly recommended to encrypt the passwords entered by the users of the admin and developer portals.
If you need to temporarily turn off SSL on Heroku, you can set the ENABLE_HTTPS environment variable to a value other than yes. For example:
heroku config:set ENABLE_HTTPS=no -a your_heroku_app_name
Note that SSL support is provided by default for *.herokuapp.com domains and is free. Obtaining an SSL certificate is only required if you want to use a custom domain name. If you have the money, and prefer to use a service that takes care of everything for you, you can use the Expedited SSL add-on on Heroku. For much less money, and just a few more minutes of your time, you can use SSLMate.
Read more about using SSL on Heroku here: http://derwiki.tumblr.com/post/107534825651/sslmate-the-simple-inexpensive-ssl-certificate