Skip to content

Commit 57e5bf3

Browse files
committed
DOCSP-43200: Get started
1 parent f8c7bd5 commit 57e5bf3

18 files changed

+907
-7
lines changed

source/get-started.txt

Lines changed: 44 additions & 0 deletions
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.
Lines changed: 88 additions & 0 deletions
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-number+}.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.
Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
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 and save the connection string
47+
48+
Paste your connection string into a file in your preferred text editor
49+
and save this file to a safe location for use in the next step.
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+
58+
Replace the ``<username>`` and ``<password>`` placeholders with
59+
your database user's username and password.
60+
61+
Then, specify a connection to the ``sample_mflix`` database from the
62+
Atlas sample datasets by adding it after the hostname, as shown in
63+
the following example:
64+
65+
.. code-block:: none
66+
:copyable: false
67+
68+
mongodb+srv://<username>:<password>@samplecluster.jkiff1s.mongodb.net/sample_mflix?retryWrites=true&w=majority&appName=SampleCluster
69+
70+
After completing these steps, you have a connection string that
71+
contains your database username, database password, and database name.

source/get-started/create-admin.txt

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
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+
41+
Username: admin
42+
Email address: [email protected]
43+
Password: <admin-password>
44+
Password (again): <admin-password>
45+
46+
Replace the ``<admin-password>`` placeholder with your user's password.
47+
48+
.. step:: Enter the admin site
49+
50+
Run the following code to start your server:
51+
52+
.. code-block:: bash
53+
54+
python manage.py runserver
55+
56+
Once your server is running, visit the http://127.0.0.1:8000/admin/
57+
URL to see the admin site. This site displays the following login
58+
screen:
59+
60+
.. figure:: /includes/figures/django_admin_login.png
61+
:alt: The login screen on the Django admin page.
62+
63+
Enter the username and password created in the previous step to log in to
64+
the site.
65+
66+
.. step:: Access your "sample_mflix" app from the admin site
67+
68+
After logging in to the admin site, you can see the following information:
69+
70+
.. figure:: /includes/figures/django_admin_index.png
71+
:alt: The initial content displayed on the Django admin site.
72+
73+
You can edit your project's authentication configuration by selecting
74+
the :guilabel:`Groups` or :guilabel:`Users` row in the
75+
:guilabel:`Authentication and Authorization` table.
76+
77+
To edit the data in the ``users`` sample collection, represented by your
78+
``Viewer`` model, navigate to your project's ``sample_mflix/admin.py`` file
79+
and paste the following code:
80+
81+
.. code-block:: python
82+
83+
from django.contrib import admin
84+
85+
from .models import Viewer
86+
87+
admin.site.register(Viewer)
88+
89+
Now, your admin site displays the following information:
90+
91+
.. figure:: /includes/figures/django_admin_model.png
92+
:alt: The content displayed on the Django admin site after registering a model.
93+
94+
.. step:: Select a Viewer object
95+
96+
You can view the data stored in a ``Viewer`` object that
97+
has a ``name`` value of ``"Abigail Carter"``. You created
98+
this object in the :ref:`django-get-started-write` step
99+
of this tutorial.
100+
101+
Click on the :guilabel:`Viewers` row of the :guilabel:`SAMPLE_MFLIX`
102+
table to see a list of viewers. The admin site displays the following
103+
list:
104+
105+
.. figure:: /includes/figures/django_admin_viewers.png
106+
:alt: The list of viewers displayed on the admin site.
107+
108+
Then, click on :guilabel:`Abigail Carter` at the top of the list.
109+
The site displays the :guilabel:`Name`, :guilabel:`Email`, and :guilabel:`Password`
110+
of the selected viewer:
111+
112+
.. figure:: /includes/figures/django_admin_edit_viewer.png
113+
:alt: The information of your selected viewer.
114+
115+
.. step:: Edit the data in a Viewer object
116+
117+
To edit the ``email`` field of the viewer, select the
118+
box that contains the text ``"[email protected]"``.
119+
Delete this text and replace it with ``"[email protected]"``,
120+
as shown in the following image:
121+
122+
.. figure:: /includes/figures/django_admin_new_email.png
123+
:alt: The updated email address of your viewer.
124+
125+
Then, click the :guilabel:`SAVE` button below the viewer's
126+
information to save your changes.
127+
128+
After completing these steps, you can access the Django
129+
admin site and use it to edit your ``Viewer`` objects.

0 commit comments

Comments
 (0)