Overview ======== System requirements ------------------- - ``git`` with a version at least ``2.16`` or higher - ``docker`` with a version at least ``18.02`` or higher - ``docker-compose`` with a version at least ``1.21`` or higher - ``python`` with exact version, see ``pyproject.toml`` Architecture ------------ config ~~~~~~ - ``config/.env.template`` - a basic example of what keys must be contained in your ``.env`` file, this file is committed to VCS and must not contain private or secret values - ``config/.env`` - main file for secret configuration, contains private and secret values, should not be committed to VCS root project ~~~~~~~~~~~~ - ``README.md`` - main readme file, it specifies the entry point to the project's documentation - ``.dockerignore`` - specifies what files should not be copied to the ``docker`` image - ``.editorconfig`` - file with format specification. You need to install the required plugin for your IDE in order to enable it - ``.gitignore`` - file that specifies what should we commit into the repository and we should not - ``.gitlab-ci.yml`` - GitLab CI configuration file. It basically defines what to do with your project after pushing it to the repository. Currently it is used for testing and releasing a ``docker`` image - ``.python-version`` - file that specifies the Python version to be used for the project, particularly when using `pyenv`. This file helps in maintaining a consistent Python environment across different machines and environments - ``CHANGELOG.md`` - file that contains a chronological log of all notable changes made to the project. It provides a comprehensive overview of the project's evolution and helps users and contributors understand the development history - ``docker-compose.yml`` - this the file specifies ``docker`` services that are needed for development and testing - ``docker-compose.override.yml`` - local override for ``docker-compose``. Is applied automatically and implicitly when no arguments provided to ``docker-compose`` command - ``manage.py`` - main file for your ``django`` project. Used as an entry point for the ``django`` project - ``pyproject.toml`` - main file of the project. It defines the project's dependencies. - ``poetry.lock`` - lock file for dependencies. It is used to install exactly the same versions of dependencies on each build - ``setup.cfg`` - configuration file, that is used by all tools in this project - ``locale/`` - helper folder, that is used to store locale data, empty by default - ``scripts/`` - helper folder, that contains various development scripts and teardown for local development server ~~~~~~ - ``server/__init__.py`` - package definition, empty file - ``server/urls.py`` - ``django`` `urls definition `_ - ``server/wsgi.py`` - ``django`` `wsgi definition `_ - ``server/asgi.py`` - ``django`` `asgi definition `_ - ``server/apps/`` - place to put all your apps into - ``server/apps/main`` - ``django`` application, used as an example, could be removed - ``server/settings`` - settings defined with ``django-split-settings``, see this `tutorial `_ for more information - ``server/templates`` - external folder for ``django`` templates, used for simple files as ``robots.txt`` and so on docker ~~~~~~ - ``docker/docker-compose.prod.yml`` - additional service definition file used for production - ``docker/django/Dockerfile`` - ``django`` container definition, used both for development and production - ``docker/django/entrypoint.sh`` - entry point script that is used when ``django`` container is starting - ``docker/django/gunicorn_config.py`` - that's how we configure ``gunicorn`` runner - ``docker/django/gunicorn.sh`` - production script for ``django`` using ``gunicorn`` - ``docker/django/ci.sh`` - file that specifies all possible checks that we execute during our CI process for django - ``docker/caddy/Caddyfile`` - configuration file for Caddy webserver - ``docker/caddy/ci.sh`` - file that specifies all possible checks that we execute during our CI process for caddy tests ~~~~~ - ``tests/plugins`` - ``pytest`` plugins that are used in this project - ``tests/test_server`` - tests that ensures that basic ``django`` stuff is working, should not be removed - ``tests/test_apps/test_main`` - example tests for the ``django`` app, could be removed - ``tests/conftest.py`` - main configuration file for ``pytest`` runner docs ~~~~ - ``docs/Makefile`` - command file that builds the documentation for Unix - ``docs/make.bat`` - command file for Windows - ``docs/conf.py`` - ``sphinx`` configuration file - ``docs/index.rst`` - main documentation file, used as an entry point - ``docs/pages/project`` - folder that will contain documentation written by you! - ``docs/pages/template`` - folder that contains documentation that is common for each project built with this template - ``docs/documents`` - folder that should contain any documents you have: spreadsheets, images, requirements, presentations, etc - ``docs/README.md`` - helper file for this directory, just tells what to do next Container internals ------------------- We use the ``docker-compose`` to link different containers together. We also utilize different ``docker`` networks to control access. Some containers might have long starting times, for example: - ``postgres`` - ``rabbitmq`` - frontend, like ``node.js`` To be sure that container is started at the right time, we utilize ``wait-for-it`` `script `_. It is executed inside ``docker/django/entrypoint.sh`` file. We start containers with ``tini``. Because this way we have a proper signal handling and eliminate zombie processes. Read the `official docs `_ to know more.