Skip to content

Python-Backend-Templates/django

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

4 Commits
docker
docker
 
 
nginx
nginx
 
 
postgresql
postgresql
 
 
rabbitmq
rabbitmq
 
 
src
src
 
 
.gitignore
.gitignore
 
 
CHANGELOG.md
CHANGELOG.md
 
 
Makefile
Makefile
 
 
README.md
README.md
 
 

Repository files navigation

Django + PostgreSQL Template

Static Badge Static Badge Static Badge Static Badge Static Badge Static Badge

Оглавление

Разворачивание проекта

Зависимости

  • docker
  • docker compose
  • python 3.8+ (опционально, для локального запуска pytest/flake8/mypy)
  • poetry (опционально, для локального запуска pytest/flake8/mypy)

Окружение

Перед запуском контейнеров, необходимо убедиться, что директории docker присутствует файл .env, в котором заполнены все необходимые переменные окружения.
Названия этих переменных можно посмотреть в .env.example

Подробное описание переменных окружения

REGISTRY

Ссылка на container registry. Необходимо заполнить, если используется compose файл с указанными image для кастомных сборок (например, docker-compose.main.yml)

ENVIRONMENT

Окружение (development, production, testing, etc). Может быть использовано для различных нужд в рамках проекта

PROJECT_NAME

Название проекта

SECRET_KEY

Секретный ключ для Django

DEBUG

Режим отладки
0 - выключен
1 - включен
Если включен, то:

  • 500 ошибки сервера не будут обработаны обработчиком исключений
  • В логах будут отображаться запросы в БД, генерируемые в рамках запроса

PROD

Режим прод окружения
0 - выключен
1 - включен
Если выключен, то:

  • Будет доступна документация swagger-ui/redoc
  • Работа с платежными системами будет работать в боевом режиме
  • Чувствительные данные будут исключены из логов

MEDIA_PATH

Путь к директории, в которой хранятся медиа-файлы

MEDIA_URL

Префикс в ссылке для медиа-файлов

STATIC_PATH

Путь к директории, в которой хранятся статические файлы

STATIC_URL

Префикс в ссылке для статических-файлов

LOG_PATH

Путь к директории, в которой хранятся лог-файлы

IN_GUNICORN

Флаг, который определяет, запускается ли проект через gunicorn

Database

При первом запуске DB_NAME, DB_USER, DB_PASSWORD могут быть любыми
При дальнейших запусках DB_NAME, DB_USER, DB_PASSWORD должны быть такими же, как при первом запуске
DB_HOST должен соответствовать названию сервиса БД из compose конфигурации
DB_PORT должен соответствовать порту БД из compose конфигурации

Nginx

NGINX_OUTER_PORT - порт, через который можно обращаться к контейнеру nginx
NGINX_INNER_PORT - порт, на который будут переадресовываться все запросы внутри контейнера nginx

WSGI

WSGI_PORT - порт, по которому можно обращаться к wsgi сервису

RabbitMQ

RABBITMQ_HOST должен соответствовать названию сервиса RabbitMQ из compose конфигурации
RABBITMQ_PORT - любой доступный на хосте порт
При первом запуске RABBITMQ_USER, RABBITMQ_PASSWORD могут быть любыми
При дальнейших запусках RABBITMQ_USER, RABBITMQ_PASSWORD должны быть такими же, как при первом запуске

Celery

CELERY_BROKER_URL - ссылка для доступа к брокеру сообщений
CELERY_RESULT_BACKEND - бэкенд для хранения результатов выполнения задач

Redis

REDIS_HOST должен соответствовать названию сервиса Redis из compose конфигурации
REDIS_PORT - любой доступный на хосте порт
REDIS_PASSWORD - пароль от пользователя default

Logging

LOGGING_SENSITIVE_FIELDS - чувствительные поля, которые нужно игнорировать при записи лога. Должны быть разделены через запятую, без пробелов
LOGGING_LOGGERS - названия логеров. Должны быть разделены через запятую, без пробелов
LOGGING_MAX_BYTES - максимальное кол-во байт на один лог файл
LOGGING_BACKUP_COUNT - максимальное кол-во бэкап файлов для логов

Docker Compose Specific

RESTART_POLICY - политика рестарта контейнеров
NGINX_VERSION - версия Nginx
POSTGRES_VERSION - версия PostgreSQL
REDIS_VERSION - версия Redis
RABBITMQ_VERSION - версия Rabbitmq
WSGI_TARGET - образ для сборки wsgi сервиса
CELERY_TARGET - образ для сборки celery worker сервиса
BEAT_TARGET - образ для сборки celery beat сервиса
*_CPUS - лимит ядер на контейнер
*_MEM_LIMIT - лимит памяти на контейнер
*_MEM_RESERVATION - запас памяти на контейнер

