Deployment with Heroku & AWS S3

Topics covered in this Ruby on Rails tutorial:

Creating Heroku & Amazon Web Services accounts, Adding the gems that Heroku needs, Configuring Active Storage to store images on Amazon S3, Setting up AWS S3: creating a bucket & security keys, Deploying our code to Heroku

Exercise Overview

The big day is finally here! We’re going to push our little application out into the world.

There are lots of options for hosting your Rails app, including plenty of Rails-specific ones. You can also create your own cloud server running some flavor of Linux and configure that to run Rails. The sky is the limit!

One of the easiest and most popular options is Heroku, so we’re going to try them out here. Heroku is a web hosting service that specializes in easily deploying Ruby on Rails apps. The only downside to their nifty, easy-to-use service is that they don’t have a way to let users upload files to their system. They recommend integrating with Amazon Web Services to store images and other user-uploaded content in their S3 cloud storage service. (You can also use Microsoft, Google, or other cloud storage providers.)

We’ll use Amazon Web Services (AWS) to host all of our images and use Heroku to get our site up and running. It’s all going to integrate together really easily. Both of these services are completely free for small deployments like ours.

Creating a Heroku Account & Installing Heroku Toolbelt

Before you can work with Heroku and Amazon Web Services, you will need to sign up for both services. Let’s create a Heroku account first.

1. Open a browser and go to heroku.com

2. Click the Sign up for free button.

3. Enter the required information. You should use an email account you can access in class.

4. Once you’re finished, click Create Free Account.

5. To see Heroku’s confirmation email, log in to the email account you used to sign up with. If you don’t see it, check your Junk folder.

6. Click the activation link in the email.

7. Enter your desired password twice, then click Set password and log in. Write it down if needed, since you’ll need to type it into Terminal later.

8. You’ll be directed to a page that welcomes you to Heroku. Click the link that says Click here to proceed as (your email).
   You should now be viewing your Heroku dashboard!

9. In a new browser tab, go to toolbelt.heroku.com

10. Scroll down to where it says Download and install and copy and paste the supplied terminal command into your terminal and hit enter.

11. Open the installer and follow the instructions to install Heroku Toolbelt.

    Other Hosting Options

    We’ve focused on Heroku and Amazon S3 here for two simple reasons:

    1. They’re very popular with Rails developers.
    2. They offer a free basic usage tier for hobbyists.

    That said, there are plenty of alternatives out there. Another popular web hosting service that offers Rails-specific support is Engine Yard. Like Heroku, it provides its own gems and has its own ways of helping get your site up and running. Additionally, many Rails sites are simply hosted on conventional cloud providers such as Amazon EC2 or Rackspace.

    For cloud storage, there are many good choices. Google Cloud and Microsoft Azure both provide comparable cloud storage options with competitive pricing (and Active Storage integration), and many smaller competitors also exist.

Creating an Amazon Web Services (AWS) Account

1. To sign up for Amazon Web Services, open aws.amazon.com in a browser.

   NOTE: Before you sign up, make sure you have your credit card and phone within reach. The services we’ll be using are free, but you will still need to provide Amazon with a valid credit card to use their services. AWS will briefly autodial you toward the end of the account setup, so if you are in a class at Noble Desktop, make sure to mute your phone before going on to the next step. Account creation can take up to 24 hours with bank validation, should be done in advance.

2. Click the Create a Free Account button.

3. If you already have an Amazon.com account, use the email associated with your Amazon.com account and enter your password.

   If you don’t have an Amazon.com account, have a non-U.S. Amazon account, or prefer to create a new login to test out AWS, enter the email address you wish to use and select I am a new user.

4. Click Sign in using our secure server. If you’re a new user, follow Amazon’s directions to create a new account.

5. Fill out your contact info, check the box below AWS Customer Agreement, then click Create Account and Continue.

6. Enter your payment information. While you need to enter your credit card details, you will be able to use AWS for free for a year as long as your usage stays within the limits written on the Payment Information screen. We won’t be exceeding the limits in this exercise, so there will be no cost to complete this exercise. For more information on the cost of storage after the first year, go to the following webpage: aws.amazon.com/s3/pricing

7. Click Continue.

8. In the Identity Verification screen, make sure your phone number is correct, then click Call Me Now. Keep the browser window open.

9. You will receive an automated call from Amazon Web Services. Enter the PIN shown in the browser window. (You can either type or speak the numbers.) The call will end once they confirm your PIN. Don’t worry, it’ll take less than a minute.

10. Once your identity is verified, click Continue to select your Support Plan.

11. Keep Basic (Free) selected and click Continue.

12. Check your email for a confirmation message that your account was activated. You should receive it shortly after completing your registration.

Configuring Active Storage to Store Images on Amazon S3

