Skip to content

Commit 9a1918c

Browse files
rustagirrustagir
authored
Merge pull request #52 from rustagir/DOCSP-43961-qs-rails
DOCSP-43961: rails qs
2 parents a1a3bb3 + 7ee7a35 commit 9a1918c

17 files changed

+507
-67
lines changed

‎snooty.toml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ intersphinx = [ "https://www.mongodb.com/docs/manual/objects.inv",
66
]
77

88
toc_landing_pages = [
9+
"/quick-start-rails",
910
"/quick-start-sinatra"
1011
]
1112

@@ -18,5 +19,6 @@ full-version = "{+version+}.2"
1819
ruby-driver = "Ruby driver"
1920
language = "Ruby"
2021
quickstart-sinatra-app-name = "my-sinatra-app"
22+
quickstart-rails-app-name = "my-rails-app"
2123
feedback-widget-title = "Feedback"
2224
server-manual = "Server manual"

‎source/includes/figures/quickstart-rails-list.png‎

185 KB
Loading

‎source/index.txt‎

Lines changed: 13 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -10,15 +10,16 @@ MongoDB in Ruby. To work with {+odm+} from the command line using
1010
<https://github.com/mongodb/mongoid-railsmdb>`_ utility.
1111

1212
.. toctree::
13-
:titlesonly:
14-
15-
/quick-start-sinatra
16-
installation-configuration
17-
tutorials
18-
schema-configuration
19-
working-with-data
20-
API <https://mongodb.com/docs/mongoid/master/api/>
21-
release-notes
22-
contributing
23-
additional-resources
24-
ecosystem
13+
:titlesonly:
14+
15+
/quick-start-rails
16+
/quick-start-sinatra
17+
installation-configuration
18+
tutorials
19+
schema-configuration
20+
working-with-data
21+
API <https://mongodb.com/docs/mongoid/master/api/>
22+
release-notes
23+
contributing
24+
additional-resources
25+
ecosystem

