Skip to content

Commit 40ffb76

Browse files
norareidynorareidy
committed
DOCSP-43200: Get started with Django
1 parent e8c1a41 commit 40ffb76

9 files changed

+448
-0
lines changed

‎snooty.toml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,12 +25,14 @@ sharedinclude_root = "https://raw.githubusercontent.com/10gen/docs-shared/main/"
2525
driver-short = "PyMongo"
2626
driver-long = "PyMongo, the MongoDB synchronous Python driver,"
2727
driver-async = "PyMongo Async"
28+
django-odm = "Django MongoDB"
2829
language = "Python"
2930
mdb-server = "MongoDB Server"
3031
mongo-community = "MongoDB Community Edition"
3132
mongo-enterprise = "MongoDB Enterprise Edition"
3233
docs-branch = "master" # always set this to the docs branch (i.e. master, 1.7, 1.8, etc.)
3334
version-number = "4.10"
35+
django-version-number = "5.0"
3436
patch-version-number = "{+version-number+}.1" # always set this to the driver branch (i.e. 1.7.0, 1.8.0, etc.)
3537
version = "v{+version-number+}"
3638
stable-api = "Stable API"

‎source/django-get-started.txt‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
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.
19+
:keywords: quick start, tutorial, basics
20+
21+
.. toctree::
22+
23+
Download & Install </django-get-started/django-install/>
24+
Create a Deployment </django-get-started/django-create-deployment/>
25+
Create a Connection String </django-get-started/django-connection-string/>
26+
Configure a MongoDB Connection </django-get-started/django-connect-mongodb/>
27+
Create an Application </django-get-started/django-create-app/>
28+
Write Data to MongoDB </django-get-started/django-write-data/>

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

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
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+
.. procedure::
15+
:style: connected
16+
17+
.. step:: Create a Django project
18+
19+
From your shell, run the following command to create a
20+
new Django project called ``quickstart`` based on a custom template:
21+
22+
.. code-block:: bash
23+
24+
django-admin startproject quickstart --template https://github.com/mongodb-labs/django-mongodb-project/archive/refs/heads/{+django-version-number+}.x.zip
25+
26+
.. note:: Project Template
27+
28+
The ``django-mongodb-project`` template resembles the default Django project
29+
template but makes the following changes:
30+
31+
- Includes MongoDB-specific migrations
32+
- Modifies the ``settings.py`` file to instruct Django
33+
to use an ``ObjectId`` value as each model's primary key
34+
35+
After running this command, your ``quickstart`` project has
36+
the following file structure:
37+
38+
.. code-block:: bash
39+
40+
quickstart/
41+
manage.py
42+
mongo_migrations/
43+
__init__.py
44+
contenttypes/
45+
auth/
46+
admin/
47+
quickstart/
48+
__init__.py
49+
apps.py
50+
settings.py
51+
urls.py
52+
asgi.py
53+
wsgi.py
54+
55+
.. step:: Update your database settings
56+
57+
Open your ``settings.py`` file and navigate to the ``DATABASES`` setting.
58+
Replace this setting with the following code:
59+
60+
.. code-block:: bash
61+
62+
DATABASES = {
63+
"default": {
64+
"ENGINE": "django_mongodb",
65+
"NAME": "db",
66+
"USER": "<username>",
67+
"PASSWORD": "<password>",
68+
"HOST": "<connection string URI>",
69+
},
70+
}
71+
72+
Replace the ``<username>`` and ``<password>`` placeholders with your
73+
Atlas database user's username and password. Then, replace the
74+
``<connection string URI>`` placeholder with the connection string
75+
that you copied from the :ref:`django-get-started-connection-string`
76+
step of this guide.
77+
78+
.. step:: Start the server
79+
80+
To verify that you installed {+django-odm+} and correctly configured
81+
your project, run the following command from your project root:
82+
83+
.. code-block:: bash
84+
85+
python3 manage.py runserver
86+
87+
Then, visit http://127.0.0.1:8000/. You should see a "Congratulations!"
88+
message and an image of a rocket.
89+

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

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
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:`Database` section and click the :guilabel:`Connect` button
28+
for your new deployment.
29+
30+
.. figure:: /includes/figures/atlas_connection_select_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+
Select the :guilabel:`Password (SCRAM)` authentication mechanism.
39+
40+
Deselect the :guilabel:`Include full driver code example` option to view
41+
the connection string.
42+
43+
.. step:: Copy your Connection String
44+
45+
Click the button on the right of the connection string to copy it to
46+
your clipboard as shown in the following screenshot:
47+
48+
.. figure:: /includes/figures/atlas_connection_copy_string_python.png
49+
:alt: The connection string copy button in the Atlas UI
50+
51+
.. step:: Update the Placeholders
52+
53+
Paste this connection string into a file in your preferred text editor
54+
and replace the ``<username>`` and ``<password>`` placeholders with
55+
your database user's username and password.
56+
57+
Save this file to a safe location for use in the next step.
58+
59+
After completing these steps, you have a connection string that
60+
contains your database username and password.
61+