So far, Active Storage has been storing all of our uploaded images on a local server. While this is fine while we’re building our app locally on the computer (the development environment) or running our test suite (the test environment), we want to store our files on AWS’s S3 cloud storage system when we are in the production environment.

1. Switch back to your code editor.

2. Open config > storage.yml. Time to uncomment that Amazon S3 chunk of code! Edit it so it looks like this (changes in bold):

   amazon:
     service: S3
     access_key_id: <%= ENV['AWS_ACCESS_KEY_ID'] %>
     secret_access_key: <%= ENV['AWS_SECRET_ACCESS_KEY'] %>
     region: <%= ENV['S3_REGION'] %>
     bucket: <%= ENV['S3_BUCKET_NAME'] %>
   

   ENV is short for environment variable. These secure values are used a lot on Heroku. We’ll set them later; for now we just need to get them into the file.

3. By default, Rails has three files in its config folder—one for each environment. Open config > environments > production.rb and change line 39:

     # Store uploaded files on Amazon S3.
     config.active_storage.service = :amazon
   

4. Save and close production.rb.

5. In your code editor, open cookbook > Gemfile.

6. At the end of the file, add the following code:

   # Use aws-sdk-s3 to configure Rails to use Amazon Web Services
   gem 'aws-sdk-s3'
   

7. Save the file.

8. Switch to the Terminal and type the following:

   bundle

Creating a Git Repository

Heroku was engineered to push all of its code around using the Git source code management (SCM) system, so before we can upload our site to Heroku, we need to create a Git repository with all of our app’s code in it.

NOTE: This section will briefly walk you through creating a Git repository. It is recommended that you familiarize yourself with using Git before continuing this exercise.

1. Switch to Terminal. If you have used Git before, skip the next step.

2. NEW GIT USERS ONLY: enter your name and email into Terminal as follows:

   git config --local user.name "your name"
   git config --local user.email "youremail"
   

3. Create a new Git repository with this command:

   git init
   

   This creates an empty repository. While this command doesn’t put any code in the repository, it gets it ready to start working.

4. Add the entire contents of our current directory (the cookbook folder) to our repository by inputting the following bold command:

   git add .
   

   NOTE: A Git repository only manages an app’s source code, which is why it’s called a source code management system. It does not back up our database.

5. The next step is to commit (save) the changes. Type in the following command, including a commit message in double quotation marks:

   git commit -m "initial commit of cookbook"
   

   Any time you change something in your source code, you need to commit it to Git. The best practice is to log a message with each commit that explains the changes. These are very helpful days, months, or even years down the road!

6. Hit Return. You’ll see that Git committed all the files in the cookbook folder.

Setting Up AWS S3: Creating a Bucket & Security Keys

We’re just about ready to push our site to Heroku! Before we can finally do that, our last task is to set up S3 cloud storage on Amazon Web Services.

1. In a browser, go to aws.amazon.com

2. Click on the My Account / Console button at the top right of the window.

3. Select AWS Management Console. If you’re not already signed in, enter your account information.

4. You’ll see a menu with all the categories and types of services offered by AWS. We’re only interested in cloud storage, so under the Storage heading, click on the S3 link.

5. Toward the top left, click the Create Bucket button.

   “Bucket” is simply Amazon’s name for a container that stores the objects you want to store in the S3 service. AWS allows you to have any number of buckets on your free account as long as the files stored in them total 5 GB or less.

6. We don’t have to worry about the Region. Leave the default selected.

   NOTE: If you were to create a bucket for a real-world project in the future, you’d want to select the one closest to your physical location so you get the minimum possible latency (lag time between an image request on your site and data retrieval from Amazon’s server).

7. Bucket names are shared across the entire Amazon S3 service. For this reason, you won’t be able to use a generic name like app, store, or even nutty! Enter a Bucket Name that you think will be unique, such as cookbook-yourname123.

8. Click Create. If your bucket name wasn’t taken yet, you’ll see some details about your new bucket. If you need to, try again with another name.

9. Write your bucket name down since you’ll need it soon.

   We need two more pieces of data before we can set up our site. Heroku needs an API access key and an API access secret in order to make a secure connection to our S3 bucket and upload files to it.

10. To get that, go to the top right of the window and click on your name.

11. Click the Security Credentials link.

    You will see a modal window that mentions an AWS best practice. This screen refers to creating multiple users with limited permissions. If you’re going to do anything serious with Amazon Web Services (such as making a real production site), you will want to read up about IAM Users later and set up separate users.

12. In this class, we’re just using the free account and we don’t have to worry about identity and access management. Click Continue to Security Credentials.

13. On the Your Security Credentials screen, click the + next to Access Keys (Access Key ID and Secret Access Key) to open up that section.

14. Click Create New Access Key. For future reference, note that you can only have two active or inactive access keys at a time.

    A modal pops up. Success, it created both keys for you!