Tracing

TRACING_EXPORTER_ENDPOINT - эндпоинт для отправки трейсов
OTEL_PYTHON_DJANGO_INSTRUMENT - вкл/выкл трейсинг

Запуск в локальном окружении

docker-compose -f docker/docker-compose.yml -f docker/docker-compose.local.yml up

или

make localup

После запуска проект будет доступен по адресу http://localhost:.../

Запуск в тестовом окружении

docker-compose up

или

make up

Запуск в прод окружении

docker-compose -f docker/docker-compose.yml -f docker/docker-compose.main.yml up

или

make mainup

После запуска

Проект станет доступен по порту ${NGINX_OUTER_PORT}
В локальном окружении достаточно перейти по адресу http://localhost:${NGINX_OUTER_PORT}/
В другом окружении необходимо настроить домен, при обращении к которому веб-сервер (Nginx/Apache) будет проксировать все запросы на порт ${NGINX_OUTER_PORT}

Возможные ошибки

Если на хосте установлена docker compose версии >2, то может возникнуть ошибка синтаксиса команды. В таком случае в командах выше нужно заменить

docker-compose

на

docker compose

Стэк

Основные инструменты

  • Используемый язык программирования — Python ...
  • Используемый фреймворк — Django ...
  • Используемая СУБД — PostgreSQL ...
  • Используемая для кэширования NoSQL БД — Redis ...
  • Используемый брокер сообщений — RabbitMQ ...
  • Используемая асинхронная очередь задач — Celery ...

Другие библиотеки / интеграции

  • gunicorn (...) — HTTP-сервер для Django
  • psycopg (...) — библиотека для работы с PostgreSQL в Python
  • redis (...) — библиотека для работы с Redis в Python
  • Celery (...) — библиотека для асинхронных очередей задач
  • amqp (...) — библиотека для работы с amqp-протоколом
  • JSON-log-formatter (...) — библиотека для форматирования логов в JSON-формате
  • dependency-injector (...) — библиотека для внедрения зависимостей (DI)
  • pytest (...) — библиотека для тестирования
  • pytest-django (...) — библиотека для тестирования Django-приложений через pytest
  • pytest-cov (...) — библиотека для оценки покрытия кода тестами через pytest
  • pytest-mock (...) — библиотека для мока зависимостей через pytest
  • pytest-timeout (...) — библиотека для ограничения времени выполнения тестов через pytest
  • concurrent-log-handler (...) — библиотека для последовательной записи логов в файлы при запуске веб приложения через несколько воркеров (как в gunicorn)
  • mypy (...) — статический анализатор типов
  • flake8 (...) — инструмент линтинга для Python
  • black (...) — библиотека для форматирования кода на языке Python
  • isort (...) - библиотека для сортировки импортов

Запуск тестов

Внутри Docker-контейнера (рекомендуется)

  1. Зайти в контейнер wsgi через команду

    docker exec -it ${PROJECT_NAME}-wsgi bash

  2. Начать выполнение тестов через команду

    pytest

или

make test

Вне Docker-контейнера

При таком запуске тесты, в которых тестируется работа с БД, выполнятся с ошибкой
При ошибке выполнения команды запустите тесты внутри Docker-контейнера

  1. Перейти в директорию с конфигурационным файлом

  2. Начать выполнение тестов через команду

    poetry run pytest

Запуск Flake8

Внутри Docker-контейнера (рекомендуется)

  1. Зайти в контейнер wsgi через команду

    docker exec -it ${PROJECT_NAME}-wsgi bash

  2. Начать выполнение flake8 через команду

    flake8 .

или

make flake8

Вне Docker-контейнера

  1. Перейти в директорию с конфигурационным файлом

  2. Начать выполнение flake8 через команду

    poetry run flake8 .

Запуск mypy

Внутри Docker-контейнера (рекомендуется)

  1. Зайти в контейнер wsgi через команду

    docker exec -it ${PROJECT_NAME}-wsgi bash

  2. Начать выполнение mypy через команду

    mypy .

или

make mypy

Вне Docker-контейнера

При возникновении ошибок запуск возможен только внутри Docker-контейнера

  1. Перейти в директорию с конфигурационным файлом

  2. Начать выполнение mypy через команду

    poetry run mypy .

Разработка

Форматирование кода

