Pet Alert - веб-приложение для поиска пропавших животных

Описание проекта

Проект создан с целью помощи людям в нахождении потерянных питомцев. Хозяин потерянной зверюшки может создать объявление на сайте, предоставив всю необходимую информацию о случившейся ситуации. Человек, который нашел на улице чужого питомца, может также сообщить об этом.

Преимущества проекта

• Удобство: пользователю достаточно заполнить простую форму на сайте, чтобы сообщить о найденной или потерянной зверюшке.
• Функциональность: благодаря интеграции в проект Яндекс карт, пользователь может выбрать место, где был найден или потерян питомец.
• Простота: пользователю не нужно заранее регистрироваться на сайте, он будет зарегистрирован в момент создания своего первого объявления.
• Возможности для коммуникации: в проекте создана система диалогов, которая позволяет пользователям переписываться в рамках объявлений.
• Приватность: пользователи могут настраивать видимость своих контактных данных (email, мобильный телефон), если они не хотят делиться телефоном или почтой - то останется возможность коммуникации прямо на сайте, через диалоги.

Используемый стек

Системные требования

Версии инструментов указаны те, с которыми велась разработка проекта. На более ранних версиях проект не тестировался, поэтому его работоспособность не может быть гарантирована при использовании таких версий.

• Python 3.13+;
• Docker (20.10+) c docker compose;
• uv (0.6.8+).

Архитектура проекта

Директория	Описание
infra	Docker-compose файл, конфиги Nginx, entrypoints
.github/workflows	CI/CD скрипты github actions
config/	env файлы с настройками приложения
server/	Django проект
server/settings/	Настройки приложения разбитые по отдельным конфигам
server/apps/	Каталог с приложениями
server/static/	Каталог со статикой нужной для работы front части
server/templates/	Каталог с HTML шаблонами для front части приложения
docker-compose.yml	Docker compose файл для локальной разработки проекта
.pre-commit-config.yaml	Конфиг с настройками git pre-commit, используемый для локальной разработки

Функциональные цели

Нажмите, чтобы развернуть

• MVP проекта
• Возможность создавать объявления
• Просмотр объявлений списком и по карте
• Фильтрация объявлений по видам питомцев
• Система регистрации с подтверждением через почту
• Система скрытой регистрации при создании объявления для гостя
• Смена пароля, сброс пароля, авторизация, выход с аккаунта
• Система управления своими объявлениями для пользователя
• Настройка Docker, Docker-compose
• Настройка CI/CD через github actions
• Интеграция Yandex карт
• Интегрировать на сайт ReCaptcha
• Настройки пользователя через профиль (имя, приватность)
• Система диалогов
• Оптимизация проекта
  • Оптимизация SQL-запросов
  • Индексы БД
  • Оптимизация Nginx
  • Внедрить Celery с Redis
  • Отправка почтовых писем в фоне
  • Оптимизация PostgreSQL
  • Оптимизация взаимодействия с Yandex картами
  • Внедрение кэширования, Redis
• Внедрение Poetry
• Замена Poetry на UV
• Внедрение различных средств форматирования
  • Ruff
  • Pre-commit
• Система оповещения администраторов о новом объявлении через телеграм
• Скачивание объявления для распечатывания с QR-кодом
• API со всем функционалом из обычного сайта
  • Создание объявлений
  • Открытие/закрытие объявлений
• 100% покрытие тестами
  • Приложение с шаблонами
  • API

Установка и эксплуатация

Локальная установка, запуск, тестирование

Установка проекта локально

Для установки и запуска проекта локально необходим установленный docker с docker compose (для работы сервисов Redis, Celery, базы данных PostgreSQL, локального почтового SMTP-сервера), а также пакетный менеджер uv (для установки зависимостей приложения).

1. Клонируем репозиторий с проектом и переходим в его директорию:

git clone https://github.com/melax08/pet_alert.git && cd pet_alert

2. Устанавливаем зависимости:

uv sync

3. Копируем файл .env.example с новыми названием .env и заполняем его необходимыми данными:

