diff --git a/README.md b/README.md index 7ee3ec9..c7cd3dd 100644 --- a/README.md +++ b/README.md @@ -47,7 +47,7 @@ gem 'rundoc' Run the `rundoc build` command on any markdown file ```sh -$ rundoc build --path my/path/to/run_doc.md +$ bin/rundoc build --path ``` > Note: This command will create and manipulate directories in the working directory of your source markdown file. Best practice is to have your source markdown file in its own empty directory. diff --git a/test/fixtures/rails_4/rundoc.md b/test/fixtures/rails_4/rundoc.md index c134f98..b532660 100644 --- a/test/fixtures/rails_4/rundoc.md +++ b/test/fixtures/rails_4/rundoc.md @@ -12,14 +12,17 @@ end https://github.com/schneems/rundoc/blob/main/test/fixtures/rails_4/rundoc.md --> +> warning +> This article is archived. It is no longer receiving updates. It is presented here for historical reference only. +> We cannot guarantee that any statements made are correct or that the instructions will still work. +> This version of Rails is [no longer supported by Ruby core](https://guides.rubyonrails.org/maintenance_policy.html). +> If you are starting a new application, we recommend you use the most recently released version of Rails. + >warning >As of November 28th, 2022, free Heroku dynos, free Heroku Postgres and free Heroku Data for Redis plans are [no longer available](https://blog.heroku.com/next-chapter). > >We recommend using our [low-cost plans](https://blog.heroku.com/new-low-cost-plans) to complete this tutorial. Eligible students can apply for platform credits through our new [Heroku for GitHub Students program](https://blog.heroku.com/github-student-developer-program). -> warning -> The latest version of Rails available is [Rails 7](https://devcenter.heroku.com/articles/getting-started-with-rails7). If you are starting a new application we recommend you use the most recently released version. - Ruby on Rails is a popular web framework written in [Ruby](http://www.ruby-lang.org/). This guide covers using Rails 4 on Heroku. For information about running previous versions of Rails on Heroku, see [Getting Started with Rails 3.x on Heroku](getting-started-with-rails3). > callout If you are already familiar with Heroku and Rails, reference the [simplifed Rails 4 on Heroku guide](https://devcenter.heroku.com/articles/rails4) instead. For general information on how to develop and architect apps for use on Heroku, see [Architecting Applications for Heroku](https://devcenter.heroku.com/articles/architecting-apps). @@ -496,6 +499,36 @@ end Confirm it works locally, then push to Heroku. -## Done +## Next Steps + +Congratulations on deploying a Rails 5 application! To continue exploring, review the following articles next: + +* Visit the [Ruby support category](/categories/ruby-support) to learn more about using Ruby and Rails on Heroku. +* The [Deployment category](/categories/deployment) provides a variety of powerful integrations and features to help streamline and simplify your deployments. + +## Deleting your app and Add-on + +If you don't need this application and database, you can now remove them from your account. You'll only be charged for the resources you used. + +>warning +>This will remove your add-on you'll lose any data saved in the database. + +```term +$ heroku addons:destroy heroku-postgresql +``` + +>warning +>This will delete your application + +```term +$ heroku apps:destroy +``` + +You can confirm that your add-on and app are gone with the commands: + +```term +$ heroku addons --all +$ heroku apps -all +``` -You now have your first application deployed to Heroku. The next step is to deploy your own application. If you're interested in reading more you can read more about [Ruby on Heroku at the Devcenter](https://devcenter.heroku.com/categories/ruby). +You're now ready to deploy your app. diff --git a/test/fixtures/rails_5/rundoc.md b/test/fixtures/rails_5/rundoc.md index 592d610..feb8a45 100644 --- a/test/fixtures/rails_5/rundoc.md +++ b/test/fixtures/rails_5/rundoc.md @@ -15,18 +15,21 @@ end $ bin/rundoc build --path test/fixtures/rails_5/rundoc.md --> +> warning +> This article is archived. It is no longer receiving updates. It is presented here for historical reference only. +> We cannot guarantee that any statements made are correct or that the instructions will still work. +> This version of Rails is [no longer supported by Ruby core](https://guides.rubyonrails.org/maintenance_policy.html). +> If you are starting a new application, we recommend you use the most recently released version of Rails. + >warning >As of November 28th, 2022, free Heroku dynos, free Heroku Postgres and free Heroku Data for Redis plans are [no longer available](https://blog.heroku.com/next-chapter). > >We recommend using our [low-cost plans](https://blog.heroku.com/new-low-cost-plans) to complete this tutorial. Eligible students can apply for platform credits through our new [Heroku for GitHub Students program](https://blog.heroku.com/github-student-developer-program). -> warning -> The latest version of Rails available is [Rails 7](https://devcenter.heroku.com/articles/getting-started-with-rails7). If you are starting a new application we recommend you use the most recently released version. - Ruby on Rails is a popular web framework written in [Ruby](http://www.ruby-lang.org/). This guide covers using Rails 5 on Heroku. For information on running previous versions of Rails on Heroku, see the tutorial for [Rails 4.x](getting-started-with-rails4) or [Rails 3.x](getting-started-with-rails3). ``` -:::-- $ ruby -e "exit 1 unless RUBY_VERSION == '2.7.2'" +:::-- $ ruby -e "exit 1 unless RUBY_VERSION == '2.7.8'" ``` For this guide you will need: @@ -75,6 +78,8 @@ Then move into your application directory. ```term :::>- $ cd myapp +:::>> $ bundle lock --add-platform x86_64-linux --add-platform ruby +:::>- $ bundle install ``` Create a database locally: @@ -173,7 +178,7 @@ Rails 5 requires Ruby 2.2.0 or above. Heroku has a recent version of Ruby instal ```ruby :::-- $ sed -i'' -e '/^ruby/d' ./Gemfile :::-> file.append Gemfile#4 -ruby "2.7.2" +ruby "2.7.8" ``` You should also be running the same version of Ruby locally. You can check this by running `$ ruby -v`. You can get more information on [specifying your Ruby version on Heroku here](https://devcenter.heroku.com/articles/ruby-versions). @@ -244,14 +249,7 @@ Provision a Postgresql database using Add-ons. >A `mini` Postgres size costs [$5 a month, prorated to the minute](https://elements.heroku.com/addons/heroku-postgresql). At the end of this tutorial, you will be prompted to [delete your database](https://devcenter.heroku.com/articles/heroku-postgresql#removing-the-add-on) to minimize costs. ```term -$ heroku addons:create heroku-postgresql:mini -Creating heroku-postgresql:mini on ⬢ shrouded-anchorage-34700... $5/month -Database has been created and is available - ! This database is empty. If upgrading, you can transfer - ! data from another database with pg:copy - -Created postgresql-encircled-75487 as DATABASE_URL -Use heroku addons:docs heroku-postgresql to view documentation +:::>> $ heroku addons:create heroku-postgresql:mini ``` Your Heroku app now has access to a Postgresql database. The credentials are stored in the `DATABASE_URL` environment variable, which Rails will connect to by convention. @@ -475,9 +473,36 @@ end Confirm it works locally, then push to Heroku. -## Next steps +## Next Steps -Congratulations! You have deployed your first Rails 5 application to Heroku. Here's some recommended reading: +Congratulations on deploying a Rails 5 application! To continue exploring, review the following articles next: * Visit the [Ruby support category](/categories/ruby-support) to learn more about using Ruby and Rails on Heroku. * The [Deployment category](/categories/deployment) provides a variety of powerful integrations and features to help streamline and simplify your deployments. + +## Deleting your app and Add-on + +If you don't need this application and database, you can now remove them from your account. You'll only be charged for the resources you used. + +>warning +>This will remove your add-on you'll lose any data saved in the database. + +```term +$ heroku addons:destroy heroku-postgresql +``` + +>warning +>This will delete your application + +```term +$ heroku apps:destroy +``` + +You can confirm that your add-on and app are gone with the commands: + +```term +$ heroku addons --all +$ heroku apps -all +``` + +You're now ready to deploy your app. diff --git a/test/fixtures/rails_6/rundoc.md b/test/fixtures/rails_6/rundoc.md index e2e883a..a9130d0 100644 --- a/test/fixtures/rails_6/rundoc.md +++ b/test/fixtures/rails_6/rundoc.md @@ -17,76 +17,74 @@ end $ bin/rundoc build --path test/fixtures/rails_6/rundoc.md --> ->warning ->As of November 28th, 2022, free Heroku dynos, free Heroku Postgres and free Heroku Data for Redis plans are [no longer available](https://blog.heroku.com/next-chapter). -> ->We recommend using our [low-cost plans](https://blog.heroku.com/new-low-cost-plans) to complete this tutorial. Eligible students can apply for platform credits through our new [Heroku for GitHub Students program](https://blog.heroku.com/github-student-developer-program). - > warning -> The latest version of Rails available is [Rails 7](https://devcenter.heroku.com/articles/getting-started-with-rails7). If you are starting a new application we recommend you use the most recently released version. +> The latest version of Rails available is [Rails 7](https://devcenter.heroku.com/articles/getting-started-with-rails7). If you're starting a new application, we recommend you use the most recently released version. Ruby on Rails is a popular web framework written in [Ruby](http://www.ruby-lang.org/). This guide covers using Rails 6 on Heroku. For information on running previous versions of Rails on Heroku, see the tutorial for [Rails 5.x](getting-started-with-rails5) or [Rails 4.x](getting-started-with-rails4). -``` -:::-- $ ruby -e "exit 1 unless RUBY_VERSION == '2.7.2'" -``` - -For this guide you will need: +The tutorial assumes that you have: - Basic familiarity with Ruby/Rails and Git - A locally installed version of Ruby 2.5.0+, Rubygems, Bundler, and Rails 6+ +- A locally installed version of the [Heroku CLI](heroku-cli#install-the-heroku-cli) - A [verified Heroku Account](https://devcenter.heroku.com/articles/account-verification) - A subscription to the [Eco dynos plan](eco-dyno-hours) (recommended) -## Local setup +>note +>Using dynos and databases to complete this tutorial counts towards your usage. We recommend using our [low-cost plans](https://blog.heroku.com/new-low-cost-plans) to complete this tutorial. Eligible students can apply for platform credits through our new [Heroku for GitHub Students program](https://blog.heroku.com/github-student-developer-program). -Install the [Heroku CLI](heroku-cli#download-and-install) on your development machine. +``` +:::-- $ ruby -e "exit 1 unless RUBY_VERSION == '3.0.6'" +``` -Once installed, the `heroku` command is available from your terminal. Log in using your Heroku account's email address and password: +## Local Setup + +After installing the [Heroku CLI](heroku-cli#install-the-heroku-cli), log in through your terminal: ```term $ heroku login -heroku: Enter your Heroku credentials -Email: schneems@example.com -Password: -Could not find an existing public key. -Would you like to generate one? [Yn] -Generating new SSH public key. -Uploading ssh public key /Users/adam/.ssh/id_rsa.pub +heroku: Press any key to open up the browser to login or q to exit + › Warning: If browser does not open, visit + › https://cli-auth.heroku.com/auth/browser/*** +heroku: Waiting for login... +Logging in... done +Logged in as me@example.com ``` -Press Enter at the prompt to upload your existing `ssh` key or create a new one, used for pushing code later on. +This command opens your web browser to the Heroku login page. If your browser is already logged in to Heroku, click the **`Log in`** button on the page. + +This authentication is required for the `heroku` and `git` commands to work correctly. -## Create a new Rails app (or upgrade an existing one) +## Create a New or Upgrade an Existing Rails App -To create a new app, first make sure that you're using Rails 6.x by running `rails -v`. If necessary, you can get the new version of rails by running the following: +Ensure that you're using Rails 6.x by running `rails -v`. If necessary, install it with this command: ```term -:::>> $ gem install rails --no-document +:::>> $ gem install rails -v 6.1.7.3 --no-document ``` -Then create a new app and move into its root directory: +Create a Rails app: ```term -:::>- $ rails new myapp --database=postgresql +:::>- $ rails _6.1.7.3_ new myapp --database=postgresql ``` -Then move into your application directory. +Move into the application directory and add the `x86_64-linux` and `ruby` platforms to `Gemfile.lock`. ```term :::>- $ cd myapp :::>> $ bundle lock --add-platform x86_64-linux --add-platform ruby ``` -Create a database locally: +Create a local database: ``` :::>> $ bin/rails db:create ``` -## Add the pg gem +## Add the pg Gem -If you're using an existing app that was created without specifying `--database=postgresql`, you need to add the `pg` gem to your Rails project. Edit your `Gemfile` and change this line: +For new or existing apps where `--database=postgresql` isn’t defined, confirm the `sqlite3` gem doesn’t exist in the `Gemfile`. Add the `pg` gem in its place. ```ruby gem 'sqlite3' @@ -98,34 +96,35 @@ To this: gem 'pg' ``` -> callout We highly recommend using PostgreSQL during development. Maintaining [parity between your development](http://www.12factor.net/dev-prod-parity) and deployment environments prevents subtle bugs from being introduced because of differences between your environments. [Install Postgres locally](heroku-postgresql#local-setup) now if it is not already on your system. +> callout +>Heroku highly recommends using PostgreSQL locally during development. Maintaining [parity between development](http://www.12factor.net/dev-prod-parity) and deployment environments prevents introducing subtle bugs due to the differences in environments. +> +> [Install Postgres locally](heroku-postgresql#local-setup). For more information on why Postgres is recommended instead of Sqlite3, see [why Sqlite3 is not compatible with Heroku](sqlite3). -Now re-install your dependencies (to generate a new `Gemfile.lock`): +With the `Gemfile` updated, reinstall the dependencies: ```ruby $ bundle install ``` -For more information on why Postgres is recommended instead of Sqlite3, see [why you cannot use Sqlite3 on Heroku](sqlite3). +The installation also updates `Gemfile.lock` with the changes. -In addition to using the `pg` gem, ensure that your `config/database.yml` file is using the `postgresql` adapter. The development section of your `config/database.yml` file should look something like this: +In addition to the `pg` gem, ensure that `config/database.yml` defines the `postgresql` adapter. The development section of `config/database.yml` file looks something like this: ```term :::>> $ cat config/database.yml ``` -Be careful here. If you omit the `sql` at the end of `postgresql` in the `adapter` section, your application will not work. +Be careful here. If the value of `adapter` is `postgres` and not `postgresql`, the application won’t work. -## Create a welcome page +## Create a Welcome Page -Rails 6 no longer has a static index page in production by default. When you're using a new app, there will not be a root page in production, so we need to create one. We will first create a controller called `welcome` for our home page to live: +Rails 6 no longer has a static index page in production by default. When you're using a new app, there isn't a root page in production, so you must create one. Create a controller called `welcome` for the home page: ```term :::>- $ rails generate controller welcome ``` -Next we'll add an index page: - ```html :::>> file.write app/views/welcome/index.html.erb

