8000 Add template-based install to django CMS v3 docs (#7709) · django-cms/django-cms@04eaeaf · GitHub
[go: up one dir, main page]
Skip to content

Commit 04eaeaf

Browse files
fsbraunfsbraun
authored
Add template-based install to django CMS v3 docs (#7709)
1 parent 7bbd10b commit 04eaeaf

File tree

1 file changed

+91
-87
lines changed

1 file changed

+91
-87
lines changed

‎docs/how_to/install.rst

Lines changed: 91 additions & 87 deletions
Original file line numberDiff line numberDiff line change
@@ -42,14 +42,6 @@ django CMS also has other requirements, which it lists as dependencies in its ``
4242
python3 -m venv venv # create a virtualenv
4343
source venv/bin/activate # activate it
4444
45-
For the cms to work correctly, you will need django version 3.2.
46-
Work with newer versions can be unstable.
47-
You can install recommended version of django with following command:
48-
49-
.. code-block:: bash
50-
51-
pip install django==3.2
52-
5345
In an activated virtualenv, run::
5446

5547
pip install --upgrade pip
@@ -63,34 +55,79 @@ Then::
6355
to install the latest stable version of django CMS.
6456

6557

66-
****************************************
67-
Create a new project
68-
****************************************
58+
************************************
59+
Create a new project from a template
60+
************************************
6961

7062
Create a new project::
7163

72-
django-admin startproject myproject
64+
django-admin startproject myproject --template https://github.com/django-cms/cms-template/archive/3.11.tar.gz
7365

7466
If this is new to you, you ought to read the `official Django tutorial
7567
<https://docs.djangoproject.com/en/3.2/intro/tutorial01/>`_, which covers starting a new project.
7668

69+
It installs additional optional packages which are used in the template project. Those are
70+
71+
* `djangocms-text-ckeditor <https://github.com/django-cms/djangocms-text-ckeditor>`_ for rich text input.
72+
* `djangocms-frontend <https://github.com/django-cms/djangocms-frontend>`_ for `Bootstrap5 <https://getbootstrap.com>`_ support.
73+
* `django-filer <https://github.com/django-cms/django-filer>`_ for managing media files like images.
74+
* `djangocms_admin_style <https://github.com/django-cms/djangocms-admin-style>`_ for a consistent user experience with django CMS and Django admin.
75+
7776
Your new project will look like this::
7877

79-
myproject
80-
myproject
78+
myproject/
79+
LICENSE
80+
README.md
81+
db.sqlite3
82+
myproject/
83+
static/
84+
templates/
85+
base.html
8186
__init__.py
8287
asgi.py
8388
settings.py
8489
urls.py
8590
wsgi.py
8691
manage.py
92+
requirements.in
93+
94+
The ``LICENSE`` and ``README.md`` files are not needed and can be deleted or replaced by appropriate files for your project.
95+
96+
``requirements.in`` contains dependencies for the project. Add your dependencies here. We suggest to use `pip-compile <https://github.com/jazzband/pip-tools>`_ to freeze your requirements as, for example, discussed in `this blog post <https://blog.typodrive.com/2020/02/04/always-freeze-requirements-with-pip-compile-to-avoid-unpleasant-surprises/>`_.
97+
98+
Now, enter the project directory and create the database::
99+
100+
cd myproject
101+
python -m manage migrate
102+
103+
To run the project, you at least need a superuser to log in::
104+
105+
python -m manage createsuperuser
106+
107+
Finally, run the ``cms check`` command to see if everything worked fine::
108+
109+
python -m manage cms check
110+
111+
Fix any errors that are displayed. Once done, you are ready to spin up Django's development server by running::
112+
113+
python -m manage runserver
114+
115+
You can visit your project's web site by pointing your browser to ``localhost:8000``.
116+
117+
Use the newly created superuser's credentials to authenticate and create your first page!
118+
119+
|it-works-cms|
120+
121+
.. |it-works-cms| image:: ../images/it-works-cms.png
87122

88123

89-
********************************************
90-
Minimally-required applications and settings
91-
********************************************
124+
***********************************************
125+
Adding django CMS to an existing Django project
126+
***********************************************
92127

93-
Open the new project's ``settings.py`` file in your text editor.
128+
django CMS is nothing more than a powerful set of Django apps. Hence you can add django CMS to any Django project. It might require some settings and URLs to be modified, however. The template project comes with suitable settings. When adding django CMS to your existing project, you need to adjust the settings yourself.
129+
130+
Open the your project's ``settings.py`` file in your text editor.
94131

95132

96133
INSTALLED_APPS
@@ -103,11 +140,9 @@ You will need to add the following to its list of ``INSTALLED_APPS``::
103140
'menus',
104141
'treebeard',
105142

106-
* django CMS needs to use Django's :mod:`django:django.contrib.sites` framework. You'll need to set a ``SITE_ID``
107-
in the settings - ``SITE_ID = 1`` will suffice.
143+
* django CMS needs to use Django's :mod:`django:django.contrib.sites` framework. You'll need to set a ``SITE_ID`` in the settings - ``SITE_ID = 1`` will suffice.
108144
* ``cms`` and ``menus`` are the core django CMS modules.
109-
* `django-treebeard <http://django-treebeard.readthedocs.io>`_ is used to manage django CMS's page and plugin tree
110-
structures.
145+
* `django-treebeard <http://django-treebeard.readthedocs.io>`_ is used to manage django CMS's page and plugin tree structures.
111146

112147
django CMS installs `django CMS admin style <https://github.com/django-cms/djangocms-admin-style>`_.
113148
This provides some styling that helps make django CMS administration components easier to work with.
@@ -136,13 +171,12 @@ For example::
136171
``LANGUAGE_CODE`` setting to ``en``.)
137172

138173

139-
********
140-
Database
141-
********
174+
Database settings
175+
=================
142176

143-
django CMS requires a relational database backend. Each django CMS installation should have its own database.
177+
django CMS requires a relational database backend. Each django CMS installation should have its own database. If you're adding django CMS to an existing project, you will most likely already have your database configured.
144178

145-
You can use SQLite, which is included in Python and doesn't need to be installed separately or configured further. You
179+
If not, you can use SQLite, which is included in Python and doesn't need to be installed separately or configured further. You
146180
are unlikely to be using that for a project in production, but it's ideal for development and exploration, especially
147181
as it is configured by default in a new Django project's :setting:`django:DATABASES`::
148182

@@ -173,39 +207,12 @@ as it is configured by default in a new Django project's :setting:`django:DATABA
173207
for your chosen database backend.
174208

175209

176-
Database tables
177-
===============
210+
Migrating database tables
211+
=========================
178212

179213
Now run migrations to create database tables for the new applications::
180214

181-
python manage.py migrate
182-
183-
184-
Admin user
185-
==========
186-
187-
Create an admin superuser::
188-
189-
python manage.py createsuperuser
190-
191-
192-
*************************************
193-
Using ``cms check`` for configuration
194-
*************************************
195-
196-
Once you have completed the minimum required set-up described above, you can use django CMS's built-in ``cms check``
197-
command to help you identify and install other components. Run::
198-
199-
python manage.py cms check
200-
201-
This will check your configuration, your applications and your database, and report on any problems.
202-
203-
.. note::
204-
205-
If key components are be missing, django CMS will be unable to run the ``cms check command`` and will simply raise
206-
an error instead.
207-
208-
After each of the steps below run ``cms check`` to verify that you have resolved that item in its checklist.
215+
python -m manage migrate
209216

210217

211218
Sekizai
@@ -279,12 +286,8 @@ Also add ``'django.template.context_processors.i18n'`` if it's not already prese
279286
required however.
280287

281288

282-
******************************
283-
Further required configuration
284-
******************************
285-
286-
URLs
287-
====
289+
Adding django CMS' URLs
290+
=======================
288291

289292
In the project's ``urls.py``, add ``re_path(r'^', include('cms.urls'))`` to the ``urlpatterns`` list. It should come after
290293
other patterns, so that specific URLs for other applications can be detected first.
@@ -304,7 +307,7 @@ The django CMS project will now run, as you'll see if you launch it with
304307

305308
.. code-block:: bash
306309
307-
python manage.py runserver
310+
python -m manage runserver
308311
309312
310313
You'll be able to reach it at http://localhost:8000/, and the admin at http://localhost:8000/admin/. You won't yet actually be able to
@@ -414,6 +417,23 @@ work in your ``urls.py``:
414417
(See the Django documentation for guidance on :doc:`serving media files in production
415418
<django:howto/static-files/index>`.)
416419

420+
Using ``cms check`` for configuration
421+
=====================================
422+
423+
Once you have completed the minimum required set-up described above, you can use django CMS's built-in ``cms check``
424+
command to help you identify and install other components. Run::
425+
426+
python -m manage cms check
427+
428+
This will check your configuration, your applications and your database, and report on any problems.
429+
430+
.. note::
431+
432+
If key components are be missing, django CMS will be unable to run the ``cms check command`` and will simply raise
433+
an error instead.
434+
435+
After each of the steps below run ``cms check`` to verify that you have resolved that item in its checklist.
436+
417437

418438
*************************************
419439
Adding content-handling functionality
@@ -442,8 +462,8 @@ To install::
442462
pip install django-filer
443463

444464
A number of applications will be installed as dependencies. `Easy Thumbnails
445-
<https://github.com/SmileyChris/easy-thumbnails>`_ is required to create new versions of images in different sizes;
446-
`Django MPTT <https://github.com/django-mptt/django-mptt/>`_ manages the tree structure of the folders in Django Filer.
465+
<https://github.com/SmileyChris/easy-thumbnails>`_ is required to create new versions of images in different sizes; in older versions of Django Filer
466+
`Django MPTT <https://github.com/django-mptt/django-mptt/>`_ manages the tree structure of the folders in Django Filer - you will not need it if you use Django Filer version 3 and above.
447467

448468
Pillow, the Python imaging library, will be installed. `Pillow <https://github.com/python-pillow/Pillow>`_ needs some
449469
system-level libraries - the `Pillow documentation <https://pillow.readthedocs.io>`_ describes in detail what is
@@ -453,7 +473,6 @@ Add::
453473

454474
'filer',
455475
'easy_thumbnails',
456-
'mptt',
457476

458477
to ``INSTALLED_APPS``.
459478

@@ -470,10 +489,10 @@ You also need to add::
470489

471490
New database tables will need to be created for Django Filer and Easy Thumbnails, so run migrations::
472491

473-
python manage.py migrate filer
474-
python manage.py migrate easy_thumbnails
492+
python -m manage migrate filer
493+
python -m manage migrate easy_thumbnails
475494

476-
(or simply, ``python manage.py migrate``).
495+
(or simply, ``python -m manage migrate``).
477496

478497

479498
Django CMS CKEditor
@@ -489,7 +508,7 @@ Add ``djangocms_text_ckeditor`` to your ``INSTALLED_APPS``.
489508

490509
Run migrations::
491510

492-
python manage.py migrate djangocms_text_ckeditor
511+
python -m manage migrate djangocms_text_ckeditor
493512

494513

495514
Miscellaneous plugins
@@ -524,27 +543,12 @@ to ``INSTALLED_APPS``.
524543

525544
Then run migrations::
526545

527-
python manage.py migrate
546+
python -m manage migrate
528547

529548
These and other plugins are described in more detail in :ref:`commonly-used-plugins`. More are listed
530549
plugins available on the `django CMS Marketplace <https://marketplace.django-cms.org/en/addons/>`_.
531550

532551

533-
******************
534-
Launch the project
535-
******************
536-
537-
Start up the runserver::
538-
539-
python manage.py runserver
540-
541-
and access the new site, which you should now be able to reach at ``http://localhost:8000``. Login if you haven't
542-
done so already.
543-
544-
|it-works-cms|
545-
546-
.. |it-works-cms| image:: ../images/it-works-cms.png
547-
548552
**********
549553
Next steps
550554
**********

0 commit comments

Comments
 (0)
0