FreshBalance

ИС для автоматизации фитнес-кафе с публичным меню, заказами, техкартами, складом, live-статусами и backoffice.

Основной стек:

• Django 5
• PostgreSQL
• Redis
• Nginx
• Celery Worker
• Celery Beat
• Flower
• Tailwind CSS через django-tailwind-cli, без node
• Docker и docker compose
• .env и автоматическая генерация DJANGO_SECRET_KEY
• однократная подготовка через do.py

Основная идея

Шаблон теперь работает в docker-first режиме.

Основной сценарий не создает .venv и не поднимает Django/Celery локально. Весь runtime-стек запускается только в контейнерах.

Локальный Python нужен только для:

• запуска do.py
• переименования шаблона
• генерации .env

Старые shell-скрипты под локальный .venv удалены. Вспомогательные команды теперь тоже завязаны только на Docker. Контейнерный runtime больше не зависит от do.py: bootstrap вынесен в отдельный одноразовый сервис bootstrap, а web только стартует Django. Внешняя точка входа в приложение теперь идет через nginx, а сам Django-контейнер живет только во внутренней docker-сети.

Placeholder-имена шаблона

Изначально используются такие имена:

• пакет проекта: workspace
• отображаемое имя проекта: Workspace
• основной app: core

Быстрый старт

Новый проект

1. Один раз подготовьте шаблон:

Linux/macOS:

python3 ./do.py --project-name PetTrace --app-name core

Windows:

python .\do.py --project-name PetTrace --app-name core

Можно и без аргументов. Если шаблон еще не переименован, do.py спросит имя проекта и app в консоли.

2. После этого запускайте проект обычным Docker-способом:

docker compose up --build

Для фонового режима:

docker compose up -d --build

Уже подготовленный проект

Если .env уже создан и rename уже выполнен, do.py больше не нужен для обычной работы.

Основной запуск:

docker compose up --build

Что делает do.py:

• при необходимости переименовывает шаблон
• создает .env из .env.example
• генерирует DJANGO_SECRET_KEY
• при конфликте старых docker volumes предлагает удалить только связанные legacy-ресурсы
• подготавливает проект к обычному запуску через docker compose

После успешного rename скрипт пытается удалить унаследованный .git. Если Windows блокирует .git, setup больше не падает: будет предупреждение, и папку можно удалить вручную позже.

Разовый setup

Сейчас do.py всегда работает как разовый подготовительный скрипт и не держит runtime-стек. Флаг --prepare-only оставлен только для обратной совместимости и эквивалентен обычному запуску do.py.

python3 ./do.py --prepare-only

Docker-only поведение

Теперь postgres и redis не публикуются наружу на хост. Они доступны только внутри docker-сети проекта.

Наружу публикуются только:

• NGINX_PORT для основного сайта
• FLOWER_BIND для Flower

По умолчанию:

• http://127.0.0.1/
• http://localhost/
• http://127.0.0.1:5555/

Сам web контейнер наружу не публикуется. nginx проксирует запросы во внутренний Django-сервис, поэтому в браузере можно заходить без явного :8000.

Первый docker compose up --build сам:

• собирает образы
• поднимает postgres, redis, одноразовый bootstrap, затем nginx, web, celery_worker, celery_beat, flower
• выполняет bootstrap Django в отдельном контейнере bootstrap
• запускает Tailwind watcher в dev-режиме

web больше не мигрирует БД сам при старте. Это сделано специально, чтобы:

• запуск через docker compose up --build работал без do.py
• bootstrap не прятался внутри web
• ошибка инициализации была видна в логах сервиса bootstrap

Если bootstrap не проходит, сначала смотрите:

docker compose logs bootstrap

Если в логе есть ошибка вида auth_user does not exist или сообщение про stale/corrupted migration state, почти всегда виноват старый volume PostgreSQL:

docker compose down -v --remove-orphans
docker compose up --build

Если нужен доступ к PostgreSQL или Redis с хоста, порты нужно добавить в docker-compose.yml вручную.

Tailwind и live-режим

В dev-режиме контейнерный web сервис запускается через:

python manage.py tailwind runserver

Поэтому:

• HTML подхватывается сразу
• обычные CSS/JS static-файлы подхватываются сразу
• Tailwind пересобирается автоматически
• collectstatic для разработки не нужен

Для dev-режима в шаблоне включен polling-based watch поверх django-tailwind-cli. Это сделано специально, потому что штатный Tailwind watch на bind mount'ах и на Windows может пропускать изменения или оставлять в выходном CSS уже неиспользуемые классы.

Переменные окружения

Файл шаблона:

.env.example

Рабочий файл:

.env

Базовые переменные:

• PROJECT_NAME
• PROJECT_SLUG
• DJANGO_ENV
• DJANGO_DEBUG
• DJANGO_SECRET_KEY
• DJANGO_ALLOWED_HOSTS
• DJANGO_CSRF_TRUSTED_ORIGINS
• DATABASE_URL
• POSTGRES_DB
• POSTGRES_USER
• POSTGRES_PASSWORD
• POSTGRES_HOST
• POSTGRES_PORT
• REDIS_URL
• CELERY_BROKER_URL
• CELERY_RESULT_BACKEND
• NGINX_PORT
• FLOWER_BIND
• DATABASE_CONN_MAX_AGE
• DATABASE_CONN_HEALTH_CHECKS
• DJANGO_SESSION_COOKIE_SECURE
• DJANGO_CSRF_COOKIE_SECURE
• DJANGO_SECURE_SSL_REDIRECT
• DJANGO_SECURE_HSTS_SECONDS
• TAILWIND_CLI_SRC_CSS (src/workspace/tailwind.src.css)