cp config/.env.example config/.env && nano config/.env

4. Запускаем docker compose для создания и запуска необходимых микросервисов:

docker compose up -d

5. Применяем миграции:

uv run python3 manage.py migrate

Опционально. Создаем суперпользователя:

uv run python3 manage.py createsuperuser

Запуск проекта локально

Запускаем проект:

uv run python3 manage.py runserver

Локальный проект будет запущен и доступен по http://127.0.0.1:8000

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

Чтобы запустить unittest тестирование работы функционала Django-приложений, выполним команду:

uv run python3 manage.py test -v 2

Установка и запуск в production окружении

Для автоматической установки проекта в контейнерах, на вашем сервере или локальном компьютере должны быть установлен Docker и Docker Compose.

Установка проекта через Docker подразумевает под собой разворачивание полноценного проекта на боевой сервер, с существующим у сайта доменом и выпуском для него SSL-сертификата.

Перед началом установки, подготовьте сервер:

1. Установите на него Docker и Docker Compose по инструкции.
2. Подготовьте домен, направьте его на ваш сервер.

Когда предварительные меры будут приняты, можно будет приступить к установке проекта на сервер.

Предварительная настройка

1. Клонируем репозиторий с проектом и переходим в его директорию:

git clone https://github.com/melax08/pet_alert.git && cd pet_alert

2. Копируем файл .env.example с новыми названием .env и заполняем его необходимыми данными:

cp config/.env.example config/.env && nano config/.env

3. Переходим в каталог с инфраструктурой.

cd infra

Первая установка через Docker

При первом запуске проекта используем шаблон для Nginx без ssl секции (так как SSL-сертификат еще не выпущен и с полноценным конфигом Nginx не запустится).

Для этого используем команду:

docker compose --env-file first_run.env --env-file ../.env -f docker-compose-prod.yml up -d

Как только проект будет запущен и SSL-сертификат будет выпущен с помощью certbot, выключаем контейнер nginx:

docker compose stop
docker compose rm -sf nginx

И запускаем его повторно, выполняя пересборку контейнера:

docker compose --env-file ../.env -f docker-compose-prod.yml up -d --build nginx

Nginx будет запущен заново, но уже с нормальным конфигом Nginx, включающим в себя ssl секцию и использующим SSL-сертификат, выпущенный ранее.

Настройка CRON-задания на перевыпуск SSL-сертификата

❗️ Данная инструкция подходит только для unix-подобных операционных систем.

Certbot выпускает Let's encrypt SSL сертификаты, которые действуют 3 месяца. Каждые 3 месяца их необходимо перевыпускать.

Для этого, добавим на хост-машине (сервере, где вы разворачиваете проект) CRON-задание на автоматический перевыпуск SSL-сертификата:

crontab -e

Вставим в конец открывшегося редактора:

5 1 1 * *  docker compose --env-file /home/petalert/pet_alert/.env --file /home/petalert/pet_alert/infra/docker-compose-prod.yml up certbot && docker compose --file /home/petalert/pet_alert/infra/docker-compose-prod.yml exec nginx nginx -s reload

Вместо /home/petalert нужно в трех местах указать путь до каталога, где хранится клонированный проект.

Данная задача будет выполняться каждое первое число месяца в 1:05 и перевыпускать SSL-сертификат для сайта.

Создание суперпользователя

Если вы хотите создать суперпользователя Django в запущенном проекте, используйте команду:

docker compose exec web python manage.py createsuperuser

Команду необходимо использовать в каталоге infra.

Для разработчиков

Перед началом разработки и созданием новых коммитов, необходимо применить git-hooks, выполнив команду:

pre-commit install

Теперь, когда вы будете создавать новые коммиты, следующие хуки будут применяться автоматически:

• Ruff linter;
• Ruff formatter;
• Django unit tests;
• check-yaml, end-of-file-fixer, trailing-whitespace.

Настройка pre-commit хуков происходит в файле: .pre-commit-config.yaml