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 moment every Rails developer anticipates has arrived: deploying your application to production where real users can access it. This transition from local development to live deployment represents a crucial milestone in your development journey.

Modern Rails applications have numerous hosting options, from specialized Rails platforms to self-managed cloud servers running Ubuntu or CentOS. You can configure your own EC2 instances, use containerized deployments with Docker, or leverage Platform-as-a-Service solutions. The landscape offers unprecedented flexibility for developers in 2026.

For this tutorial, we're using Heroku—a veteran platform that continues to excel at Rails deployment despite increased competition from services like Railway, Render, and Fly.io. Heroku's strength lies in its developer-friendly approach and robust Rails integration. However, Heroku's ephemeral filesystem means uploaded files don't persist between deployments, making external storage essential. This limitation actually reflects production best practices—separating application logic from static assets improves scalability and reliability.

We'll integrate Amazon Web Services (AWS) S3 for file storage while using Heroku for application hosting. This architecture mirrors what you'll encounter in professional Rails environments. Both services offer generous free tiers that accommodate learning projects and small-scale applications, though you'll want to monitor usage as your applications grow.

Creating a Heroku Account & Installing Heroku Toolbelt

Before deploying to either platform, you'll need accounts with both Heroku and AWS. Let's start with Heroku, as it's typically the faster setup process.

1. Navigate to heroku.com in your browser

2. Click the Sign up for free button.

3. Complete the registration form with accurate information. Use an email address you can access immediately, as you'll need to verify it during this session.

4. Click Create Free Account to proceed.

5. Check your email for Heroku's confirmation message. If it doesn't appear in your inbox within a few minutes, check your spam or promotions folder.

6. Click the activation link in the email to verify your account.

7. Create a secure password when prompted, then click Set password and log in. Store this password securely—you'll need it for command-line authentication.

8. After successful login, you'll see your Heroku dashboard. Click Click here to proceed as (your email) to complete the setup process.

9. Open a new browser tab and navigate to toolbelt.heroku.com

10. Locate the Download and install section, copy the provided terminal command, paste it into your terminal, and press ENTER.

11. Run the installer and follow the installation prompts to install the Heroku CLI tools.

    Heroku Setup Requirements

    0/3

    Create Heroku account with accessible email

    You'll need to verify the account and access it during development

    Install Heroku Toolbelt from toolbelt.heroku.com

    Command-line interface for deploying and managing Heroku applications

    Set secure password and document it

    Required for Terminal authentication during deployment process

Creating an Amazon Web Services (AWS) Account

AWS setup requires more verification steps than most services, but this thorough process ensures security for what will become your cloud infrastructure foundation.

1. Navigate to AWS.amazon.com in your browser.

   IMPORTANT: Have your credit card and mobile phone ready before proceeding. While S3's free tier covers our tutorial usage, AWS requires payment method verification for all accounts. AWS will call your phone number during setup for identity verification—if you're in a classroom or quiet environment, ensure your phone is muted initially. Account activation can take up to 24 hours depending on verification complexity, so complete this step well before you need to deploy.

2. Click the Create a Free Account button to begin registration.

3. If you have an existing Amazon.com account, use those credentials for consistency.

   If you're new to Amazon services or prefer separate accounts for AWS, enter your desired email address and select I am a new user.

4. Click Sign in using our secure server. New users should follow Amazon's account creation process completely.

5. Complete your contact information accurately, accept the AWS Customer Agreement, then click Create Account and Continue.

6. Enter your payment information. AWS requires valid payment methods even for free-tier usage. The Free Tier provides 5GB of S3 storage, 20,000 GET requests, and 2,000 PUT requests monthly for your first year—more than sufficient for learning projects. After the first year, S3 costs roughly $0.023 per GB monthly. For current pricing details, visit AWS.amazon.com/s3/pricing

7. Click Continue to proceed to identity verification.

8. Verify your phone number is correct on the Identity Verification screen, then click Call Me Now. Keep this browser window active.

9. AWS will call you within moments with an automated system. Enter the PIN displayed in your browser when prompted. You can use either your keypad or speak the numbers clearly. The call typically lasts under 30 seconds.