‎source/django-get-started/django-create-app.txt‎

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
.. _django-get-started-create-app:
2+
3+
=====================
4+
Create an Application
5+
=====================
6+
7+
.. facet::
8+
:name: genre
9+
:values: tutorial
10+
11+
.. meta::
12+
:keywords: app, odm, code example
13+
14+
.. procedure::
15+
:style: connected
16+
17+
.. step:: Create a "sample_mflix" app
18+
19+
From your ``quickstart`` project directory, run the following command to create a
20+
new Django app called ``sample_mflix`` based on a custom template:
21+
22+
.. code-block:: bash
23+
24+
python3 manage.py startapp sample_mflix --template https://github.com/mongodb-labs/django-mongodb-app/archive/refs/heads/5.0.x.zip
25+
26+
.. note:: App Template
27+
28+
The ``django-mongodb-app`` template ensures that your ``app.py`` file
29+
includes the line ``"default_auto_field = 'django_mongodb.fields.ObjectIdAutoField'"``.
30+
31+
.. step:: Create a view
32+
33+
Open the ``views.py`` file in your ``sample_mflix`` directory and replace
34+
its contents with the following code:
35+
36+
.. code-block:: python
37+
38+
from django.http import HttpResponse
39+
40+
41+
def index(request):
42+
return HttpResponse("Hello, world. You're at the application index.")
43+
44+
.. step:: Configure a URL
45+
46+
Create a new file called ``urls.py`` file in your ``sample_mflix`` directory and add
47+
the following code:
48+
49+
.. code-block:: python
50+
51+
from django.urls import path
52+
53+
from . import views
54+
55+
urlpatterns = [
56+
path("", views.index, name="index"),
57+
]
58+
59+
Then, navigate to the ``quickstart/urls.py`` file and replace its contents with
60+
the following code:
61+
62+
.. code-block:: python
63+
64+
from django.contrib import admin
65+
from django.urls import include, path
66+
67+
urlpatterns = [
68+
path("sample_mflix/", include("sample_mflix.urls")),
69+
path("admin/", admin.site.urls),
70+
]
71+
72+
Visit http://127.0.0.1:8000/sample_mflix/ to see the text defined in your view.
73+
74+
.. step:: Apply database migrations
75+
76+
From your project root, run the following command:
77+
78+
.. code-block:: bash
79+
80+
python manage.py migrate
81+
82+
.. step:: Create models for movie and users data
83+
84+
Open the ``models.py`` file in the ``sample_mflix`` directory and replace
85+
its contents with the following code:
86+
87+
.. code-block:: python
88+
89+
from django.db import models
90+
91+
92+
class Movies(models.Model):
93+
name = models.CharField(max_length=200)
94+
runtime = models.IntegerField(default=0)
95+
96+
97+
class Users(models.Model):
98+
name = models.CharField(max_length=200)
99+
email = models.CharField(max_length=200)
100+
101+
102+
.. step:: Include your app in your project
103+
104+
Open the ``settings.py`` file in ``quickstart`` and edit your
105+
``INSTALLED_APPS`` setting to resemble the following code:
106+
107+
.. code-block:: python
108+
109+
INSTALLED_APPS = [
110+
'sample_mflix.apps.SampleMflixConfig',
111+
'quickstart.apps.MongoAdminConfig',
112+
'quickstart.apps.MongoAuthConfig',
113+
'quickstart.apps.MongoContentTypesConfig',
114+
'django.contrib.sessions',
115+
'django.contrib.messages',
116+
'django.contrib.staticfiles',
117+
]
118+
119+
.. step:: Create migrations for your new models
120+
121+
From your project root, run the following command to create
122+
migrations for the ``Movies`` and ``Users`` models and Apply
123+
the changes to the database:
124+
125+
.. code-block:: bash
126+
127+
python3 manage.py makemigrations sample_mflix
128+
python3 manage.py migrate

‎source/django-get-started/django-create-deployment.txt‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
.. _django-get-started-create-deployment:
2+
3+
===========================
4+
Create a MongoDB Deployment
5+
===========================
6+
7+
You can create a free tier MongoDB deployment on MongoDB Atlas
8+
to store and manage your data. MongoDB Atlas hosts and manages
9+
your MongoDB database in the cloud.
10+
11+
.. procedure::
12+
:style: connected
13+
14+
.. step:: Create a Free MongoDB deployment on Atlas
15+
16+
Complete the :atlas:`Get Started with Atlas </getting-started?tck=docs_driver_python>`
17+
guide to set up a new Atlas account and load sample data into a new free
18+
tier MongoDB deployment.
19+
20+
.. step:: Save your Credentials
21+
22+
After you create your database user, save that user's
23+
username and password to a safe location for use in an upcoming step.
24+
25+
After you complete these steps, you have a new free tier MongoDB
26+
deployment on Atlas, database user credentials, and sample data loaded
27+
in your database.

0 commit comments

Comments
 (0)