‎source/quick-start-rails.txt‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
.. _mongoid-quick-start-rails:
2+
3+
===========================
4+
Quick Start (Ruby on Rails)
5+
===========================
6+
7+
.. facet::
8+
:name: genre
9+
:values: tutorial
10+
11+
.. meta::
12+
:keywords: ruby framework, odm
13+
14+
.. contents:: On this page
15+
:local:
16+
:backlinks: none
17+
:depth: 1
18+
:class: singlecol
19+
20+
Overview
21+
--------
22+
23+
This guide shows you how to use {+odm+} in a new **Ruby on Rails 7 (Rails)**
24+
web application, connect to a MongoDB cluster hosted on MongoDB
25+
Atlas, and perform read and write operations on the data in your
26+
cluster.
27+
28+
.. tip::
29+
30+
If you prefer to connect to MongoDB by using the {+ruby-driver+} without
31+
{+odm+}, see the {+ruby-driver+} :ruby:`Quick Start guide
32+
</tutorials/quick-start/>`.
33+
34+
{+odm+} is an Object-Document Mapper (ODM) framework for MongoDB in
35+
Ruby. By using {+odm+}, you can easily interact with your data and
36+
create flexible data models.
37+
38+
Ruby on Rails is a web application framework for
39+
{+language+}. Rails applications use a model-view-controller (MVC)
40+
architecture that allows you to easily control how your data is
41+
modeled and displayed. {+odm+} replaces the default ``ActiveRecord``
42+
adapter for data modeling in Rails.
43+
44+
To learn more about Ruby on Rails, see the `Getting Started
45+
with Rails <https://guides.rubyonrails.org/getting_started.html>`__
46+
guide in the Rails documentation.
47+
48+
MongoDB Atlas is a fully managed cloud database service that hosts your
49+
MongoDB deployments. You can create your own free (no credit card
50+
required) MongoDB Atlas deployment by following the steps in this guide.
51+
52+
Follow the steps in this guide to create a sample {+odm+} web application
53+
that connects to a MongoDB deployment.
54+
55+
.. tip:: Other Framework Tutorials
56+
57+
If you prefer to use Rails 6 to build your application, see the
58+
:ref:`mongoid-getting-started-rails-6` guide.
59+
60+
If you prefer to use Sinatra as your web framework, see the
61+
:ref:`mongoid-quick-start-sinatra` guide.
62+
63+
.. TODO .. tip::
64+
..
65+
.. You can download the complete web application project by cloning the
66+
.. `mongoid-quickstart <>`__ GitHub repository.
67+
68+
.. toctree::
69+
70+
/quick-start-rails/download-and-install/
71+
/quick-start-rails/create-a-deployment/
72+
/quick-start-rails/create-a-connection-string/
73+
/quick-start-rails/configure-mongodb/
74+
/quick-start-rails/view-data/
75+
/quick-start-rails/write-data/
76+
/quick-start-rails/next-steps/

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

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
.. _mongoid-quick-start-rails-connect-to-mongodb:
2+
3+
=================================
4+
Configure Your MongoDB Connection
5+
=================================
6+
7+
.. facet::
8+
:name: genre
9+
:values: tutorial
10+
11+
.. meta::
12+
:keywords: test connection, runnable, code example
13+
14+
.. procedure::
15+
:style: connected
16+
17+
.. step:: Configure application for MongoDB
18+
19+
To configure your application to use MongoDB and {+odm+} as your
20+
ODM, run the following command from the root of your project:
21+
22+
.. code-block:: bash
23+
24+
bin/rails g mongoid:config
25+
26+
After the command completes successfully, your application
27+
contains the ``config/mongoid.yml`` file to configure the
28+
connection to the MongoDB deployment. Your application also
29+
includes the ``config/initializers/mongoid.rb`` file for more
30+
advanced configuration.
31+
32+
.. step:: Specify target database in connection string
33+
34+
When connecting to an Atlas cluster, you must specify the database that
35+
you want to interact with as the default database in your connection string.
36+
You must add the database name to your connection string *after the hostname*.
37+
38+
The following example specifies the ``sample_restaurants`` target database
39+
in a sample connection string:
40+
41+
.. code-block:: none
42+
43+
mongodb+srv://user0:[email protected]/sample_restaurants
44+
45+
.. step:: Specify connection in mongoid.yml
46+
47+
Paste the following configuration into the ``config/mongoid.yml`` file,
48+
making sure to replace the ``<connection string>`` placeholder
49+
with your connection string that references the target database:
50+
51+
.. code-block:: yaml
52+
:emphasize-lines: 4
53+
54+
development:
55+
clients:
56+
default:
57+
uri: <connection string>
58+
59+
After completing these steps, your Rails web application is ready to
60+
connect to MongoDB.
61+
62+
.. include:: /includes/quick-start/troubleshoot.rst

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

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
.. _mongoid-quick-start-rails-create-cxn-str:
2+
3+
==========================
4+
Create a Connection String
5+
==========================
6+
7+
.. include:: /includes/quick-start/create-cxn-str.rst

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

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
.. _mongoid-quick-start-rails-create-deployment:
2+
3+
===========================
4+
Create a MongoDB Deployment
5+
===========================
6+
7+
.. include:: /includes/quick-start/create-deployment.rst

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

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
.. _mongoid-quick-start-rails-download-and-install:
2+
3+
====================
4+
Download and Install
5+
====================
6+
7+
.. facet::
8+
:name: genre
9+
:values: tutorial
10+
11+
.. meta::
12+
:keywords: ruby framework, odm, code example
13+
14+
Prerequisites
15+
-------------
16+
17+
To create the Quick Start application by using Ruby on Rails 7, you need the
18+
following software installed in your development environment:
19+
20+
- `{+language+}. <https://www.ruby-lang.org/en/documentation/installation/>`__
21+
Rails requires {+language+} v3.1.0 or later. Use the latest version
22+
to prevent version conflicts.
23+
- `RubyGems package manager. <https://rubygems.org/pages/download>`__
24+
- A terminal app and shell. For MacOS users, use Terminal or a similar app.
25+
For Windows users, use PowerShell.
26+
27+
.. tip:: Rails 6 Tutorial
28+
29+
If you prefer to use Rails 6 to build your application, see the
30+
:ref:`mongoid-getting-started-rails-6` guide.
31+
32+
Download and Install the {+odm+} and Framework Gems
33+
---------------------------------------------------
34+
35+
In {+language+}, packages are called **gems**.
36+
37+
Complete the following steps to install and add the {+odm+} and Rails
38+
gems to your web application.
39+
40+
.. procedure::
41+
:style: connected
42+
43+
.. step:: Install Rails
44+
45+
Install the ``rails`` gem, which provides a command-line
46+
interface to create a basic application structure and application
47+
components.
48+
49+
Run the following command to install ``rails``:
50+
51+
.. code-block:: bash
52+
53+
gem install rails
54+
55+
.. step:: Create a Rails app with default scaffolding
56+
57+
Run the following commands to create a new Rails application
58+
directory with default scaffolding and enter the application:
59+
60+
.. code-block:: bash
61+
62+
rails new {+quickstart-rails-app-name+} --skip-active-record
63+
cd {+quickstart-rails-app-name+}
64+
65+
The ``--skip-active-record`` flag instructs Rails to not add
66+
``ActiveRecord`` as a dependency. You don't need this
67+
dependency because you will use {+odm+}
68+
instead.
69+
70+
.. tip:: MacOS Installation Issue
71+
72+
If you are using macOS, you might encounter issues when creating a
73+
new Rails app during the automatic bundle installation step.
74+
First, make sure that your macOS and `Xcode
75+
<https://developer.apple.com/xcode/>`__ versions are up to
76+
date. If you receive an error message similar to the following,
77+
you must update or configure your build tools:
78+
79+
.. code-block:: none
80+
:copyable: false
81+
82+
The compiler failed to generate an executable file.
83+
...
84+
(RuntimeError) You have to install development tools first.
85+
86+
Run the following commands to install Xcode command line tools:
87+
88+
.. code-block:: bash
89+
90+
xcode-select --install
91+
xcodebuild -license accept
92+
93+
Then, try to run the ``bundle install`` command again.
94+
95+
.. step:: Add the {+odm+} gem
96+
97+
Open the ``Gemfile`` in your application and add the following
98+
entry:
99+
100+
.. code-block:: ruby
101+
102+
gem 'mongoid'
103+
104+
.. step:: Install gems
105+
106+
Run the following command to install the gems into your
107+
application:
108+
109+
.. code-block:: bash
110+
111+
gem install bundler
112+
bundle install
113+
114+
When the command runs successfully, the output in your
115+
shell contains a ``Bundle complete!`` message and describes the
116+
number of new gems installed.
117+
118+
After completing these steps, you have a new Rails web application with
119+
{+odm+} installed.
120+
121+
.. include:: /includes/quick-start/troubleshoot.rst

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

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
.. _mongoid-quick-start-rails-next-steps:
2+
3+
==========
4+
Next Steps
5+
==========
6+
7+
.. facet::
8+
:name: genre
9+
:values: reference
10+
11+
.. meta::
12+
:keywords: learn more
13+
14+
Congratulations on completing the Quick Start tutorial for Ruby on Rails
15+
7!
16+
17+
After you complete these steps, you have a Rails web application that
18+
uses {+odm+} to connect to your MongoDB deployment, run a query on
19+
the sample data, and render retrieved results.
20+
21+
.. TODO You can download the completed web application project by cloning the
22+
.. `mongoid-quickstart <>`__
23+
.. GitHub repository.
24+
25+
.. TODO Learn more about {+odm+} features from the following resources:
26+
27+
.. - :ref:`mongoid-fundamentals-connection`: Learn how to configure your MongoDB
28+
.. connection.
29+
..
30+
.. - :ref:`mongoid-usage-examples`: See code examples of frequently used MongoDB
31+
.. operations.
32+

0 commit comments

Comments
 (0)