При разработке рекомендуется использовать black, чтобы поддерживать чистоту кода и избегать лишних изменений при работе с гитом.
Пример конфигурационного файла для Visual Studio Code .vscode/settings.json:

{
    "[python]": {
        "editor.defaultFormatter": "ms-python.black-formatter",
        "editor.formatOnSave": true
    }
}

Git хуки

При разработке рекомендуется использовать pre-commit, чтобы перед формированием МР код был уже подготовленным и поверхностно проверенным (например, через flake8)

Для использования должны быть установлены dev-зависимости

Pre-commit хуки

Установка

poetry run pre-commit install

Удаление

poetry run pre-commit uninstall

После установки, при каждом коммите будут отрабатывать хуки из конфигурационного файла, предназначенные для коммитов (stages: [commit])

Pre-push хуки

Установка

poetry run pre-commit install --hook-type pre-push

Удаление

poetry run pre-commit uninstall -t pre-push

После установки, при каждом пуше будут отрабатывать хуки из конфигурационного файла, предназначенные для пушей (stages: [push])

Git хуки

При разработке рекомендуется использовать pre-commit, чтобы перед формированием МР код был уже подготовленным и поверхностно проверенным (например, через flake8)

Для использования должны быть установлены dev-зависимости

Pre-commit хуки

Установка

poetry run pre-commit install

Удаление

poetry run pre-commit uninstall

После установки, при каждом коммите будут отрабатывать хуки из конфигурационного файла, предназначенные для коммитов (stages: [commit])

Pre-push хуки

Установка

poetry run pre-commit install --hook-type pre-push

Удаление

poetry run pre-commit uninstall -t pre-push

После установки, при каждом пуше будут отрабатывать хуки из конфигурационного файла, предназначенные для пушей (stages: [push])

Make

Для удобного запуска контейнеров, их сборки, запуска тестов и т.п. в проекте есть Makefile

Для выполнения инструкции, на примере запуска тестов, нужно выполнить команду

make test

Git Flow

Основные правила работы с ветками на проекте:

  • develop — ветка разработки.
    • Собирается и разворачивается на dev-сервере;
  • feature/{feature-slug} — feature-ветка.
    • Создается только из ветки develop;
    • По готовности создается MR в ветку develop.
  • bugfix/{bug-slug} — bugfix-ветка.
    • Создается только из ветки develop;
    • По готовности создается MR в ветку develop.
  • release/{major}.{minor} — release-ветка.
    • Создается только из ветки develop;
    • Считается как release-candidate;
    • Собирается и разворачивается на stage-сервере (пока не утверждено, как вариант);
    • Прямо в ветке могут быть пофикшены баги, без MR;
    • Все пофикшенные в ветке баги должны быть смержены в develop, желательно сразу по готовности бага, чтобы не упустить фикс;
    • По готовности создается MR в ветку main.
    • Правила изменения версии релиза:
      • minor версия увеличивается при изменениях, не нарушающих обратную совместимость. Т.е. при этих изменениях пользователи API продолжат работу без необходимости вносить изменения;
      • major версия увеличивается при изменениях, нарушающих обратную совместимость.
        • В идеале, major версия должна совпадать с последней версией API, т.к. новая версия API внедряется по такому же принципу - при появлении изменений, нарушающих обратную совместимость.
  • hotfix/{bug-slug} — hotfix-ветка.
    • Создается только из ветки main;
    • По готовности создается MR в ветку main.
  • main — прод ветка.
    • Собирается и разворачивается на prod-сервере;
    • После слияния MR в эту ветку создается tag и release по этой ветке (т.е. по последнему коммиту этой ветки).

CI/CD

Dev-сервер

TBD

Prod-сервер

TBD

Release ветки

TBD

Выпуск релиза

TBD

CHANGELOG.md

Заметки о релизах ведутся начиная с версии 1.0.0

По готовности релиза в release/* ветке или при хотфиксе в hotfix/* ветке, нужно обновить файл CHANGELOG.md.

Заметки о новом релизе добавляются в начало файла, т.е. до предыдущего релиза. Шаблон заметки о релизе

## 1.1.0 (2024-01-01)

Security:

  -   

Features:

  - 

Bugfixes:

  -

При необходимости, можно вести заметки о будущем релизе прямо в ветке develop. В таком случае, вместо даты релиза нужно писать unreleased, который потом следует заменить на фактическую дату релиза

## 1.2.0 (unreleased)

Security:

  -   

Features:

  - 

Bugfixes:

  -

About

No description, website, or topics provided.

Resources

Readme
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages