Skip to content

Commit 8be45de

Browse files
norareidynorareidy
authored
DOCSP-43200: Get started (#10)
* DOCSP-43200: Get started * fixes * move code to file * remove password field, edits * fix * fix urls * url order * url * connection string * embedded model * fix urls * snooty.toml edit
1 parent a6d9814 commit 8be45de

26 files changed

+961
-9
lines changed

‎snooty.toml

+4-1
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,8 @@ intersphinx = [ "https://www.mongodb.com/docs/manual/objects.inv",
77
]
88

99
toc_landing_pages = [
10-
"/interact-data"
10+
"/get-started",
11+
"/interact-data",
1112
]
1213

1314
[constants]
@@ -16,4 +17,6 @@ api = "https://django-mongodb.readthedocs.io/en/latest/"
1617
mdb-server = "MongoDB Server"
1718
django-version = "5.0"
1819
django-docs = "https://docs.djangoproject.com/en/{+django-version+}"
20+
django-api = "https://django-mongodb-backend.readthedocs.io/en/latest/"
21+
pymongo-version = "4.10"
1922
pymongo-docs = "https://www.mongodb.com/docs/languages/python/pymongo-driver/current"

‎source/get-started.txt

+44
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
.. _django-get-started:
2+
3+
===============================
4+
Get Started with {+django-odm+}
5+
===============================
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 2
11+
:class: singlecol
12+
13+
.. facet::
14+
:name: genre
15+
:values: tutorial
16+
17+
.. meta::
18+
:description: Learn how to create an app to connect to a MongoDB deployment by using Django MongoDB Backend.
19+
:keywords: quick start, tutorial, basics
20+
21+
.. toctree::
22+
23+
Download & Install </get-started/install/>
24+
Create a Deployment </get-started/create-deployment/>
25+
Create a Connection String </get-started/connection-string/>
26+
Configure a MongoDB Connection </get-started/connect-mongodb/>
27+
Create an Application </get-started/create-app/>
28+
Write Data to MongoDB </get-started/write-data/>
29+
Query MongoDB Data </get-started/query-data/>
30+
Create an Admin Site </get-started/create-admin/>
31+
Next Steps </get-started/next-steps/>
32+
33+
{+django-odm+} is a Django database backend that uses PyMongo to connect
34+
to MongoDB. This tutorial shows you how to create a Django app, connect to
35+
a MongoDB cluster hosted on MongoDB Atlas, and interact with data in your cluster.
36+
37+
.. tip::
38+
39+
MongoDB Atlas is a fully managed cloud database service that hosts your MongoDB
40+
deployments. You can create your own free (no credit card required) MongoDB Atlas
41+
deployment by following the steps in this guide.
42+
43+
Follow this tutorial to connect a sample Django application to a MongoDB Atlas
44+
deployment.

‎source/get-started/connect-mongodb.txt

+88
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
.. _django-get-started-connect:
2+
3+
=================================
4+
Configure your MongoDB Connection
5+
=================================
6+
7+
.. facet::
8+
:name: genre
9+
:values: tutorial
10+
11+
.. meta::
12+
:keywords: app, odm, code example
13+
14+
After installing {+django-odm+} and creating a MongoDB Atlas deployment,
15+
you can create a Django project that connects to MongoDB.
16+
17+
.. procedure::
18+
:style: connected
19+
20+
.. step:: Create a Django project
21+
22+
From your shell, run the following command to create a
23+
new Django project called ``quickstart`` based on a custom template:
24+
25+
.. code-block:: bash
26+
27+
django-admin startproject quickstart --template https://github.com/mongodb-labs/django-mongodb-project/archive/refs/heads/{+django-version+}.x.zip
28+
29+
.. note:: Project Template
30+
31+
The ``django-mongodb-project`` template resembles the default Django project
32+
template but makes the following changes:
33+
34+
- Includes MongoDB-specific migrations
35+
- Modifies the ``settings.py`` file to instruct Django
36+
to use an ``ObjectId`` value as each model's primary key
37+
38+
After running this command, your ``quickstart`` project has
39+
the following file structure:
40+
41+
.. code-block:: bash
42+
:copyable: false
43+
44+
quickstart/
45+
manage.py
46+
mongo_migrations/
47+
__init__.py
48+
contenttypes/
49+
auth/
50+
admin/
51+
quickstart/
52+
__init__.py
53+
apps.py
54+
settings.py
55+
urls.py
56+
asgi.py
57+
wsgi.py
58+
59+
.. step:: Update your database settings
60+
61+
Open your ``settings.py`` file and navigate to the ``DATABASES`` setting.
62+
Replace this setting with the following code:
63+
64+
.. code-block:: python
65+
66+
DATABASES = {
67+
"default": django_mongodb_backend.parse_uri("<connection string URI>"),
68+
}
69+
70+
Replace the ``<connection string URI>`` placeholder with the connection string
71+
that you copied from the :ref:`django-get-started-connection-string`
72+
step of this guide. This configures your Django app to connect to
73+
your Atlas deployment and access the ``sample_mflix`` sample database.
74+
75+
.. step:: Start the server
76+
77+
To verify that you installed {+django-odm+} and correctly configured
78+
your project, run the following command from your project root:
79+
80+
.. code-block:: bash
81+
82+
python manage.py runserver
83+
84+
Then, visit http://127.0.0.1:8000/. This page displays a "Congratulations!"
85+
message and an image of a rocket.
86+
87+
After completing these steps, you have a Django project configured
88+
to use MongoDB.

‎source/get-started/connection-string.txt

+74
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
.. _django-get-started-connection-string:
2+
3+
==========================
4+
Create a Connection String
5+
==========================
6+
7+
You can connect to your MongoDB deployment by providing a
8+
**connection URI**, also called a *connection string*, which
9+
instructs the driver on how to connect to a MongoDB deployment
10+
and how to behave while connected.
11+
12+
The connection string includes the hostname or IP address and
13+
port of your deployment, the authentication mechanism, user credentials
14+
when applicable, and connection options.
15+
16+
To connect to an instance or deployment not hosted on Atlas, see
17+
:ref:`pymongo-connection-targets` in the PyMongo documentation.
18+
19+
.. procedure::
20+
:style: connected
21+
22+
.. step:: Find your MongoDB Atlas connection string
23+
24+
To retrieve your connection string for the deployment that
25+
you created in the :ref:`previous step <django-get-started-create-deployment>`,
26+
log into your Atlas account and navigate to the
27+
:guilabel:`Clusters` section and click the :guilabel:`Connect` button
28+
for your new deployment.
29+
30+
.. figure:: /includes/figures/atlas_connection_connect_cluster.png
31+
:alt: The connect button in the clusters section of the Atlas UI
32+
33+
Proceed to the :guilabel:`Connect your application` section and select
34+
"Python" from the :guilabel:`Driver` selection menu and the version
35+
that best matches the version you installed from the :guilabel:`Version`
36+
selection menu.
37+
38+
.. step:: Copy your connection string
39+
40+
Click the button on the right of the connection string to copy it to
41+
your clipboard as shown in the following screenshot:
42+
43+
.. figure:: /includes/figures/atlas_connection_copy_string_python.png
44+
:alt: The connection string copy button in the Atlas UI
45+
46+
.. step:: Edit your connection string credentials
47+
48+
Paste your connection string into a file in your preferred text editor
49+
and save this file to a safe location for later use.
50+
Your connection string resembles the following example:
51+
52+
.. code-block:: none
53+
:copyable: false
54+
55+
mongodb+srv://<username>:<password>@samplecluster.jkiff1s.mongodb.net/?retryWrites=true&w=majority&appName=SampleCluster
56+
57+
Replace the ``<username>`` and ``<password>`` placeholders with
58+
your database user's username and password.
59+
60+
.. step:: Add a database to your connection string
61+
62+
Specify a database connection in your connection string by adding
63+
your database name after the hostname, as shown in the following example:
64+
65+
.. code-block:: none
66+
:copyable: false
67+
68+
mongodb+srv://<username>:<password>@samplecluster.jkiff1s.mongodb.net/<database name>?retryWrites=true&w=majority&appName=SampleCluster
69+
70+
Replace the ``<database name>`` placeholder with ``sample_mflix`` to
71+
configure a connection to the ``sample_mflix`` Atlas sample database.
72+
73+
After completing these steps, you have a connection string that
74+
contains your database username, database password, and database name.

‎source/get-started/create-admin.txt

+130
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
.. _django-get-started-create-admin:
2+
3+
====================
4+
Create an Admin Site
5+
====================
6+
7+
.. facet::
8+
:name: genre
9+
:values: tutorial
10+
11+
.. meta::
12+
:keywords: app, odm, code example
13+
14+
You can create a Django admin site to edit your application's
15+
data from a web interface. To learn more about the Django admin
16+
site and its features, see `The Django admin site <https://docs.djangoproject.com/en/{+django-version-number+}/ref/contrib/admin/>`__
17+
in the Django documentation.
18+
19+
.. procedure::
20+
:style: connected
21+
22+
.. step:: Create an admin user
23+
24+
Before creating an admin site, you must create a user
25+
who can log in to the site.
26+
27+
From your project's root directory, run the following command to create
28+
an admin user:
29+
30+
.. code-block:: bash
31+
32+
python manage.py createsuperuser
33+
34+
Then, your terminal prompts you for a username, email address,
35+
and password. For each prompt, enter the following information
36+
to create a user with the specified credentials and press "enter"
37+
after each entry:
38+
39+
.. code-block:: bash
40+
:copyable: false
41+
42+
Username: admin
43+
Email address: [email protected]
44+
Password: <admin-password>
45+
Password (again): <admin-password>
46+
47+
Replace the ``<admin-password>`` placeholder with your user's password.
48+
49+
.. step:: Enter the admin site
50+
51+
Run the following code to start your server:
52+
53+
.. code-block:: bash
54+
55+
python manage.py runserver
56+
57+
Once your server is running, visit the http://127.0.0.1:8000/admin/
58+
URL to see the admin site. This site displays the following login
59+
screen:
60+
61+
.. figure:: /includes/figures/django_admin_login.png
62+
:alt: The login screen on the Django admin page.
63+
64+
Enter the username and password created in the previous step to log in to
65+
the site.
66+
67+
.. step:: Access your "sample_mflix" app from the admin site
68+
69+
After logging in to the admin site, you can see the following information:
70+
71+
.. figure:: /includes/figures/django_admin_index.png
72+
:alt: The initial content displayed on the Django admin site.
73+
74+
You can edit your project's authentication configuration by selecting
75+
the :guilabel:`Groups` or :guilabel:`Users` row in the
76+
:guilabel:`Authentication and Authorization` table.
77+
78+
To edit the data in the ``users`` sample collection, represented by your
79+
``Viewer`` model, navigate to your project's ``sample_mflix/admin.py`` file
80+
and paste the following code:
81+
82+
.. code-block:: python
83+
84+
from django.contrib import admin
85+
86+
from .models import Viewer
87+
88+
admin.site.register(Viewer)
89+
90+
Now, your admin site displays the following information:
91+
92+
.. figure:: /includes/figures/django_admin_model.png
93+
:alt: The content displayed on the Django admin site after registering a model.
94+
95+
.. step:: Select a Viewer object
96+
97+
You can view the data stored in a ``Viewer`` object that
98+
has a ``name`` value of ``"Abigail Carter"``. You created
99+
this object in the :ref:`django-get-started-write` step
100+
of this tutorial.
101+
102+
Click on the :guilabel:`Viewers` row of the :guilabel:`SAMPLE_MFLIX`
103+
table to see a list of viewers. The admin site displays the following
104+
list:
105+
106+
.. figure:: /includes/figures/django_admin_viewers.png
107+
:alt: The list of viewers displayed on the admin site.
108+
109+
Then, click on :guilabel:`Abigail Carter` at the top of the list.
110+
The site displays the :guilabel:`Name` and :guilabel:`Email` of
111+
the selected viewer:
112+
113+
.. figure:: /includes/figures/django_admin_edit_viewer.png
114+
:alt: The information of your selected viewer.
115+
116+
.. step:: Edit the data in a Viewer object
117+
118+
To edit the ``email`` field of the viewer, select the
119+
box that contains the text ``"[email protected]"``.
120+
Delete this text and replace it with ``"[email protected]"``,
121+
as shown in the following image:
122+
123+
.. figure:: /includes/figures/django_admin_new_email.png
124+
:alt: The updated email address of your viewer.
125+
126+
Then, click the :guilabel:`SAVE` button below the viewer's
127+
information to save your changes.
128+
129+
After completing these steps, you can access the Django
130+
admin site and use it to edit your ``Viewer`` objects.

0 commit comments

Comments
 (0)