По умолчанию .env.example уже настроен под docker-сеть:

• POSTGRES_HOST=postgres
• REDIS_HOST=redis
• COMPOSE_PROJECT_NAME=PROJECT_SLUG
• NGINX_PORT=80

Healthchecks и pre-release

Для runtime теперь есть две служебные точки:

• /health/ — liveness, быстрый ответ без зависимостей
• /ready/ — readiness, проверка БД и cache backend

В docker compose добавлены healthcheck'и для web и nginx, поэтому nginx ждет именно готовый Django-контур, а не просто старт процесса.

Перед релизом можно прогнать preflight:

docker compose run --rm web python manage.py preflight_release

Команда:

• запускает check --deploy
• валидирует критичные env/runtime-настройки
• проверяет readiness БД и кеша

Если нужен только runtime без cache-пинга:

docker compose run --rm web python manage.py preflight_release --skip-cache

Демо-наполнение

Для демонстрации подготовлен сидер, который разворачивает:

• 3 месяца операционной истории
• заказы, оплаты, частичные возвраты и split payment
• закупки, партии, инвентаризации и смены
• текущие live-заказы для стойки, кухни и публичного статуса
• демо-пользователей по ролям

Запуск:

python manage.py seed_demo_data --reset --months 3

Демо-аккаунты:

• director / freshbalance123
• operations / freshbalance123
• manager / freshbalance123
• barista / freshbalance123
• waiter / freshbalance123

CI/CD и production deploy

В репозитории подготовлен production-контур:

• GitHub Actions: .github/workflows/ci-cd.yml
• прод-overrides compose: docker-compose.prod.yml
• systemd units: deploy/systemd/
• скрипт раскатки: scripts/deploy_prod.sh
• пример Caddy site block: deploy/caddy/freshbalance.Caddyfile

Ожидаемый цикл:

1. push в main
2. GitHub Actions прогоняет миграции, сидер, тесты и preflight_release
3. workflow обновляет ветку deploy/prod
4. серверный timer подтягивает deploy/prod и запускает scripts/deploy_prod.sh

Целевой production path:

/srv/freshbalance

Системные unit-файлы:

• freshbalance-stack.service
• freshbalance-deploy.service
• freshbalance-deploy.timer

Smoke-check после деплоя проверяет:

• /
• /health/
• /ready/
• /staff/login/
• /backoffice/ (redirect expected)

Полезные флаги

Переименование при запуске:

python3 ./do.py --project-name ITUWebsite --app-name core

Пропустить rename:

python3 ./do.py --skip-rename

Только подготовить окружение:

python3 ./do.py --prepare-only

Справка:

python3 ./do.py --help

Управление сервисами

Основной запуск:

docker compose up --build

Основной запуск в фоне:

docker compose up -d --build

Остановить стек:

docker compose down

Остановить стек и удалить volumes текущего проекта:

docker compose down -v

Посмотреть логи:

docker compose logs -f

Посмотреть bootstrap отдельно:

docker compose logs bootstrap

Makefile

Makefile тоже переведен на docker-only режим. make init выполняет разовую подготовку через do.py, а make up уже запускает обычный docker compose up --build.

Основные команды:

make init
make up
make up-d
make prepare
make bootstrap
make down
make reset
make logs
make ps

Полезные команды для Django:

make migrate
make makemigrations
make createsuperuser
make shell
make check
make tailwind-build

Проверки:

make lint
make test

Django-команды внутри контейнера

Все management-команды теперь предполагаются внутри web контейнера.

Примеры:

docker compose exec web python manage.py createsuperuser
docker compose exec web python manage.py makemigrations
docker compose exec web python manage.py migrate
docker compose exec web python manage.py shell

Если стек еще не запущен, можно использовать one-off контейнер:

docker compose run --rm web python manage.py check

Что переименовывает шаблон

Скрипт scripts/rename_template.py обновляет:

• пакет проекта в src/workspace
• основной app в src/apps/core
• контейнерный manage.py в src/manage.py
• пути шаблонов app
• Python imports
• compose-related идентификаторы в конфигурации
• placeholder-строки в конфигурации и документации

Пример dry-run:

python3 ./scripts/rename_template.py --project-name PetTrace --app-name core --dry-run

Структура проекта

• src/workspace — пакет Django-проекта
• src/workspace/settings — настройки проекта
• src/apps/core — основной app-шаблон
• src/manage.py — основная точка запуска Django внутри контейнера
• templates — общие шаблоны
• assets — Tailwind source и собранный CSS
• scripts — служебные скрипты
• docker — docker runtime и конфиг nginx

Команда python manage.py startapp blog внутри контейнера теперь по умолчанию создает app в src/apps/blog, а не в корне проекта.

Типовые проблемы

Старый postgres volume после rename

Если проект уже переименован, а в Docker остался старый volume от предыдущего имени, do.py сам покажет только конфликтующие legacy-ресурсы и предложит удалить их по номерам.

Windows не дает удалить .git

Теперь это не останавливает setup. do.py попробует удалить .git с повторной попыткой и правами на запись. Если не получится, он просто выведет warning.

Порт 80 или 5555 уже занят

Измените NGINX_PORT или FLOWER_BIND в .env, затем перезапустите:

docker compose up --build