15. Click the Show Access Key link.

16. If you do not click the Download Key File button before closing the modal, you will never be able to retrieve the secret access key again! Click the button to download the key file. Once that file is on your own computer, make sure to store it in a secure location offline.

    NOTE: If you click on it, the key file will open in your default spreadsheet program (Excel, etc.). You can also copy both keys and paste them in a TXT file for easier access. Just make sure the info is handy, since we’ll need it soon.

17. Close the modal, then the browser window or tab. We’re done setting up AWS!

Deploying Our Code to Heroku

Now that we have all the settings that we need now to get our Heroku app configured, we’re ready to deploy our app to the cloud for all to see!

1. Switch to Terminal and type the following command to log in to Heroku:

   heroku login
   

2. It will prompt you for your Heroku credentials. Enter the email you used to sign up for Heroku, then hit Return.

3. Type in your Heroku password. Terminal will not show the password as you type, so enter it carefully. If you make a mistake, just type it again.

   If you’ve never logged in to Heroku before, this command will generate a key file on your computer. It will copy that info to Heroku, making it so you’re now able to deploy code to Heroku’s servers.

4. Type the following command to create a new Heroku app:

   heroku create
   

   Heroku will generate a random name for your app, such as vast-savannah-7319. For now, just stick with whatever name you get. For information about how to rename a Heroku app, read the sidebar at the end of the exercise.

   Just like on Amazon Web Services, Heroku app names are shared across the entire service, so once a user assigns a name to their app, no one else can use that name. As you can guess, you won’t be able to use a generic name like nutty here either. Heroku recommends letting them choose a random name for you at first, then renaming your app when you’re ready start sharing it.

5. Now we need to configure Heroku to use the AWS info that we copied earlier. Make sure your bucket name, access key id, and secret access key is handy.

6. First up, you need to enter the name of the bucket you created earlier. Type the following and do not hit Return until we say so:

   heroku config:set S3_BUCKET_NAME=
   

7. After the equal sign, enter the name of your bucket. The entire line should look something like this, though your bucket name will be different:

   heroku config:set S3_BUCKET_NAME=cookbook-yourname123
   

8. Hit Return to apply the command.

9. We need to enter the heroku config:set command three more times. Next up, you’ll need to enter your AWS access key id (the public one). Type the beginning of the command as shown below:

   heroku config:set AWS_ACCESS_KEY_ID=
   

10. After the equal sign, enter your Access Key id. Once it’s entered, press Return.

11. One more piece of AWS info to enter! Type the following bold code:

    heroku config:set AWS_SECRET_ACCESS_KEY=
    

12. After the equal sign, enter your Secret Access Key, then press Return.

13. Finally, set the region:

    heroku config:set S3_REGION=us-east-1
    

14. That’s all it takes to get Heroku to get set up! Now we can start pushing our code to a Heroku server. Type the following command:

    git push heroku master
    

    This command may take a little while to finish executing, especially if it’s your first time using Heroku. This command pushes our code up to Heroku by running bundle on Heroku to install all of the gems in our Gemfile, as well as doing other things to get the Heroku server ready for our app.

    NOTE: If Terminal says something like the authenticity of host heroku.com can’t be established, and asks if you want to continue connecting, type yes and hit Return. If it tells you the connection was closed, type the previous command again: git push heroku master

15. If you copied your AWS credentials to a TXT file, delete it now. We’re done entering that info.

16. Just like we’ve been doing on the local server throughout the class, our next task is to run rails db:migrate. The only difference is we need to run them on Heroku by starting the command with heroku run. Type:

    heroku run rails db:migrate
    

    The output will look familiar to what you’ve seen when running rake db:migrate on the local machine.

17. Once Heroku is done seeding our Postgres database, we should be able to visit our site in a browser. But let’s use a nifty shortcut that will open it right from Terminal:

    heroku open
    

18. The site pops up in your default browser. Our site is up and running in real time on Heroku’s server!

Testing the Production Site and Syncing Your Database

1. The page should work just like our site, except that now anyone in the world can access it. To confirm, try adding a recipe. You can use the sample recipe from earlier, or invent one of your own. Be sure to add a picture!

2. Once you have some content up on your live site, let’s try taking a backup, and syncing it locally. From your Terminal, run the command:

   heroku pg:backups capture
   

3. This should start a backup running. Once it’s done, run:

   curl -o cookbook.dump `heroku pg:backups public-url`
   

   This will download a file called cookbook.dump to your Mac. This is the backup of your database.

4. To restore it, run:

   pg_restore --clean --no-acl --no-owner -n public -h localhost -U cookbook -d cookbook cookbook.dump
   

5. Visit http://localhost:3000 to see your new recipe locally. Now you can easily download your live site and try things out locally without disrupting your visitors!