10. After successful verification, click Continue to select your Support Plan.

11. Keep Basic (Free) selected and click Continue. The free support plan includes documentation, whitepapers, and community forums.

12. Monitor your email for account activation confirmation. This usually arrives within minutes of completing registration.

Configuring Active Storage to Store Images on Amazon S3

Now we'll configure Rails to use different storage backends for different environments—a common pattern in professional Rails applications. Local storage works perfectly for development and testing, while production requires the reliability and scalability of cloud storage.

1. Return to your code editor and open your Rails project.

2. Open config > storage.yml. Locate the commented Amazon configuration section and modify it to match this configuration (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'] %>

   Using ENV environment variables is a security best practice that keeps sensitive credentials out of your codebase. This approach prevents accidental credential exposure in version control and allows different environments to use different AWS resources.

3. Open config > environments > production.rb and locate line 39. Update it to specify Amazon S3 for production storage:

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

   This configuration ensures your production application uses S3 while development and test environments continue using local storage.

4. Save and close production.rb.

5. In your code editor, open your project's Gemfile.

6. Add the AWS SDK gem at the end of the file:

   # AWS SDK for S3 integration with Active Storage
   gem 'aws-sdk-s3'

   The AWS SDK provides the interface between Rails and S3 services, handling authentication, file transfers, and error handling.

7. Save the Gemfile and return to your terminal.

8. Install the new gem by running:

   bundle install

Creating a Git Repository

Heroku's deployment process relies entirely on Git, the industry-standard version control system. If you're not already using Git for your Rails projects, this is an excellent opportunity to establish that crucial habit. Even beyond deployment, Git is essential for professional Rails development.

NOTE: This section provides a Git quickstart for deployment purposes. For comprehensive Git workflows, consider dedicated Git training before working on team projects.

1. Switch to Terminal and navigate to your Rails project directory if you're not already there.

2. FIRST-TIME GIT USERS ONLY: Configure Git with your identity information:

   git config --local user.name "Your Full Name"
   git config --local user.email "your.email@example.com"

   Use the same email address you used for your Heroku account to maintain consistency across platforms.

3. Initialize a new Git repository in your project directory:

   git init

   This creates a hidden .git directory containing all repository metadata. Your project is now ready for version control.

4. Stage all project files for the initial commit:

   git add .

   The period represents the current directory and all subdirectories. Git will include all source code, configuration files, and assets while respecting any .gitignore rules.

5. Create your initial commit with a descriptive message:

   git commit -m "Initial commit: Rails application ready for deployment"

   Commit messages should clearly describe the changes. This practice becomes invaluable when reviewing project history or debugging issues months later.

6. Press Return to execute the commit. Git will confirm that all files have been successfully committed to your repository.

Setting up AWS S3: Creating a Bucket & Security Keys

With your AWS account ready, we'll now create the S3 infrastructure needed for file storage. This process involves creating a storage bucket and generating the security credentials Rails will use to access it.

1. Navigate to AWS.amazon.com in your browser

2. Click My Account / Console in the top-right corner of the page.

3. Select AWS Management Console from the dropdown. Sign in if prompted.

4. The AWS Console displays numerous service categories. Under the Storage section, click S3 to access Simple Storage Service.

5. Click the Create Bucket button to begin bucket creation.

   In AWS terminology, a "bucket" is a container for objects (files) in S3. Each bucket has a globally unique name and can store unlimited objects up to 5TB each. Your free tier provides 5GB of storage across all buckets.

6. Accept the default Region selection unless you have specific latency requirements.

   NOTE: For production applications, choose the region closest to your users' geographic location to minimize latency and potentially reduce costs.

7. Enter a globally unique Bucket Name. Since S3 bucket names must be unique across all AWS users worldwide, avoid generic names. Try something like rails-cookbook-yourname-2026 or cookbook-tutorial-uniquestring.

8. Click Create to create your bucket. If the name is already taken, try variations until you find an available name.

9. Record your bucket name securely—you'll need it for Heroku configuration.

   Next, we'll generate API credentials that allow Heroku to securely access your S3 bucket. These credentials consist of an Access Key ID (public) and Secret Access Key (private).

10. Click your account name in the top-right corner of the AWS console.

11. Select Security Credentials from the dropdown menu.

    AWS will display information about IAM (Identity and Access Management) best practices. For production applications, you should create dedicated IAM users with minimal required permissions rather than using root credentials.

12. For this tutorial, click Continue to Security Credentials to proceed with root access keys.

13. Expand the Access Keys (Access Key ID and Secret Access Key) section by clicking the + icon.

14. Click Create New Access Key to generate a new credential pair. Note that AWS limits accounts to two active access keys for security.

    A modal dialog will display your new access keys.

15. Click Show Access Key to reveal both the Access Key ID and Secret Access Key.

16. CRITICAL: Click Download Key File immediately. AWS will never display the Secret Access Key again after you close this dialog. Store the downloaded file securely offline—treat it like a password.

    TIP: The key file opens in spreadsheet applications like Excel. You can also copy both keys to a temporary text file for easier access during the next steps, but delete it afterward for security.

17. Close the modal and the AWS console tab. Your S3 infrastructure is now ready for integration.

Deploying Our Code to Heroku

With all prerequisites completed, we're ready to deploy your Rails application to Heroku's cloud platform. This process involves authenticating with Heroku, creating your application space, configuring environment variables, and pushing your code.

1. Return to Terminal and authenticate with Heroku:

   heroku login

2. Enter the email address associated with your Heroku account when prompted, then press Return.

3. Type your Heroku password carefully. Terminal won't display characters as you type for security reasons. If you make an error, simply try again.

   First-time authentication generates SSH keys on your local machine and registers them with Heroku, enabling secure code deployment without repeated password entry.

4. Create your Heroku application with:

   heroku create

   Heroku assigns a random name like mysterious-plateau-12345 to avoid naming conflicts. This randomization is necessary since application names must be unique across Heroku's entire platform. You can rename your application later if desired.

   This command also adds a new Git remote named "heroku" to your repository, which enables deployment via git push.

5. Now configure Heroku with your AWS credentials. Have your S3 bucket name, Access Key ID, and Secret Access Key ready from the previous steps.

6. Set your S3 bucket name (don't press Return yet):

   heroku config:set S3_BUCKET_NAME=

7. Complete the command with your actual bucket name, for example:

   heroku config:set S3_BUCKET_NAME=rails-cookbook-yourname-2026

8. Press Return to save this environment variable.

9. Configure your AWS Access Key ID:

   heroku config:set AWS_ACCESS_KEY_ID=

10. Append your Access Key ID (the public key) and press Return to save it.

11. Configure your AWS Secret Access Key:

    heroku config:set AWS_SECRET_ACCESS_KEY=

12. Append your Secret Access Key (the private key) and press Return. Handle this key with extreme care—it provides full access to your AWS resources.

13. Set the AWS region to match your S3 bucket:

    heroku config:set S3_REGION=us-east-1

14. Deploy your application to Heroku:

    git push heroku master

    This command may take several minutes on first deployment. Heroku receives your code, installs all gems specified in your Gemfile, compiles assets, and configures the runtime environment. You'll see detailed output showing each step's progress.

    NOTE: If Terminal reports authenticity concerns about heroku.com, type yes and press Return to continue. If the connection fails, simply retry the push command.

15. Delete any temporary files containing your AWS credentials now that they're securely stored in Heroku's environment.

16. Run database migrations on your Heroku application:

    heroku run rails db:migrate

    The heroku run prefix executes commands on Heroku's servers rather than locally. The output resembles local migration runs but occurs in your production environment.

17. Open your live application directly from Terminal:

    heroku open

18. Your Rails application launches in your default browser, running live on Heroku's infrastructure and accessible to users worldwide!

Testing the Production Site and Syncing Your Database

Your application is now live, but thorough testing ensures everything functions correctly in the production environment. This is also an excellent time to understand the differences between development and production databases.

1. Verify full application functionality by creating a new recipe. Use content from your development testing or create something new, but be sure to include an image upload to test S3 integration. This test confirms that your Rails application, Heroku hosting, and AWS S3 storage are working together correctly.

2. Once you