How to deploy the Ohana API to your Heroku account
If you've successfully deployed apps to Heroku on the computer you're using now, simply run these commands from the directory of your choice:
Follow these installation instructions.
See the customization section.
$ git push origin master$ heroku apps:create your_app_name$ script/setup_heroku your_app_nameIt's always a good idea to read the script so you know what it will install.
By default, the Heroku deployment script sets DEFAULT_PER_PAGE to 30 and MAX_PER_PAGE to 50.
You can change those settings if you want by running a command like the one below:
$ heroku config:set DEFAULT_PER_PAGE=15 -a your_heroku_app_name
Read more about all the environment variables you can configure in application.example.yml.
If you haven't already, export your database to the data directory:
$ script/export_prod_dbThis will create a filed called ohana_api_production.dump in the data folder.
Upload this file somewhere secure online, such as on Amazon S3, which allows you to create
a temporary URL for the file that expires after a configurable amount of time. Read more about importing to Heroku.
Run this command to get your Heroku database name:
$ heroku config -a your_app_nameIn the output of that command, look for a key that starts with HEROKU_POSTGRESQL. It will be followed by _SOMECOLOR_URL. For example, HEROKU_POSTGRESQL_TEAL_URL.
Run the command below to import your database to Heroku, filling in your Heroku database name and the HTTP URL for your file:
$ heroku pg:backups restore YOUR_HEROKU_DB_URL 'https://the-url-to-your-dump-file' -a your_app_nameWhen it's done, launch the app and verify that your data is available.
Heroku's free Postgres plans are limited to 10,000 total rows. This means the sum of all rows across all tables. If your dataset exceeds this limit, you'll get a warning email from Heroku. After 7 days, you'll no longer be able to add new entries to the database, but you'll still be able to read and update it. If you plan on hosting your data on a production site, it's probably a good idea to upgrade to at least the Standard Tier. Read more about the available plans.
As mentioned in application.example.yml, you can serve the API and/or admin interface on subdomains in conjunction with a custom domain name.
Even though you can't use subdomains while on the default Heroku domain name setup (app-name.herokuapp.com), you need to make sure the TLD_LENGTH config var is set to 2. If you deployed the app to Heroku using the setup_heroku script, then this was already done for you.
Once you're ready to deploy with a custom domain name (like "smc-connect.org"), you will need to set TLD_LENGTH to the number of dots in your top-level domain (TLD) name, which will most likely be 1, but
if you are using a TLD like .co.uk for example, then you should set it to 2.
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
Whenever you turn HTTPS on or off, make sure to update the OHANA_API_ENDPOINT in your Ohana Web Search instance to point to the correct version of the API. In other words, if you had already deployed a non-HTTPS version of the API, and later set ENABLE_HTTPS=yes, then you will need to update the http part of your OHANA_API_ENDPOINT (in Ohana Web Search) to https.
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, but a little more work, you can use SSLMate.
Read more about using SSL on Heroku here: http://derwiki.tumblr.com/post/107534825651/sslmate-the-simple-inexpensive-ssl-certificate
https://devcenter.heroku.com/articles/ssl-endpoint
https://devcenter.heroku.com/articles/expeditedssl
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-api 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-api && cd ohana-api
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-api 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-api, go back to https://github.com/codeforamerica/ohana-api 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-api. When it's done, you will have an ohana-api 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-api" folder by entering this command in Git Bash:
$ cd ~/Documents/GitHub/ohana-api
On a Mac, if you chose a different destination, cd to it in Terminal.
$ heroku create
Make a note of your app name, as you will need it in the next step.
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 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 API_PATH environment variable to api, run the following commmand:
$ heroku config:set API_PATH=api
Repeat this for any environment variable you want to set.
In addition to the variables listed in application.example.yml, you'll need to set three additional ones.
The first is for sending emails when people sign up on the developer and admin portals:
$ heroku config:set MAILER_URL=your_heroku_app_name.herokuapp.com
The next two variables require 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 DEVISE_SECRET_KEY=your_random_string
Generate another random string, then paste it in this command:
$ heroku config:set SECRET_TOKEN=your_other_random_string
Heroku add-ons provide a very convenient and easy way to use various development tools. heroku-postgresql allows you to store the data in a PostgreSQL database. Mandrill by MailChimp is used to send emails to developers when they sign up for an API account.
$ heroku addons:add heroku-postgresql
$ heroku addons:add mandrill
Follow the instructions in INSTALL.md.
Open settings.yml and read the instructions for more details.
$ git add .
$ git commit -m "Update values in settings.yml"
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
$ heroku run script/setup_db
You can take a break now, as this will take several minutes.
Once the setup is done, launch the app:
$ heroku open
If all went well, you should see a web page like this:
Go to /api/locations on your site.
Verify that search works by going to /api/search?keyword=food (assuming your data contains the word 'food').
Congrats!