DOCSP-43961: rails qs

snooty.toml

@@ -6,6 +6,7 @@ intersphinx = [ "https://www.mongodb.com/docs/manual/objects.inv",
               ]
 
 toc_landing_pages = [
+    "/quick-start-rails",
     "/quick-start-sinatra"
     ]
 
@@ -18,5 +19,6 @@ full-version = "{+version+}.2"
 ruby-driver = "Ruby driver"
 language = "Ruby"
 quickstart-sinatra-app-name = "my-sinatra-app"
+quickstart-rails-app-name = "my-rails-app"
 feedback-widget-title = "Feedback"
 server-manual = "Server manual"

source/index.txt

@@ -10,15 +10,16 @@
 <https://github.com/mongodb/mongoid-railsmdb>`_ utility.
 
 .. toctree::
-  :titlesonly:
-
-  /quick-start-sinatra
-  installation-configuration
-  tutorials
-  schema-configuration
-  working-with-data
-  API <https://mongodb.com/docs/mongoid/master/api/>
-  release-notes
-  contributing
-  additional-resources
-  ecosystem
+   :titlesonly:
+
+   /quick-start-rails
+   /quick-start-sinatra
+   installation-configuration
+   tutorials
+   schema-configuration
+   working-with-data
+   API <https://mongodb.com/docs/mongoid/master/api/>
+   release-notes
+   contributing
+   additional-resources
+   ecosystem

source/quick-start-rails.txt

@@ -0,0 +1,76 @@
+.. _mongoid-quick-start-rails:
+
+===========================
+Quick Start (Ruby on Rails)
+===========================
+
+.. facet::
+   :name: genre
+   :values: tutorial
+
+.. meta::
+   :keywords: ruby framework, odm
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+Overview
+--------
+
+This guide shows you how to use {+odm+} in a new **Ruby on Rails 7 (Rails)**
+web application, connect to a MongoDB cluster hosted on MongoDB
+Atlas, and perform read and write operations on the data in your
+cluster.
+
+.. tip::
+
+   If you prefer to connect to MongoDB by using the {+ruby-driver+} without
+   {+odm+}, see the {+ruby-driver+} :ruby:`Quick Start guide
+   </tutorials/quick-start/>`.
+
+{+odm+} is an Object-Document Mapper (ODM) framework for MongoDB in
+Ruby. By using {+odm+}, you can easily interact with your data and
+create flexible data models.
+
+Ruby on Rails, or Rails, is a web application framework for
+{+language+}. Rails applications use a model-view-controller (MVC)
+architecture that allows you to easily control how your data is
+modeled and displayed. {+odm+} replaces the default ``ActiveRecord``
+adapter for data modeling in Rails.
+
+To learn more about Ruby on Rails, see the `Getting Started
+with Rails <https://guides.rubyonrails.org/getting_started.html>`__
+guide in the Rails documentation.
+
+MongoDB Atlas is a fully managed cloud database service that hosts your
+MongoDB deployments. You can create your own free (no credit card
+required) MongoDB Atlas deployment by following the steps in this guide.
+
+Follow the steps in this guide to create a sample {+odm+} web application
+that connects to a MongoDB deployment.
+
+.. tip:: Other Framework Tutorials
+
+   If you prefer to use Rails 6 to build your application, see the
+   :ref:`mongoid-getting-started-rails-6` guide.
+
+   If you prefer to use Sinatra as your web framework, see the
+   :ref:`mongoid-quick-start-sinatra` guide.
+
+.. TODO .. tip::
+.. 
+..    You can download the complete web application project by cloning the
+..    `mongoid-quickstart <>`__ GitHub repository.
+
+.. toctree::
+
+   /quick-start-rails/download-and-install/
+   /quick-start-rails/create-a-deployment/
+   /quick-start-rails/create-a-connection-string/
+   /quick-start-rails/configure-mongodb/
+   /quick-start-rails/view-data/
+   /quick-start-rails/write-data/
+   /quick-start-rails/next-steps/

source/quick-start-rails/configure-mongodb.txt

@@ -0,0 +1,62 @@
+.. _mongoid-quick-start-rails-connect-to-mongodb:
+
+=================================
+Configure Your MongoDB Connection
+=================================
+
+.. facet::
+   :name: genre
+   :values: tutorial
+
+.. meta::
+   :keywords: test connection, runnable, code example
+
+.. procedure::
+   :style: connected
+
+   .. step:: Configure application for MongoDB
+
+      To configure your application to use MongoDB and {+odm+} as your
+      ODM, run the following command from the root of your project:
+
+      .. code-block:: bash
+
+         bin/rails g mongoid:config
+
+      After the command completes successfully, your application
+      contains the ``config/mongoid.yml`` file to configure the
+      connection to the MongoDB deployment. Your application also
+      includes the ``config/initializers/mongoid.rb`` file for more
+      advanced configuration.
+
+   .. step:: Specify target database in connection string
+
+      When connecting to an Atlas cluster, you must specify the database that
+      you want to interact with as the default database in your connection string.
+      You must add the database name to your connection string *after the hostname*.
+
+      The following example specifies the ``sample_restaurants`` target database
+      in a sample connection string:
+
+      .. code-block:: none
+
+         mongodb+srv://user0:[email protected]/sample_restaurants
+
+   .. step:: Specify connection in mongoid.yml
+
+      Paste the following configuration into the ``config/mongoid.yml`` file,
+      making sure to replace the ``<connection string>`` placeholder
+      with your connection string that references the target database:
+
+      .. code-block:: yaml
+         :emphasize-lines: 4
+
+         development:
+           clients:
+             default:
+               uri: <connection string>
+
+After completing these steps, your Rails web application is ready to
+connect to MongoDB.
+
+.. include:: /includes/quick-start/troubleshoot.rst

source/quick-start-rails/create-a-connection-string.txt

@@ -0,0 +1,7 @@
+.. _mongoid-quick-start-rails-create-cxn-str:
+
+==========================
+Create a Connection String
+==========================
+
+.. include:: /includes/quick-start/create-cxn-str.rst

source/quick-start-rails/create-a-deployment.txt

@@ -0,0 +1,7 @@
+.. _mongoid-quick-start-rails-create-deployment:
+
+===========================
+Create a MongoDB Deployment
+===========================
+
+.. include:: /includes/quick-start/create-deployment.rst

source/quick-start-rails/download-and-install.txt

@@ -0,0 +1,121 @@
+.. _mongoid-quick-start-rails-download-and-install:
+
+====================
+Download and Install
+====================
+
+.. facet::
+   :name: genre
+   :values: tutorial
+
+.. meta::
+   :keywords: ruby framework, odm, code example
+
+Prerequisites
+-------------
+
+To create the Quick Start application by using Rails 7, you need the
+following software installed in your development environment:
+
+- `{+language+}. <https://www.ruby-lang.org/en/documentation/installation/>`__
+  Rails requires {+language+}  v3.1.0 or later. Use the latest version
+  to prevent version conflicts.
+- `RubyGems package manager. <https://rubygems.org/pages/download>`__
+- A terminal app and shell. For MacOS users, use Terminal or a similar app.
+  For Windows users, use PowerShell.
+
+.. tip:: Rails 6 Tutorial
+
+   If you prefer to use Rails 6 to build your application, see the
+   :ref:`mongoid-getting-started-rails-6` guide.
+
+Download and Install the {+odm+} and Framework Gems
+---------------------------------------------------
+
+In {+language+}, packages are called **gems**.
+
+Complete the following steps to install and add the {+odm+} and Rails
+gems to your web application.
+
+.. procedure::
+   :style: connected
+
+   .. step:: Install Rails
+
+      Install the ``rails`` gem, which provides a command-line
+      interface to create a basic application structure and application
+      components.
+
+      Run the following command to install ``rails``:
+
+      .. code-block:: bash
+
+         gem install rails
+
+   .. step:: Create a Rails app with default scaffolding
+
+      Run the following commands to create a new Rails application
+      directory with default scaffolding and enter the application:
+
+      .. code-block:: bash
+
+         rails new {+quickstart-rails-app-name+} --skip-active-record
+         cd {+quickstart-rails-app-name+}
+
+      The ``--skip-active-record`` flag instructs Rails to not add
+      ``ActiveRecord`` as a dependency. You don't need this
+      dependency because you will use {+odm+}
+      instead.
+
+      .. tip:: MacOS Installation Issue
+
+         If you are using macOS, you might encounter issues when creating a
+         new Rails app during the automatic bundle installation step.
+         First, make sure that your macOS and `Xcode
+         <https://developer.apple.com/xcode/>`__ versions are up to
+         date. If you receive an error message similar to the following,
+         you must update or configure your build tools:
+
+         .. code-block:: none
+            :copyable: false
+
+            The compiler failed to generate an executable file.
+            ...
+            (RuntimeError) You have to install development tools first.
+
+         Run the following commands to install Xcode command line tools:
+
+         .. code-block:: bash
+
+            xcode-select --install
+            xcodebuild -license accept
+
+         Then, try to run the ``bundle install`` command again.
+
+   .. step:: Add the {+odm+} gem
+
+      Open the ``Gemfile`` in your application and add the following
+      entry:
+
+      .. code-block:: ruby
+
+         gem 'mongoid'
+
+   .. step:: Install gems
+
+      Run the following command to install the gems into your
+      application:
+
+      .. code-block:: bash
+
+         gem install bundler
+         bundle install
+
+      When the command runs successfully, the output in your
+      shell contains a ``Bundle complete!`` message and describes the
+      number of new gems installed.
+
+      After completing these steps, you have a new Rails web application with
+      {+odm+} installed.
+
+.. include:: /includes/quick-start/troubleshoot.rst

source/quick-start-rails/next-steps.txt

@@ -0,0 +1,32 @@
+.. _mongoid-quick-start-rails-next-steps:
+
+==========
+Next Steps
+==========
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: learn more
+
+Congratulations on completing the Quick Start tutorial for Ruby on Rails
+7!
+
+After you complete these steps, you have a Rails web application that
+uses {+odm+} to connect to your MongoDB deployment, run a query on
+the sample data, and render retrieved results.
+
+.. TODO You can download the completed web application project by cloning the
+.. `mongoid-quickstart <>`__
+.. GitHub repository.
+
+.. TODO Learn more about {+odm+} features from the following resources:
+
+.. - :ref:`mongoid-fundamentals-connection`: Learn how to configure your MongoDB
+..   connection.
+.. 
+.. - :ref:`mongoid-usage-examples`: See code examples of frequently used MongoDB
+..   operations.
+