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.