From 2d5a1d58979da0cd09666f119f830e4a7c0ba179 Mon Sep 17 00:00:00 2001 From: Jens-Erik Weber Date: Fri, 11 Aug 2023 13:13:47 +0200 Subject: [PATCH 1/5] Make database persistent, set ext. postgres port with env. variable, docs Create a named volume in order to keep the database content after containers have been deleted with docker compose down. To access the postgres instance in the docker container from the host, an external port number can be set. Update documentation --- .gitignore | 1 + README.rst | 22 +++++++++++++++++++++- docker-compose.yml => compose.yaml | 9 ++++++--- requirements.in | 2 +- 4 files changed, 29 insertions(+), 5 deletions(-) rename docker-compose.yml => compose.yaml (82%) diff --git a/.gitignore b/.gitignore index e53bf1c4..97e759ba 100644 --- a/.gitignore +++ b/.gitignore @@ -20,3 +20,4 @@ db.sqlite3 .Trashes .idea/ +/.env diff --git a/README.rst b/README.rst index ac29dcd0..eabcfe50 100644 --- a/README.rst +++ b/README.rst @@ -38,6 +38,20 @@ Try it Then open http://django-cms-quickstart.127.0.0.1.nip.io:8000 (or just http://127.0.0.1:8000) in your browser. +You can stop the server with ``docker compose stop`` without destroying the containers and restart it with +``docker compose start``. + +With ``docker compose down`` the containers are deleted, but the database content ist still preserved in the named +volume ``django-cms-quickstart_postgres-data`` and the media files are stored in the file system in ``data/media``. +Then you can update the project e. g. by changing the requirements and settings. Then you can rebuild the web image +and start the server again: + +.. code-block:: bash + + docker compose build web + docker compose up -d + + Note: Since Compose V2, ``docker-compose`` is now included inside docker. For more information, checkout the `Compose V2 `_ Documentation. .. inclusion-end-marker-do-not-remove @@ -56,7 +70,8 @@ Options are also available for using Postgres/MySQL, uWSGI/Gunicorn/Guvicorn, et Updating requirements ===================== -The project uses a 2 step approach, freezing all dependencies with pip-tools. Read more about how to handle it here: https://blog.typodrive.com/2020/02/04/always-freeze-requirements-with-pip-compile-to-avoid-unpleasant-surprises/ +The project uses a 2 step approach, freezing all dependencies with pip-tools. Read more about how to handle it here: +https://blog.typodrive.com/2020/02/04/always-freeze-requirements-with-pip-compile-to-avoid-unpleasant-surprises/ Features ######## @@ -87,6 +102,11 @@ Env variables - to deploy this project in testing mode (recommended) set the environment variable ``DEBUG`` to ``True`` in your hosting environment. - For production environment (if ``DEBUG`` is false) django requires you to whitelist the domain. Set the env var ``DOMAIN`` to the host, i.e. ``www.domain.com`` or ``*.domain.com``. - If you want the media hosted on S3 set the ``DEFAULT_FILE_STORAGE`` variable accordingly. +- If you want to access the PostgreSQL database from the host system, set ``EXT_PG_PORT`` to the desired port number. + 5432 is the standard port number. If you run a PosgreSQL on your host system, you may want to set another port number. + If this variable is empty (the default), the PosgreSQL instance in the container is only reachable within docker, but + not from outside. + Deployment Commands =================== diff --git a/docker-compose.yml b/compose.yaml similarity index 82% rename from docker-compose.yml rename to compose.yaml index 402f5cbf..31886c56 100644 --- a/docker-compose.yml +++ b/compose.yaml @@ -21,9 +21,9 @@ services: database_default: # Select one of the following db configurations for the database - image: postgres:13.5-alpine + image: postgres:15-alpine ports: - - "5432:5432/tcp" # allow your local dev env to connect to the db + - "${EXT_PG_PORT-}:5432/tcp" # allow your local dev env to connect to the db if variable set environment: POSTGRES_DB: "db" POSTGRES_PASSWORD: "password" @@ -34,7 +34,10 @@ services: - djangocmsnet volumes: - - ".:/app:rw" + - postgres-data:/var/lib/postgresql/data/ networks: djangocmsnet: + +volumes: + postgres-data: \ No newline at end of file diff --git a/requirements.in b/requirements.in index 3f9a32bd..f30c8759 100644 --- a/requirements.in +++ b/requirements.in @@ -1,5 +1,5 @@ # Compile this file for changes to take effect: -# pip-compile requirements.in >> requirements.txt +# pip-compile -U --resolver=backtracking boto3 psycopg2 From d07c08a1535867deb689beade078d25a515455c1 Mon Sep 17 00:00:00 2001 From: Jens-Erik Weber Date: Fri, 11 Aug 2023 16:57:51 +0200 Subject: [PATCH 2/5] Update .gitignore Co-authored-by: Mark Walker --- .gitignore | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.gitignore b/.gitignore index 97e759ba..bb27c247 100644 --- a/.gitignore +++ b/.gitignore @@ -20,4 +20,4 @@ db.sqlite3 .Trashes .idea/ -/.env +.env From b1aa6f4e97d6ad48bc50eb7259cf3736d0752520 Mon Sep 17 00:00:00 2001 From: Jens-Erik Weber Date: Fri, 11 Aug 2023 16:58:35 +0200 Subject: [PATCH 3/5] Update compose.yaml more generic, shorter db port name Co-authored-by: Mark Walker --- compose.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/compose.yaml b/compose.yaml index 31886c56..83e7d009 100644 --- a/compose.yaml +++ b/compose.yaml @@ -23,7 +23,7 @@ services: # Select one of the following db configurations for the database image: postgres:15-alpine ports: - - "${EXT_PG_PORT-}:5432/tcp" # allow your local dev env to connect to the db if variable set + - "${DB_PORT-}:5432/tcp" # allow your local dev env to connect to the db if variable set environment: POSTGRES_DB: "db" POSTGRES_PASSWORD: "password" From ad916ba73a2936c65d5d813b06ebe473df704a40 Mon Sep 17 00:00:00 2001 From: Jens-Erik Weber Date: Fri, 11 Aug 2023 18:31:38 +0200 Subject: [PATCH 4/5] Reflect renaming of the db port env. variable to DB_PORT in the docs --- README.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.rst b/README.rst index eabcfe50..7f05a374 100644 --- a/README.rst +++ b/README.rst @@ -102,8 +102,8 @@ Env variables - to deploy this project in testing mode (recommended) set the environment variable ``DEBUG`` to ``True`` in your hosting environment. - For production environment (if ``DEBUG`` is false) django requires you to whitelist the domain. Set the env var ``DOMAIN`` to the host, i.e. ``www.domain.com`` or ``*.domain.com``. - If you want the media hosted on S3 set the ``DEFAULT_FILE_STORAGE`` variable accordingly. -- If you want to access the PostgreSQL database from the host system, set ``EXT_PG_PORT`` to the desired port number. - 5432 is the standard port number. If you run a PosgreSQL on your host system, you may want to set another port number. +- If you want to access the PostgreSQL database from the host system, set ``DB_PORT`` to the desired port number. + 5432 is the standard port number. If you run PosgreSQL on your host system, you may want to set another port number. If this variable is empty (the default), the PosgreSQL instance in the container is only reachable within docker, but not from outside. From 5bc367b7a82eb25289124b076b4ae48ce7c1220d Mon Sep 17 00:00:00 2001 From: Jens-Erik Weber Date: Mon, 14 Aug 2023 11:49:16 +0200 Subject: [PATCH 5/5] Fix typos, version numbers in the documentation, formatting Update version numbers in the documentation Keep line length to max. 120 where possible --- README.rst | 50 ++++++++++++++++++++++++++++++++------------------ 1 file changed, 32 insertions(+), 18 deletions(-) diff --git a/README.rst b/README.rst index 7f05a374..d688368f 100644 --- a/README.rst +++ b/README.rst @@ -4,21 +4,26 @@ django CMS quickstart ##################### -A Dockerised django CMS project, ready to deploy on `Divio `_ or another Docker-based cloud platform, and run locally in Docker on your own machine. +A dockerised django CMS project, ready to deploy on `Divio `_ or another Docker-based cloud +platform, and run locally in Docker on your own machine. -This version uses Python 3.10 running and the most up-to-date versions of Django 3.2, and django CMS 4.1.0rc1 +This version uses Python 3.11 and the most up-to-date versions of Django 3.2, and django CMS 4.1.0rc3 -This project is endorsed by the `django CMS Association `_. That means that it is officially accepted by the dCA as being in line with our roadmap vision and development/plugin policy. Join us on `Slack `_ for more information or questions. +This project is endorsed by the `django CMS Association `_. That means that it +is officially accepted by the dCA as being in line with our roadmap vision and development/plugin policy. Join us on +`Slack `_ for more information or questions. -The documentation for version 4.1 is still work in progress and - for the time being - can be found here: https://django-cms-docs.readthedocs.io/en/latest/ +The documentation for version 4.1 is still work in progress and - for the time being - can be found here: +https://django-cms-docs.readthedocs.io/en/latest/ Installation ############ -You need to have docker installed on your system to run this project. +You need to have Docker installed on your system to run this project. - `Install Docker `_ here. -- If you have not used docker in the past, please read this `introduction on docker `_ here. +- If you have not used docker in the past, please read this + `introduction on docker `_ here. Try it ###### @@ -41,9 +46,9 @@ Then open http://django-cms-quickstart.127.0.0.1.nip.io:8000 (or just http://127 You can stop the server with ``docker compose stop`` without destroying the containers and restart it with ``docker compose start``. -With ``docker compose down`` the containers are deleted, but the database content ist still preserved in the named +With ``docker compose down`` the containers are deleted, but the database content is still preserved in the named volume ``django-cms-quickstart_postgres-data`` and the media files are stored in the file system in ``data/media``. -Then you can update the project e. g. by changing the requirements and settings. Then you can rebuild the web image +Then you can update the project e. g. by changing the requirements and settings. Finally you can rebuild the web image and start the server again: .. code-block:: bash @@ -52,7 +57,8 @@ and start the server again: docker compose up -d -Note: Since Compose V2, ``docker-compose`` is now included inside docker. For more information, checkout the `Compose V2 `_ Documentation. +Note: Since Compose V2, ``docker-compose`` is now included inside docker. For more information, checkout the +`Compose V2 `_ Documentation. .. inclusion-end-marker-do-not-remove @@ -62,8 +68,8 @@ Customising the project This project is ready-to-go without making any changes at all, but also gives you some options. As-is, it will include a number of useful django CMS plugins and Bootstrap 4 for the frontend. You don't have to use -these; they're optional. If you don't want to use them, read through the ``settings.py`` and ``requirements.txt`` files to -see sections that can be removed - in each case, the section is noted with a comment containing the word 'optional'. +these; they're optional. If you don't want to use them, read through the ``settings.py`` and ``requirements.txt`` files +to see sections that can be removed - in each case, the section is noted with a comment containing the word 'optional'. Options are also available for using Postgres/MySQL, uWSGI/Gunicorn/Guvicorn, etc. @@ -81,26 +87,32 @@ Static Files with Whitenoise This quickstart demo has a cloud-ready static files setup via django-whitenoise. -In the containerized cloud the application is not served by a web server like nginx but directly through uwsgi. django-whitenoise is the glue that's needed to serve static files in your application directly through uwsgi. +In the containerized cloud the application is not served by a web server like nginx but directly through uwsgi. +django-whitenoise is the glue that's needed to serve static files in your application directly through uwsgi. -See the django-whitenoise settings in settings.py and the ``quickstart/templates/whitenoise-static-files-demo.html`` demo page template that serves a static file. +See the django-whitenoise settings in settings.py and the ``quickstart/templates/whitenoise-static-files-demo.html`` +demo page template that serves a static file. Contribution ############ -Here is the official django CMS repository: `https://github.com/django-cms/django-cms-quickstart/ `_. +Here is the official django CMS repository: +`https://github.com/django-cms/django-cms-quickstart/ `_. Deployment ########## -Note that this is just a demo project to get you started. If you want a full production ready site with all the bells and whistles we recommend you have a look at https://github.com/django-cms/djangocms-template instead. +Note that this is just a demo project to get you started. If you want a full production ready site with all the bells +and whistles we recommend you have a look at https://github.com/django-cms/djangocms-template instead. Env variables ============= -- to deploy this project in testing mode (recommended) set the environment variable ``DEBUG`` to ``True`` in your hosting environment. -- For production environment (if ``DEBUG`` is false) django requires you to whitelist the domain. Set the env var ``DOMAIN`` to the host, i.e. ``www.domain.com`` or ``*.domain.com``. +- to deploy this project in testing mode (recommended) set the environment variable ``DEBUG`` to ``True`` in your + hosting environment. +- For production environment (if ``DEBUG`` is false) django requires you to whitelist the domain. Set the env var + ``DOMAIN`` to the host, i.e. ``www.domain.com`` or ``*.domain.com``. - If you want the media hosted on S3 set the ``DEFAULT_FILE_STORAGE`` variable accordingly. - If you want to access the PostgreSQL database from the host system, set ``DB_PORT`` to the desired port number. 5432 is the standard port number. If you run PosgreSQL on your host system, you may want to set another port number. @@ -119,7 +131,9 @@ Configure your hosting environment to run the following commands on every deploy Divio Deployment ================ -divio.com is a cloud hosting platform optimized for django web applications. It's the quickest way to deploy this project. Here is a `video tutorial `_ and a `description of the deployment steps `_ that are mostly applicable for this quickstart project. +divio.com is a cloud hosting platform optimized for django web applications. It's the quickest way to deploy this +project. Here is a `video tutorial `_ and a +`description of the deployment steps `_ that are mostly applicable for this quickstart project. .. |pythonapp| image:: https://github.com/django-cms/django-cms-quickstart/workflows/Python%20application/badge.svg?branch=support/cms-4.1.x