Hello World

@@ -134,7 +133,7 @@ Next we'll add an index page:

``` -Now we need to make Rails route to this action. We'll edit `config/routes.rb` to set the index page to our new method: +Create a Rails route to this action. Edit `config/routes.rb` to set the index page to the new method: ```ruby :::>> file.append config/routes.rb#2 @@ -148,57 +147,59 @@ You can verify that the page is there by running your server: :::-- background.stop(name: "server") ``` -And visiting [http://localhost:3000](http://localhost:3000) in your browser. If you do not see the page, [use the logs](#view-logs) that are output to your server to debug. +Visit [http://localhost:3000](http://localhost:3000) in your browser. If you don't see the page, [use the logs](#view-application-logs) to debug. Rails outputs logs in the same terminal where `rails server` started. -## Heroku gems - -Previous versions of Rails required you to add a gem to your project [rails_12factor](https://github.com/heroku/rails_12factor) to enable static asset serving and logging on Heroku. If you are deploying a new application, this gem is not needed. If you are upgrading an existing application, you can remove this gem provided you have the appropriate configuration in your `config/environments/production.rb` file: +## Specify the Ruby Version +Rails 6 requires Ruby 2.5.0 or above. Heroku has a recent version of Ruby installed by default. Specify an exact version with the `ruby` DSL in `Gemfile`. For example: ```ruby -# config/environments/production.rb -config.public_file_server.enabled = ENV['RAILS_SERVE_STATIC_FILES'].present? - -if ENV["RAILS_LOG_TO_STDOUT"].present? - logger = ActiveSupport::Logger.new(STDOUT) - logger.formatter = config.log_formatter - config.logger = ActiveSupport::TaggedLogging.new(logger) -end +:::-- $ sed -i'' -e '/^ruby/d' ./Gemfile +:::-> file.append Gemfile#4 +ruby "3.0.6" ``` -## Specify your Ruby version +Always use the same version of Ruby locally. Confirm the local version of ruby with `ruby -v`. Refer to the [Ruby Versions](ruby-versions) article for more details on defining a specific ruby version. -Rails 6 requires Ruby 2.5.0 or above. Heroku has a recent version of Ruby installed by default, however you can specify an exact version by using the `ruby` DSL in your `Gemfile`. Depending on your version of Ruby that you are currently running it might look like this: +## Create a Procfile +Use a [Procfile](procfile), a text file in the root directory of your application, to explicitly declare what command to execute to start your app. -```ruby -:::-- $ sed -i'' -e '/^ruby/d' ./Gemfile -:::-> file.append Gemfile#4 -ruby "2.7.2" +This Procfile declares a single process type, `web`, and the command needed to run it. The name `web` is important here. It declares that this process type is attached to Heroku's [HTTP routing](http-routing) stack and receives web traffic when deployed. + +By default, a Rails app’s web process runs `rails server`, which uses Puma in Rails 7. When you deploy a Rails 7 application without a Procfile, this command executes. However, we recommend explicitly declaring how to boot your server process via a Procfile. + +``` +:::>> file.write Procfile +web: bundle exec puma -C config/puma.rb ``` -You should also be running the same version of Ruby locally. You can check this by running `$ ruby -v`. You can get more information on [specifying your Ruby version on Heroku here](https://devcenter.heroku.com/articles/ruby-versions). +>note +>The `Procfile` filename is case sensitive. There is no file extension. -## Store your app in Git +If `config/puma.rb` doesn’t exist, create one using [Heroku’s Puma documentation](https://devcenter.heroku.com/articles/deploying-rails-applications-with-the-puma-web-server) for maximum performance. -Heroku relies on [Git](http://git-scm.com/), a distributed source control management tool, for deploying your project. If your project is not already in Git, first verify that `git` is on your system: +A Procfile can contain additional process types. For example, you can declare a [background worker process](background-jobs-queueing#process-model) that processes items off a queue. + + +## Store The App in Git + +Heroku relies on [Git](http://git-scm.com/), a distributed source control management tool, for deploying applications. If the application is not already in Git, first verify that `git` is on the system with `git --help`: ```term :::>- $ git --help :::>> | $ head -n 5 ``` -If you don't see any output or get `command not found` you need to install Git on your system. - -Once you've verified that Git works, first make sure you are in your Rails app directory by running `$ ls`: +If the command produces no output or `command not found`, [install Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git). -The output should look like this: +Navigate to the root directory of the Rails app. Use the `ls` command to see its contents: ```term :::>> $ ls ``` -Now run these commands in your Rails app directory to initialize and commit your code to Git: +Within the Rails app directly, initialize a local empty Git repository and commit the app’s code: ```term :::>- $ git init @@ -206,109 +207,145 @@ Now run these commands in your Rails app directory to initialize and commit your :::>- $ git commit -m "init" ``` -You can verify everything was committed correctly by running: +Verify everything committed correctly with `git status`: ```term :::>> $ git status ``` -Now that your application is committed to Git you can deploy to Heroku. +With the application committed to Git, it's ready to deploy to Heroku. + +## Fix a babel regression + +Rails 6 relies on the [webpacker gem](https://github.com/rails/webpacker) which uses babel as a dependency. Version 7.22.0 of [babel released a breaking change](https://github.com/babel/babel/issues/15679) in a minor version that caused new Rails 6.1.x apps to break. Rails 6 and webpacker are no longer receiving bug fixes so unless babel reverts the change, then you will need to workaround this bug in your new app. + +Test to see if your application is affected by this bug by running this command: + +```term +:::>> $ rake webpacker:clobber webpacker:compile 2>&1 | grep "Cannot find package '@babel/plugin-proposal-private-methods'" +``` + +To fix this issue modify `babel.config.js`, replace `plugin-proposal-private-methods` with `plugin-transform-private-methods`: + +```diff +- '@babel/plugin-plugin-private-methods', ++ '@babel/plugin-transform-private-methods', +``` + +```ruby +:::-- $ sed -i'' -e 's/plugin-proposal-private-methods/plugin-transform-private-methods/' ./babel.config.js +``` + +Verify that it works correctly: + +```term +:::>- $ rake webpacker:clobber webpacker:compile +``` + +Commit the fix to git: + +``` +:::>- $ git add . +:::>- $ git commit -m "fix babel error" +``` -## Create a Heroku app +## Create a Heroku App >warning >Using a dyno and a database to complete this tutorial counts towards your usage. [Delete your app](https://devcenter.heroku.com/articles/heroku-cli-commands#heroku-apps-destroy), and [database](https://devcenter.heroku.com/articles/heroku-postgresql#removing-the-add-on) as soon as you're done to control costs. -Make sure you are in the directory that contains your Rails app, then create an app on Heroku: +To create an app on Heroku, use the Heroku CLI Inside the Rails app’s root directory: ```term :::>> $ heroku create --stack heroku-20 ``` -You can verify that the remote was added to your project by running: +When you create an app, a git remote called `heroku` is also created and associated with your local git repository. Git remotes are versions of your repository that live on other servers. You deploy your app by pushing its code to that special Heroku-hosted remote associated with your app. Verify the remote is set with `git config`: ```term :::>> $ git config --list --local | grep heroku ``` -If you see `fatal: not in a git directory` then you are likely not in the correct directory. Otherwise, you can deploy your code. After you deploy your code, you need to migrate your database, make sure it is properly scaled, and use logs to debug any issues that come up. +If the current directory is incorrect or Git isn't [initialized](#store-the-app-in-git), Git returns `fatal: not in a git directory`. If Git returns a list of remotes, it's ready to deploy. >note >Following changes in the industry, Heroku has updated our default git branch name to `main`. If the project you’re deploying uses `master` as its default branch name, use `git push heroku master`. ## Provision a Database -Provision a Postgresql database using Add-ons. +Provision a [Heroku Postgres](https://devcenter.heroku.com/articles/heroku-postgresql) database, one of the add-ons available through the [Elements Marketplace](https://www.heroku.com/elements/addons). Add-ons are cloud services that provide out-of-the-box additional services for your application, such as logging, monitoring, databases, and more. >note ->A `mini` Postgres size costs [$5 a month, prorated to the minute](https://elements.heroku.com/addons/heroku-postgresql). At the end of this tutorial, you will be prompted to [delete your database](https://devcenter.heroku.com/articles/heroku-postgresql#removing-the-add-on) to minimize costs. +>A `mini` Postgres size costs [$5 a month, prorated to the minute](https://elements.heroku.com/addons/heroku-postgresql). At the end of this tutorial, we prompt you to [delete your database](https://devcenter.heroku.com/articles/heroku-postgresql#removing-the-add-on) to minimize costs. ```term -$ heroku addons:create heroku-postgresql:mini -Creating heroku-postgresql:mini on ⬢ shrouded-anchorage-34700... $5/month -Database has been created and is available - ! This database is empty. If upgrading, you can transfer - ! data from another database with pg:copy - -Created postgresql-encircled-75487 as DATABASE_URL -Use heroku addons:docs heroku-postgresql to view documentation +:::>> $ heroku addons:create heroku-postgresql:mini ``` -Your Heroku app now has access to a Postgresql database. The credentials are stored in the `DATABASE_URL` environment variable, which Rails will connect to by convention. +Your Heroku app can now access this Postgres database. The `DATABASE_URL` environment variable stores your credentials, which Rails connects to by convention. -## Deploy your application to Heroku +## Deploy the App to Heroku + +>warning +>Using a dyno to complete this tutorial counts towards your usage. [Delete your app](https://devcenter.heroku.com/articles/heroku-cli-commands#heroku-apps-destroy) as soon as you're done to control costs. -Deploy your code: +Deploy your code. This command pushes the `main` branch of the sample repo to your `heroku` remote, which then deploys to Heroku: ```term :::>> $ git push heroku main ``` -It is always a good idea to check to see if there are any warnings or errors in the output. If everything went well you can migrate your database. +If the output displays warnings or error messages, check the output and make adjustments. -## Migrate your database +After a successful deployment, complete these tasks as necessary: -If you are using the database in your application, trigger a migration by using the Heroku CLI to start a one-off [dyno](dynos), which is a lightweight container that is the basic unit of composition on Heroku, and run `db:migrate`: +* Database migrations +* Scale your dynos +* Check the app’s logs if issues arise + +## Migrate The Database + +If you're using a database in your application, trigger a migration by using the Heroku CLI to start a one-off [dyno](dynos). You can run commands, typically scripts and applications that are part of your app, in one-off dynos using the `heroku run` command. You can trigger a database migration with this command: ```term $ heroku run rake db:migrate ``` -Any commands after the `heroku run` are executed on a Heroku [dyno](dynos). You can obtain an interactive shell session by running `$ heroku run bash`. +To use an interactive shell session instead, you can execute `heroku run bash`. -## Visit your application +## Scale and Access the Application -You've deployed your code to Heroku. You can now instruct Heroku to execute a process type. Heroku does this by running the associated command in a [dyno](dynos), which is a lightweight container that is the basic unit of composition on Heroku. - -Let's ensure we have one dyno running the `web` process type: +Heroku runs application code using defined processes and [process types](procfile). New applications don't a process type active by default. The following command scales your app up to one dyno, running the `web` process: ```term :::>- $ heroku ps:scale web=1 ``` -You can check the state of the app's dynos. The `heroku ps` command lists the running dynos of your application: +Use the Heroku CLI’s `ps` command to display the state of all app dynos in the terminal: ```term :::>> $ heroku ps ``` -Here, one dyno is running. +By default, apps use Eco dynos if you're subscribed to [Eco](eco-dyno-hours). Otherwise, it defaults to Basic dynos. The Eco dynos plan is shared across all Eco dynos in your account and is recommended if you plan on deploying many small apps to Heroku. Eco dynos sleep if they don't receive any traffic for half an hour. This sleep behavior causes a few seconds delay for the first request upon waking. Eco dynos consume from a monthly, account-level quota of [eco dyno hours](eco-dyno-hours). As long as you haven't exhausted the quota, your apps can continue to run. + +To avoid dyno sleeping, upgrade to a Basic or higher dyno type as described in the [Dyno Types](dyno-types) article. Upgrading to at least Standard dynos also allows you to scale up to multiple dynos per process type. -We can now visit the app in our browser with `heroku open`. +To launch the app in the browser, run `heroku open`: ```term :::>> $ heroku open ``` -You should now see the "Hello World" text we inserted above. +The browser displays the “Hello World” text. If it doesn't, or there's an error, [review and confirm the welcome page contents](#create-a-welcome-page). -Heroku gives you a default web URL for simplicity while you are developing. When you are ready to scale up and use Heroku for production you can add your own [custom domain](https://devcenter.heroku.com/articles/custom-domains). +Heroku provides a [default web URL](app-names-and-subdomains) for every application during development. When the application is ready for production, add a [custom domain](https://devcenter.heroku.com/articles/custom-domains). -## View logs +## View Application Logs -If you run into any problems getting your app to perform properly, you will need to check the logs. +The app logs are a valuable tool if the app is not performing correctly or generating errors. -You can view information about your running app using one of the [logging commands](logging), `heroku logs`: +View information about a running app using the Heroku CLI [logging command](logging), `heroku logs`. Here's example output: ```term :::>> $ heroku logs @@ -320,15 +357,13 @@ You can also get the full stream of logs by running the logs command with the `- $ heroku logs --tail ``` -## Dyno sleeping and scaling +By default, Heroku stores 1500 lines of logs from your application, but the full log stream is available as a service. Several [add-on providers](https://elements.heroku.com/addons/#logging) have logging services that provide things such as log persistence, search, and email and SMS alerts. -By default, new applications are deployed to an eco dyno. Eco apps will "sleep" to conserve resources. You can find more information about this behavior by reading about [eco dyno behavior](eco-dyno-hours). +## Optional Steps -To avoid dyno sleeping, you can upgrade to a Basic or Professional dyno type as described in the [Dyno Types](dyno-types) article. For example, if you migrate your app to a professional dyno, you can easily scale it by running a command telling Heroku to execute a specific number of dynos, each running your web process type. +### Use The Rails Console -## Run the Rails console - -Heroku allows you to run commands in a [one-off dyno](one-off-dynos) - scripts and applications that only need to be executed when needed - using the `heroku run` command. Use this to launch a Rails console process attached to your local terminal for experimenting in your app's environment: +Use the Heroku CLI `run` command to trigger [one-off dynos](one-off-dynos) to run scripts and applications only when necessary. Use the command to launch a Rails console process attached to the local terminal for experimenting in the app's environment: ```term $ heroku run rails console @@ -336,59 +371,29 @@ irb(main):001:0> puts 1+1 2 ``` -Another useful command for debugging is `$ heroku run bash` which will spin up a new dyno and give you access to a bash session. - -## Run Rake commands +### Run Rake Commands -Rake can be run as an attached process exactly like the console: +Run `rake` commands, such as `db:migrate`, using the `run` command exactly like the Rails console: ```term $ heroku run rake db:migrate ``` -## Configure your webserver - -By default, your app's web process runs `rails server`, which uses Puma in Rails 6. If you are upgrading an app you'll need to add `puma` to your application `Gemfile`: - -```ruby -gem 'puma' -``` - -Then run - -```term -:::>- $ bundle install -``` - -Now you are ready to configure your app to use Puma. For this tutorial we will use the default `config/puma.rb` of that ships with Rails 6, but we recommend reading more about configuring your application for maximum performance by [reading the Puma documentation](https://devcenter.heroku.com/articles/deploying-rails-applications-with-the-puma-web-server). - -Finally you will need to tell Heroku how to run your Rails app by creating a `Procfile` in the root of your application directory. - -### Create a Procfile - -Change the command used to launch your web process by creating a file called [Procfile](procfile) and entering this: - -``` -:::>> file.write Procfile -web: bundle exec puma -t 5:5 -p ${PORT:-3000} -e ${RACK_ENV:-development} -``` - -> Note: This file must be named `Procfile` exactly. - -We recommend generating a Puma config file based on [our Puma documentation](https://devcenter.heroku.com/articles/deploying-rails-applications-with-the-puma-web-server) for maximum performance. +### Use a Procfile locally -To use the Procfile locally, you can use `heroku local`. +To use the `Procfile` locally, use the `heroku local` CLI command. -In addition to running commands in your `Procfile` `heroku local` can also help you manage environment variables locally through a `.env` file. Set the local `RACK_ENV` to development in your environment and a `PORT` to connect to. Before pushing to Heroku you'll want to test with the `RACK_ENV` set to production since this is the environment your Heroku app will run in. +In addition to running commands in the `Procfile`, the `heroku local` command can also manage environment variables locally through a `.env` file. Set `RACK_ENV` to `development` for the local environment and the `PORT` for Puma. ```term :::>> $ echo "RACK_ENV=development" >>.env :::>> $ echo "PORT=3000" >> .env ``` -> Note: Another alternative to using environment variables locally with a `.env` file is the [dotenv](https://github.com/bkeepers/dotenv) gem. +>note +> Another alternative to using environment variables locally with a `.env` file is the [dotenv](https://github.com/bkeepers/dotenv) gem. -You'll also want to add `.env` to your `.gitignore` since this is for local environment setup. +Add `.env` to `.gitignore` as these variables are for local environment setup only. ```term :::>- $ echo ".env" >> .gitignore @@ -396,55 +401,46 @@ You'll also want to add `.env` to your `.gitignore` since this is for local envi :::>- $ git commit -m "add .env to .gitignore" ``` -If you're running Rails 6.0.0 you'll need to create a `tmp/pids` directory: - -```term -:::>> $ mkdir -p tmp/pids -:::>> $ touch tmp/pids/.gitkeep -``` - -Test your Procfile locally using Foreman. You can now start your web server by running: +Test the Procfile locally using [Foreman](heroku-local#run-your-app-locally-using-foreman)​​. Start the web server with `local`: ```term :::>> background.start("heroku local", name: "local", wait: "Ctrl-C to stop", timeout: 15) :::-- background.stop(name: "local") ``` -Looks good, so press `Ctrl+C` to exit and you can deploy your changes to Heroku: +Press `Ctrl+C` or `Cmd+C` to exit. -```term -:::>- $ git add . -:::>- $ git commit -m "use puma via procfile" -:::>- $ git push heroku main || git push heroku master -``` +## Rails asset pipeline -Check `ps`. You'll see that the web process uses your new command specifying Puma as the web server. +When deploying to Heroku, there are several options for invoking the [Rails asset pipeline](http://guides.rubyonrails.org/asset_pipeline.html). See the [Rails 3.1+ Asset Pipeline on Heroku Cedar](rails-asset-pipeline) article for general information on the asset pipeline. -```term -:::>> $ heroku ps -``` +Rails 6 removed the `config.assets.initialize_on_precompile` option because it's no longer needed. Additionally, any failure in asset compilation now causes the push to fail. For Rails 6 asset pipeline support, see the [Ruby Support](ruby-support#rails-5-x-applications) page. -The logs also reflect that we are now using Puma. +## Remove Heroku Gems -```term -$ heroku logs -``` +Previous versions of Rails required you to add a gem to your project [rails_12factor](https://github.com/heroku/rails_12factor) to enable static asset serving and logging on Heroku. If you are deploying a new application, this gem is not needed. If you are upgrading an existing application, you can remove this gem provided you have the appropriate configuration in your `config/environments/production.rb` file: -## Rails asset pipeline -There are several options for invoking the [Rails asset pipeline](http://guides.rubyonrails.org/asset_pipeline.html) when deploying to Heroku. For general information on the asset pipeline please see the [Rails 3.1+ Asset Pipeline on Heroku Cedar](rails-asset-pipeline) article. +```ruby +# config/environments/production.rb +config.public_file_server.enabled = ENV['RAILS_SERVE_STATIC_FILES'].present? -The `config.assets.initialize_on_precompile` option has been removed is and not needed for Rails 6. Also, any failure in asset compilation will now cause the push to fail. For Rails 6 asset pipeline support see the [Ruby Support](ruby-support#rails-5-x-applications) page. +if ENV["RAILS_LOG_TO_STDOUT"].present? + logger = ActiveSupport::Logger.new(STDOUT) + logger.formatter = config.log_formatter + config.logger = ActiveSupport::TaggedLogging.new(logger) +end +``` ## Troubleshooting -If you push up your app and it crashes (`heroku ps` shows state `crashed`), check your logs to find out what went wrong. Here are some common problems. +If an app deployed to Heroku crashes, for example, `heroku ps` shows the state `crashed`, review the app’s logs. The following section covers common causes of app crashes. -### Runtime dependencies on development/test gems +### Runtime Dependencies on Development or Test Gems -If you're missing a gem when you deploy, check your Bundler groups. Heroku builds your app without the `development` or `test` groups, and if your app depends on a gem from one of these groups to run, you should move it out of the group. +If a gem is missing during deployment, check the Bundler groups. Heroku builds apps without the `development` or `test` groups, and if the app depends on a gem from one of these groups to run, move it out of the group. -One common example is using the RSpec tasks in your `Rakefile`. If you see this in your Heroku deploy: +A common example is using the RSpec tasks in the `Rakefile`. The error often looks like this: ```term $ heroku run rake -T @@ -452,7 +448,8 @@ Running `bundle exec rake -T` attached to terminal... up, ps.3 rake aborted! no such file to load -- rspec/core/rake_task ``` -Then you've hit this problem. First, duplicate the problem locally: + +First, duplicate the problem locally by running `bundle install` without the development or test gem groups: ```term $ bundle install --without development:test @@ -462,9 +459,10 @@ rake aborted! no such file to load -- rspec/core/rake_task ``` -> Note: The `--without` option on bundler is sticky. You can get rid of this option by running `bundle config --delete without`. +>note +>The `--without` option on `bundler` is persistent. To remove this option, run `bundle config --delete without`. -Now you can fix it by making these Rake tasks conditional on the gem load. For example: +Fix the error by making these Rake tasks conditional during gem load. For example: ```ruby begin @@ -480,11 +478,38 @@ rescue LoadError end ``` -Confirm it works locally, then push to Heroku. +Confirm it works locally, then push it to Heroku. -## Next steps +## Next Steps -Congratulations! You have deployed your first Rails 6 application to Heroku. Here's some recommended reading: +Congratulations! You deployed your first Rails 6 application to Heroku. Review the following articles next: * Visit the [Ruby support category](/categories/ruby-support) to learn more about using Ruby and Rails on Heroku. * The [Deployment category](/categories/deployment) provides a variety of powerful integrations and features to help streamline and simplify your deployments. + +## Deleting Your App and Add-on + +Remove the app and database from your account. You're only charged for the resources you used. + +>warning +>This action removes your add-on and any data saved in the database. + +```term +$ heroku addons:destroy heroku-postgresql +``` + +>warning +>This action permanently deletes your application + +```term +$ heroku apps:destroy +``` + +You can confirm that your add-on and app are gone with the commands: + +```term +$ heroku addons --all +$ heroku apps -all +``` + +You're now ready to deploy your app. diff --git a/test/fixtures/rails_7/rundoc.md b/test/fixtures/rails_7/rundoc.md index f6134e8..ae61a1f 100644 --- a/test/fixtures/rails_7/rundoc.md +++ b/test/fixtures/rails_7/rundoc.md @@ -17,48 +17,49 @@ end $ bin/rundoc build --path test/fixtures/rails_7/rundoc.md --> ->warning ->As of November 28th, 2022, free Heroku dynos, free Heroku Postgres and free Heroku Data for Redis plans are [no longer available](https://blog.heroku.com/next-chapter). -> ->We recommend using our [low-cost plans](https://blog.heroku.com/new-low-cost-plans) to complete this tutorial. Eligible students can apply for platform credits through our new [Heroku for GitHub Students program](https://blog.heroku.com/github-student-developer-program). - Ruby on Rails is a popular web framework written in [Ruby](http://www.ruby-lang.org/). This guide covers using Rails 7 on Heroku. For information on running previous versions of Rails on Heroku, see the tutorial for [Rails 6.x](getting-started-with-rails6) or [Rails 5.x](getting-started-with-rails5). ``` -:::-- $ ruby -e "exit 1 unless RUBY_VERSION == '3.1.2'" +:::-- $ ruby -e "exit 1 unless RUBY_VERSION == '3.1.4'" ``` -Before continuing, it’s helpful to have: +The tutorial assumes that you have: - Basic familiarity with Ruby, Ruby on Rails, and Git -- A locally installed version of Ruby 2.7.0+, Rubygems, Bundler, and Rails 7+ -- A locally installed version of the [Heroku CLI](heroku-cli#download-and-install) +- A locally installed version of Ruby 3.0.0+, Rubygems, Bundler, and Rails 7+ +- A locally installed version of the [Heroku CLI](heroku-cli#install-the-heroku-cli) - A [verified Heroku Account](https://devcenter.heroku.com/articles/account-verification) - A subscription to the [Eco dynos plan](eco-dyno-hours) (recommended) -## Local setup -With the Heroku CLI installed, `heroku` is now an available command in the terminal. Log in to Heroku using the CLI: +>note +>Using dynos and databases to complete this tutorial counts towards your usage. We recommend using our [low-cost plans](https://blog.heroku.com/new-low-cost-plans) to complete this tutorial. Eligible students can apply for platform credits through our new [Heroku for GitHub Students program](https://blog.heroku.com/github-student-developer-program). + + +## Local Setup + +After installing the [Heroku CLI](heroku-cli#install-the-heroku-cli), log in through your terminal: ```term $ heroku login -heroku: Enter your Heroku credentials -Email: schneems@example.com -Password: -Could not find an existing public key. -Would you like to generate one? [Yn] -Generating new SSH public key. -Uploading ssh public key /Users/adam/.ssh/id_rsa.pub +heroku: Press any key to open up the browser to login or q to exit + › Warning: If browser does not open, visit + › https://cli-auth.heroku.com/auth/browser/*** +heroku: Waiting for login... +Logging in... done +Logged in as developer@example.com ``` -Press Enter at the prompt to upload an existing `ssh` key or create a new one. +This command opens your web browser to the Heroku login page. If your browser is already logged in to Heroku, click the **`Log in`** button on the page. + +This authentication is required for the `heroku` and `git` commands to work correctly. ->info ->After November 30, 2021, Heroku [will no longer support the SSH Git transport](​​https://devcenter.heroku.com/changelog-items/2215). SSH keys will serve no purpose in pushing code to applications on the Heroku platform. +>note +> If you're behind a firewall that uses a proxy to connect with external HTTP/HTTPS services, [set the `HTTP_PROXY` or `HTTPS_PROXY` environment variables](articles/using-the-cli#using-an-http-proxy) in your local development environment before running the `heroku` command. ## Create a New or Upgrade an Existing Rails App -Ensure Rails 7 is installed with `rails -v` before creating an app. If necessary, install Rails 7 with `gem install`: +Ensure you have Rails 7 installed by running `rails -v` before creating an app. If necessary, install Rails 7 with `gem install`: ```term :::>> $ gem install rails --no-document @@ -70,22 +71,25 @@ Create a Rails app: :::>- $ rails new myapp --database=postgresql ``` -Move into the application directly and add the `x86_64-linux` and `ruby` platforms to `Gemfile.lock`. +Move into the application directory and add the `x86_64-linux` and `ruby` platforms to `Gemfile.lock`. ```term :::>- $ cd myapp :::>> $ bundle lock --add-platform x86_64-linux --add-platform ruby +:::-- $ bundle install ``` + + Create a local database: -``` +```term :::>> $ bin/rails db:create ``` -## Add the pg gem +## Add the pg Gem -For new or existing apps where `--database=postgresql` wasn’t defined, confirm the `sqlite3` gem doesn’t exist in the `Gemfile`. Add the `pg` gem in its place. +For new or existing apps where `--database=postgresql` isn’t defined, confirm the `sqlite3` gem doesn’t exist in the `Gemfile`. Add the `pg` gem in its place. Within the `Gemfile` remove: @@ -93,15 +97,16 @@ Within the `Gemfile` remove: gem 'sqlite3' ``` -And replace it with: +Replace it with: ```ruby gem 'pg' ``` -> callout Heroku highly recommends using PostgreSQL locally during development. Maintaining [parity between development](http://www.12factor.net/dev-prod-parity) and deployment environments prevents subtle bugs from being introduced because of the differences in those environments. +> callout +>Heroku highly recommends using PostgreSQL locally during development. Maintaining [parity between development](http://www.12factor.net/dev-prod-parity) and deployment environments prevents introducing subtle bugs due to the differences in environments. > -> [Install Postgres locally](heroku-postgresql#local-setup) now if not present on the system, already. For more information on why Postgres is recommended instead of Sqlite3, see [why Sqlite3 is not compatible with Heroku](sqlite3). +> [Install Postgres locally](heroku-postgresql#local-setup). For more information on why Postgres is recommended instead of Sqlite3, see [why Sqlite3 is not compatible with Heroku](sqlite3). With the `Gemfile` updated, reinstall the dependencies: @@ -109,19 +114,19 @@ With the `Gemfile` updated, reinstall the dependencies: $ bundle install ``` -Doing so updates `Gemfile.lock` with the changes made previously. +The installation also updates `Gemfile.lock` with the changes. -In addition to using the `pg` gem, ensure that `config/database.yml` defines the `postgresql` adapter. The development section of `config/database.yml` file will look something like this: +In addition to the `pg` gem, ensure that `config/database.yml` defines the `postgresql` adapter. The development section of `config/database.yml` file looks something like this: ```term :::>> $ cat config/database.yml ``` -Be careful here. If the value of `adapter` is `postgres` and not `postgresql` (note the `sql` at the end), the application won’t work. +Be careful here. If the value of `adapter` is `postgres` and not `postgresql`, the application won’t work. ## Create a Welcome Page -Rails 7 no longer has a static index page in production by default. Apps upgraded to Rails 7 keep their existing page configurations, but new Rails 7 apps do not have an automatically generated welcome page. Create a `welcome` controller to hold the homepage: +Rails 7 no longer has a static index page in production by default. Apps upgraded to Rails 7 keep their existing page configurations, but new Rails 7 apps don't automatically generate a welcome page. Create a `welcome` controller to hold the homepage: ```term :::>- $ rails generate controller welcome @@ -151,35 +156,39 @@ Verify the page is present by starting the Rails web server: :::-- background.stop(name: "server") ``` -Visit [http://localhost:3000](http://localhost:3000) in a browser. If the page doesn’t display, [reference the logs](#view-logs) Rails outputs within the same terminal where `rails server` started to debug the error. +Visit [http://localhost:3000](http://localhost:3000) in a browser. If the page doesn’t display, [reference the logs](#view-application-logs) to debug the error. Rails outputs logs in the same terminal where `rails server` started. -## Heroku Gems +## Specify the Ruby Version -Previous versions of Rails (Rails 4 and older) required the [rails_12factor](https://github.com/heroku/rails_12factor) gem to enable static asset serving and logging on Heroku. New Rails applications don’t need this gem. The gem can be removed from existing, upgraded applications provided the following code is present in `config/environments/production.rb`: +Rails 7 requires Ruby 2.7.0 or above. Heroku installs a recent version of Ruby by default. Specify an exact version with the `ruby` DSL in `Gemfile`. For example: ```ruby -# config/environments/production.rb -config.public_file_server.enabled = ENV['RAILS_SERVE_STATIC_FILES'].present? - -if ENV["RAILS_LOG_TO_STDOUT"].present? - logger = ActiveSupport::Logger.new(STDOUT) - logger.formatter = config.log_formatter - config.logger = ActiveSupport::TaggedLogging.new(logger) -end +:::-- $ sed -i'' -e '/^ruby/d' ./Gemfile +:::-> file.append Gemfile#4 +ruby "3.1.4" ``` -## Specify the Ruby Version +Always use the same version of Ruby locally. Confirm the local version of ruby with `ruby -v`. Refer to the [Ruby Versions](ruby-versions) article for more details on defining a specific ruby version. -Rails 7 requires Ruby 2.7.0 or above. Heroku installs a recent version of Ruby buy default. Specify an exact version with the `ruby` DSL in `Gemfile` like the following example of defining Ruby 3.1.2: +## Create a Procfile +Use a [Procfile](procfile), a text file in the root directory of your application, to explicitly declare what command to execute to start your app. -```ruby -:::-- $ sed -i'' -e '/^ruby/d' ./Gemfile -:::-> file.append Gemfile#4 -ruby "3.1.2" +This Procfile declares a single process type, `web`, and the command needed to run it. The name `web` is important here. It declares that this process type is attached to Heroku's [HTTP routing](http-routing) stack and receives web traffic when deployed. + +By default, a Rails app’s web process runs `rails server`, which uses Puma in Rails 7. When you deploy a Rails 7 application without a Procfile, this command executes. However, we recommend explicitly declaring how to boot your server process via a Procfile. For example: + +``` +:::>> file.write Procfile +web: bundle exec puma -C config/puma.rb ``` -Always use the same version of Ruby locally, too. Confirm the local version of ruby with `ruby -v`. Refer to the [Ruby Versions](ruby-versions) article for more details on defining a specific ruby version. +>note +>The `Procfile` filename is case sensitive. There is no file extension. + +If `config/puma.rb` doesn’t exist, create one using [Heroku’s Puma documentation](https://devcenter.heroku.com/articles/deploying-rails-applications-with-the-puma-web-server) for maximum performance. + +A Procfile can contain additional process types. For example, you can declare a [background worker process](background-jobs-queueing#process-model) that processes items off a queue. ## Store The App in Git @@ -190,9 +199,9 @@ Heroku relies on [Git](http://git-scm.com/), a distributed source control manage :::>> | $ head -n 5 ``` -Git is not present if the command produces no output or `command not found`. Install Git on the system. +If the command produces no output or `command not found`, [install Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git). -After verifying Git is functional, navigate to the root directory of the Rails app. The contents of the Rails app looks something like this when using `ls`: +Navigate to the root directory of the Rails app. Use the `ls` command to see its contents: ```term :::>> $ ls @@ -206,106 +215,113 @@ Within the Rails app directly, initialize a local empty Git repository and commi :::>- $ git commit -m "init" ``` -Verify everything was committed correctly with `git status`: +Verify everything committed correctly with `git status`: ```term :::>> $ git status ``` -With the application committed to Git, it is ready to deploy to Heroku. +With the application committed to Git, it's ready to deploy to Heroku. -## Create a Heroku app +## Create a Heroku App >warning >Using a dyno and a database to complete this tutorial counts towards your usage. [Delete your app](https://devcenter.heroku.com/articles/heroku-cli-commands#heroku-apps-destroy), and [database](https://devcenter.heroku.com/articles/heroku-postgresql#removing-the-add-on) as soon as you're done to control costs. -Inside the Rails app’s root directory, use the Heroku CLI to create an app on Heroku: +To create an app on Heroku, use the Heroku CLI Inside the Rails app’s root directory: ```term -:::>> $ heroku apps:create --stack=heroku-22 +:::>> $ heroku apps:create ``` -The Heroku CLI adds the Git remote automatically. Verify it is set with `git config`: +When you create an app, a git remote called `heroku` is also created and associated with your local git repository. Git remotes are versions of your repository that live on other servers. You deploy your app by pushing its code to that special Heroku-hosted remote associated with your app. Verify the remote is set with `git config`: ```term :::>> $ git config --list --local | grep heroku ``` -Git returns `fatal: not in a git directory` if the current directory is incorrect or Git is not [initialized](#store-the-app-in-git). If Git returns a list of remotes, it is ready to deploy. +If the current directory is incorrect or Git isn't [initialized](#store-the-app-in-git), Git returns `fatal: not in a git directory`. If Git returns a list of remotes, it's ready to deploy. >note >Following changes in the industry, Heroku [updated the default branch name](​​https://devcenter.heroku.com/changelog-items/1829) to `main`. If the project uses `master` as its default branch name, use `git push heroku master`. ## Provision a Database -Provision a Postgresql database using Add-ons. +Provision a [Heroku Postgres](https://devcenter.heroku.com/articles/heroku-postgresql) database, one of the add-ons available through the [Elements Marketplace](https://www.heroku.com/elements/addons). Add-ons are cloud services that provide out-of-the-box additional services for your application, such as logging, monitoring, databases, and more. >note ->A `mini` Postgres size costs [$5 a month, prorated to the minute](https://elements.heroku.com/addons/heroku-postgresql). At the end of this tutorial, you will be prompted to [delete your database](https://devcenter.heroku.com/articles/heroku-postgresql#removing-the-add-on) to minimize costs. +>A `mini` Postgres size costs [$5 a month, prorated to the minute](https://elements.heroku.com/addons/heroku-postgresql). At the end of this tutorial, we prompt you to [delete your database](https://devcenter.heroku.com/articles/heroku-postgresql#removing-the-add-on) to minimize costs. ```term :::>> $ heroku addons:create heroku-postgresql:mini ``` -Your Heroku app now has access to a Postgresql database. The credentials are stored in the `DATABASE_URL` environment variable, which Rails will connect to by convention. +Your Heroku app can now access this Postgres database. The `DATABASE_URL` environment variable stores your credentials, which Rails connects to by convention. + +## Deploy the App to Heroku -## Deploy the Application to Heroku +>warning +>Using a dyno to complete this tutorial counts towards your usage. [Delete your app](https://devcenter.heroku.com/articles/heroku-cli-commands#heroku-apps-destroy) as soon as you're done to control costs. -Deploy the code: +Deploy your code. This command pushes the `main` branch of the sample repo to your `heroku` remote, which then deploys to Heroku: ```term :::>> $ git push heroku main ``` -The output may display warnings or error messages. Check the output for these and make adjustments as necessary. +If the output displays warnings or error messages, check the output and make adjustments. -If the deployment is successful, the application may need a few additional adjustments: +After a successful deployment, complete these tasks as necessary: -* Migration of the database -* Ensure proper dyno scaling -* Reference the app’s logs if any issues arise +* Database migrations +* Scale your dynos +* Check the app’s logs if issues arise ## Migrate The Database -If you are using the database in your application, trigger a migration by using the Heroku CLI to start a one-off [dyno](dynos), which is a lightweight container that is the basic unit of composition on Heroku, and run `db:migrate`: +If you're using a database in your application, trigger a migration by using the Heroku CLI to start a one-off [dyno](dynos). You can run commands, typically scripts and applications that are part of your app, in one-off dynos using the `heroku run` command. You can trigger a database migration with this command: ```term $ heroku run rake db:migrate ``` -Obtain an interactive shell session, instead, with `heroku run bash`. +To use an interactive shell session instead, you can execute `heroku run bash`. -## Access the Application +## Scale and Access the Application -The application is successfully deployed to Heroku. Heroku runs application code using defined processes and [process types](procfile). New applications will not have a process type active by default. Scale the `web` process type using the Heroku CLI’s `ps:scale` command: +Heroku runs application code using defined processes and [process types](procfile). New applications don't a process type active by default. The following command scales your app up to one dyno, running the `web` process: ```term :::>- $ heroku ps:scale web=1 ``` -Use the Heroku CLI’s `ps` command to display the state of all of an app’s dynos in the terminal: +Use the Heroku CLI’s `ps` command to display the state of all app dynos in the terminal: ```term :::>> $ heroku ps ``` -In the previous example, a single `web` process is running. +In this example, a single `web` process is running. + +By default, apps use Eco dynos if you're subscribed to [Eco](eco-dyno-hours). Otherwise, it defaults to Basic dynos. The Eco dynos plan is shared across all Eco dynos in your account and is recommended if you plan on deploying many small apps to Heroku. Eco dynos sleep if they don't receive any traffic for half an hour. This sleep behavior causes a few seconds delay for the first request upon waking. Eco dynos consume from a monthly, account-level quota of [eco dyno hours](eco-dyno-hours). As long as you haven't exhausted the quota, your apps can continue to run. + +To avoid dyno sleeping, upgrade to a Basic or higher dyno type as described in the [Dyno Types](dyno-types) article. Upgrading to at least Standard dynos also allows you to scale up to multiple dynos per process type. -Use `heroku open` to launch the app in the browser. +To launch the app in the browser, run `heroku open`: ```term :::>> $ heroku open ``` -The browser should display the “Hello World” text defined previously. If it does not, or an error is present, [review and confirm the welcome page contents](#create-a-welcome-page). +The browser displays the “Hello World” text. If it doesn't, or there's an error, [review and confirm the welcome page contents](#create-a-welcome-page). -Heroku provides a default web URL for every application during development. When the application is ready to scale up for production, add a [custom domain](https://devcenter.heroku.com/articles/custom-domains). +Heroku provides a [default web URL](app-names-and-subdomains) for every application during development. When the application is ready for production, add a [custom domain](https://devcenter.heroku.com/articles/custom-domains). ## View Application Logs The app logs are a valuable tool if the app is not performing correctly or generating errors. -View information about a running app using the Heroku CLI [logging command](logging), `heroku logs`. Here is example output: +View information about a running app using the Heroku CLI [logging command](logging), `heroku logs`. Here's example output: ```term :::>> $ heroku logs @@ -317,13 +333,11 @@ Append `-t`/`--tail` to the command to see a full, live stream of the app’s lo $ heroku logs --tail ``` -## Dyno Sleeping and Scaling +By default, Heroku stores 1500 lines of logs from your application, but the full log stream is available as a service. Several [add-on providers](https://elements.heroku.com/addons/#logging) have logging services that provide things such as log persistence, search, and email and SMS alerts. -New applications are deployed to an eco dyno by default. After a period of inactivity, eco apps will "sleep" to conserve resources. For more on Heroku’s eco dyno behavior, see [Eco Dyno Hours](eco-dyno-hours). +## Optional Steps -Upgrade to a Basic or Professional dyno type as described in the [Dyno Types](dyno-types) article to avoid dyno sleeping. For example, migrating an app to a progressional dyno allows for easy scaling by using the Heroku CLI `ps:scale` command to instruct the Heroku platform to start or stop additional dynos that run the same `web` process type. - -## The Rails Console +### Use The Rails Console Use the Heroku CLI `run` command to trigger [one-off dynos](one-off-dynos) to run scripts and applications only when necessary. Use the command to launch a Rails console process attached to the local terminal for experimenting in the app's environment: @@ -335,49 +349,19 @@ irb(main):001:0> puts 1+1 The `run bash` Heroku CLI command is also helpful for debugging. The command starts a new one-off dyno with an interactive bash session. -## Rake Commands +### Run Rake Commands -Run `rake` commands (`db:migrate`, for example) using the `run` command exactly like the Rails console: +Run `rake` commands, such as `db:migrate`, using the `run` command exactly like the Rails console: ```term $ heroku run rake db:migrate ``` -## Configure The Web Server - -By default, a Rails app's web process runs `rails server`, which uses Puma in Rails 7. Apps upgraded to Rails 7 need the `puma` gem added to the app’s `Gemfile`: - -```ruby -gem 'puma' -``` - -After adding the `puma` gem, install it: - -```term -:::>- $ bundle install -``` - -Rails 7 uses `config/puma.rb` to define Puma’s configuration and functionality with Puma installed. Heroku recommends reviewing [additional Puma configuration options](https://devcenter.heroku.com/articles/deploying-rails-applications-with-the-puma-web-server) to maximize the app’s performance. +### Use a Procfile locally -If `config/puma.rb` doesn’t exist, create one using [Heroku’s Puma documentation](https://devcenter.heroku.com/articles/deploying-rails-applications-with-the-puma-web-server) for maximum performance. - -With Puma installed, use the `Procfile` to instruct Heroku on how to launch the Rails app on a dyno. - -### Create a Procfile - -Change the command used to launch your web process by creating a file called [Procfile](procfile) inside the app’s root directory. Add the following line: - -``` -:::>> file.write Procfile -web: bundle exec puma -t 5:5 -p ${PORT:-3000} -e ${RACK_ENV:-development} -``` - ->note ->This file must be named `Procfile` exactly with a capital `P`, lowercase `rocfile`, and no file extension. - -To use the Procfile locally, use the `local` Heroku CLI command. +To use the `Procfile` locally, use the `heroku local` CLI command. -In addition to running commands in the `Procfile`, `heroku local` can also manage environment variables locally through a `.env` file. Set `RACK_ENV` to `development` for the local environment and the `PORT` for Puma. Test with the `RACK_ENV` set to `production` before pushing to Heroku; `production` is the environment in which the Heroku app will run. +In addition to running commands in the `Procfile`, the `heroku local` command can also manage environment variables locally through a `.env` file. Set `RACK_ENV` to `development` for the local environment and the `PORT` for Puma. ```term :::>> $ echo "RACK_ENV=development" >>.env @@ -385,9 +369,9 @@ In addition to running commands in the `Procfile`, `heroku local` can also manag ``` >note ->Another alternative to using environment variables locally with a `.env` file is the [dotenv](https://github.com/bkeepers/dotenv) gem. +> Another alternative to using environment variables locally with a `.env` file is the [dotenv](https://github.com/bkeepers/dotenv) gem. -Add `.env` to `.gitignore` since this is for local environment setup only. +Add `.env` to `.gitignore` as these variables are for local environment setup only. ```term :::>- $ echo ".env" >> .gitignore @@ -395,42 +379,24 @@ Add `.env` to `.gitignore` since this is for local environment setup only. :::>- $ git commit -m "add .env to .gitignore" ``` -Test the Procfile locally using [Foreman](run-your-app-locally-using-foreman)​​. Start the web server with `local`: +Test the Procfile locally using [Foreman](heroku-local#run-your-app-locally-using-foreman)​​. Start the web server with `local`: ```term :::>> background.start("heroku local", name: "local", wait: "Ctrl-C to stop", timeout: 15) :::-- background.stop(name: "local") ``` -A successful test will look similar to the previous example. Press `Ctrl+C` or `CMD+C` to exit and deploy the changes to Heroku: +Press `Ctrl+C` or `Cmd+C` to exit. -```term -:::>- $ git add . -:::>- $ git commit -m "use puma via procfile" -:::>- $ git push heroku main || git push heroku master -``` +### Rails asset pipeline -Check `ps`. The `web` process is now using the new command specifying Puma as the web server: - -```term -:::>> $ heroku ps -``` - -The logs also reflect that Puma is in use. - -```term -$ heroku logs -``` +When deploying to Heroku, there are several options for invoking the [Rails asset pipeline](http://guides.rubyonrails.org/asset_pipeline.html). See the [Rails 3.1+ Asset Pipeline on Heroku](rails-asset-pipeline) article for general information on the asset pipeline. -## Rails asset pipeline - -When deploying to Heroku, there are several options for invoking the [Rails asset pipeline](http://guides.rubyonrails.org/asset_pipeline.html). Please review the [Rails 3.1+ Asset Pipeline on Heroku Cedar](rails-asset-pipeline) article for general information on the asset pipeline. - -Rails 7 removed the `config.assets.initialize_on_precompile` option because it is no longer needed. Additionally, any failure in asset compilation will now cause the push to fail. For Rails 7 asset pipeline support, see the [Ruby Support](ruby-support#rails-5-x-applications) page. +Rails 7 removed the `config.assets.initialize_on_precompile` option because it's no longer needed. Additionally, any failure in asset compilation now causes the push to fail. For Rails 7 asset pipeline support, see the [Ruby Support](ruby-support#rails-7-x-applications) page. ## Troubleshooting -If an app deployed to Heroku crashes (`heroku ps` shows state `crashed`), review the app’s logs to determine what went wrong. The following section covers common causes of app crashes. +If an app deployed to Heroku crashes, for example, `heroku ps` shows the state `crashed`, review the app’s logs. The following section covers common causes of app crashes. ### Runtime Dependencies on Development or Test Gems @@ -455,7 +421,7 @@ no such file to load -- rspec/core/rake_task ``` >note ->The `--without` option on bundler is sticky. To get rid of this option, run `bundle config --delete without`. +>The `--without` option on `bundler` is persistent. To remove this option, run `bundle config --delete without`. Fix the error by making these Rake tasks conditional during gem load. For example: @@ -473,11 +439,41 @@ rescue LoadError end ``` -Confirm it works locally, then push to Heroku. +Confirm it works locally, then push it to Heroku. ## Next Steps -Congratulations! You deployed your first Rails 7 application to Heroku. Review the following articles next: +Congratulations on deploying a Rails 7 application! To continue exploring, review the following articles next: * Visit the [Ruby support category](/categories/ruby-support) to learn more about using Ruby and Rails on Heroku. * The [Deployment category](/categories/deployment) provides a variety of powerful integrations and features to help streamline and simplify your deployments. + +>note +>Remember to [delete your example app](https://devcenter.heroku.com/articles/heroku-cli-commands#heroku-apps-destroy), and [database](https://devcenter.heroku.com/articles/heroku-postgresql#removing-the-add-on) as soon as you're done with the tutorial, to control costs. + +## Delete Your App and Add-on + +Remove the app and database from your account. You're only charged for the resources you used. + +>warning +>This action removes your add-on and any data saved in the database. + +```term +$ heroku addons:destroy heroku-postgresql +``` + +>warning +>This action permanently deletes your application + +```term +$ heroku apps:destroy +``` + +You can confirm that your add-on and app are gone with these commands: + +```term +$ heroku addons --all +$ heroku apps --all +``` + +You're now ready to deploy your app.