diff --git a/.gitignore b/.gitignore index e53bf1c4..bb27c247 100644 --- a/.gitignore +++ b/.gitignore @@ -20,3 +20,4 @@ db.sqlite3 .Trashes .idea/ +.env diff --git a/README.rst b/README.rst index ac29dcd0..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 ###### @@ -38,7 +43,22 @@ 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. -Note: Since Compose V2, ``docker-compose`` is now included inside docker. For more information, checkout the `Compose V2 `_ Documentation. +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 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. Finally 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 @@ -48,15 +68,16 @@ 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. 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 ######## @@ -66,27 +87,38 @@ 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. + If this variable is empty (the default), the PosgreSQL instance in the container is only reachable within docker, but + not from outside. + Deployment Commands =================== @@ -99,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 diff --git a/docker-compose.yml b/compose.yaml similarity index 82% rename from docker-compose.yml rename to compose.yaml index 402f5cbf..83e7d009 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 + - "${DB_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