Nakarte GPX Bot

Telegram бот для скачивания GPX треков с nakarte.me. Бот принимает ссылки nakarte.me и возвращает пользователям GPX файлы с интеллектуальным кешированием для быстрых ответов.

Features

🚀 Fast Processing: Intelligent caching system (Redis or file-based)
🤖 Browser Automation: Uses Playwright for reliable GPX extraction
🐳 Docker Ready: Fully containerized with docker-compose
📝 Structured Logging: Comprehensive logging with request tracing
🔒 Secure: Runs as non-root user in Docker
🌐 Russian Interface: User-friendly messages in Russian
⚡ Async/Await: Built with modern async Python patterns

Architecture

project/
├── docker-compose.yml       # Docker orchestration
├── Dockerfile              # Multi-stage Docker build
├── requirements.txt        # Python dependencies
├── .env.example           # Environment variables template
├── test_nakarte.py        # Standalone testing script
├── README.md              # This file
├── TESTING.md             # Testing guide
├── NAKARTE_API.md         # Nakarte.me API documentation
├── src/
│   ├── __init__.py
│   ├── main.py            # Application entry point
│   ├── bot/
│   │   ├── __init__.py
│   │   └── handlers.py    # Telegram bot handlers
│   ├── services/
│   │   ├── __init__.py
│   │   ├── nakarte_service.py  # GPX extraction service
│   │   └── cache_service.py    # Caching abstraction
│   └── utils/
│       ├── __init__.py
│       └── logger.py      # Structured logging setup
└── cache/                 # Cache directory (created automatically)

Prerequisites

Docker and Docker Compose
Telegram Bot Token (get from @BotFather)

Quick Start

1. Clone the Repository

git clone <repository-url>
cd NakarteGPX

2. Configure Environment

Create a .env file from the example:

cp .env.example .env

Edit .env and set your bot token:

TELEGRAM_BOT_TOKEN=your_bot_token_here

3. Build and Run

# Build and start services
docker-compose up -d

# View logs
docker-compose logs -f bot

# Stop services
docker-compose down

Quick Test

Перед запуском бота можно протестировать извлечение GPX:

# Установите зависимости
pip install -r requirements.txt
playwright install chromium

# Запустите тест
python test_nakarte.py "https://nakarte.me/#m=15/41.69442/44.81043&l=O&nktl=YOUR_TRACK_ID"

# Или с видимым браузером (для отладки)
python test_nakarte.py "https://nakarte.me/#..." --no-headless

Скрипт покажет:

✅ Валидацию URL
📋 ID трека
📊 Размер и количество точек
💾 Сохранит GPX файл локально
📄 Покажет превью содержимого

Configuration

All configuration is done via environment variables in the .env file:

Required Variables

Variable	Description	Example
`TELEGRAM_BOT_TOKEN`	Your Telegram bot token	`123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11`

Optional Variables

Variable	Description	Default
`CACHE_TYPE`	Cache backend (`redis` or `file`)	`redis`
`CACHE_TTL`	Cache time-to-live in seconds	`86400` (24 hours)
`REDIS_HOST`	Redis hostname	`redis`
`REDIS_PORT`	Redis port	`6379`
`REDIS_DB`	Redis database number	`0`
`REDIS_PASSWORD`	Redis password (if required)	(empty)
`LOG_LEVEL`	Logging level	`INFO`
`BROWSER_HEADLESS`	Run browser in headless mode	`true`
`BROWSER_TIMEOUT`	Browser timeout in milliseconds	`30000`

Usage

Для пользователей

Начните чат с ботом в Telegram
Отправьте /start для приветствия
Скопируйте ссылку с nakarte.me (например, https://nakarte.me/#m=15/41.69442/44.81043&l=O&nktl=FqYcC2069tzeSG-foUKGsA)
Отправьте ссылку боту
Получите GPX файл

Команды бота

/start - Приветственное сообщение и инструкции
/help - Подробная справка

Как получить ссылку на трек

Откройте nakarte.me
Создайте или загрузите трек
Скопируйте URL из адресной строки браузера
Убедитесь, что URL содержит параметр nktl (идентификатор трека)

Development

Local Development Setup

Install Python 3.11+:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt

Install Playwright browsers:

playwright install chromium

Create .env file with your configuration
Run the bot:

python -m src.main

Running Tests

# Install dev dependencies
pip install pytest pytest-asyncio pytest-cov

# Run tests (when implemented)
pytest tests/

Implementation Details

Извлечение GPX из nakarte.me

Бот использует Playwright для автоматизации браузера и извлечения GPX данных:

Загрузка страницы: Открывает nakarte.me с URL трека
Ожидание инициализации: Ждет загрузки JavaScript приложения
Доступ к API: Получает доступ к window.app.trackManager
Извлечение данных: Получает координаты через getTrackPolylines()
Генерация GPX: Создает XML в формате GPX 1.1
Кеширование: Сохраняет результат для быстрого повторного доступа

Подробнее см. NAKARTE_API.md

Процесс обработки запроса

Пользователь → Telegram Bot Handler
                      ↓
              Проверка кеша
                   ↙    ↘
            Cache Hit   Cache Miss
                ↓           ↓
           Возврат    Playwright Browser
            файла          ↓
                    nakarte.me загрузка
                          ↓
                   Извлечение GPX
                          ↓
                   Сохранение в кеш
                          ↓
                    Возврат файла

Docker Details

Multi-Stage Build

The Dockerfile uses a multi-stage build to optimize image size:

Builder stage: Compiles Python dependencies
Runtime stage: Minimal runtime with only necessary components

Services

bot: Main application container
redis: Redis cache (optional, can use file cache instead)

Volumes

redis_data: Persistent Redis data
cache_data: File-based cache storage
./logs: Application logs (optional)

Resource Limits

Default limits (configurable in docker-compose.yml):

CPU: 2 cores max, 0.5 cores reserved
Memory: 2GB max, 512MB reserved

Monitoring

Health Checks

The bot includes health checks:

# Check bot container health
docker-compose ps

# View detailed health status
docker inspect nakarte-bot --format='{{.State.Health.Status}}'

Logs

View structured JSON logs:

# Follow all logs
docker-compose logs -f

# Follow bot logs only
docker-compose logs -f bot

# View last 100 lines
docker-compose logs --tail=100 bot

Log Fields

Each log entry includes:

timestamp: ISO 8601 timestamp
level: Log level (INFO, WARNING, ERROR)
event: Event type
user_id: Telegram user ID
request_id: Unique request identifier
Additional context-specific fields

Troubleshooting

Бот не запускается

Проверьте логи: docker-compose logs bot
Убедитесь, что токен бота правильный в .env
Проверьте, что Redis запущен: docker-compose ps redis

Не удается скачать GPX

Симптомы: Бот отвечает "Не удалось загрузить трек"

Решения:

Проверьте доступность nakarte.me в браузере
Убедитесь, что URL содержит параметр nktl
Увеличьте BROWSER_TIMEOUT в .env
Проверьте логи: docker-compose logs bot | grep error
Протестируйте локально: python test_nakarte.py "URL"

Типичные ошибки:

"No tracks found on the page" - трек не загрузился или удален
"Timeout waiting for condition" - слишком маленький timeout
"Could not find GPX data" - проблема с извлечением данных

Cache Issues

Redis connection failed:

# Check Redis status
docker-compose ps redis

# Restart Redis
docker-compose restart redis

Switch to file-based cache:

CACHE_TYPE=file

Memory Issues

If the bot runs out of memory:

Increase memory limits in docker-compose.yml
Reduce BROWSER_TIMEOUT
Monitor with: docker stats nakarte-bot

Production Deployment

Security Recommendations

Use secrets management: Don't commit .env to version control
Enable Redis password: Set REDIS_PASSWORD in production
Use reverse proxy: Put behind nginx for additional security
Regular updates: Keep dependencies updated
Monitor logs: Set up log aggregation (ELK, Loki, etc.)

Scaling

For high load:

Horizontal scaling: Run multiple bot instances
Redis cluster: Use Redis cluster for distributed caching
Load balancing: Use Telegram's webhook mode with load balancer

Backup

Backup important data:

# Backup Redis data
docker-compose exec redis redis-cli BGSAVE

# Backup file cache
tar -czf cache-backup.tar.gz cache/

Testing

Подробное руководство по тестированию см. в TESTING.md

Быстрый тест

# Тест извлечения GPX
python test_nakarte.py "https://nakarte.me/#m=15/41.69442/44.81043&l=O&nktl=ABC123"

# С видимым браузером (для отладки)
python test_nakarte.py "URL" --no-headless

Проверка логов

# Следить за логами в реальном времени
docker-compose logs -f bot

# Фильтр по событиям
docker-compose logs bot | grep "gpx_downloaded"
docker-compose logs bot | grep "error"

API Reference

NakarteService

from src.services.nakarte_service import NakarteService

service = NakarteService(headless=True, timeout=30000)

# Валидация URL
is_valid = service.validate_url(url)

# Извлечение ID трека
track_id = service.extract_track_id(url)

# Скачивание GPX
gpx_data = await service.download_gpx(url)

# Закрытие
await service.close()

CacheService

from src.services.cache_service import create_cache_service

cache = create_cache_service(cache_type='redis')

# Получение из кеша
data = await cache.get(key)

# Сохранение в кеш
await cache.set(key, value, ttl=86400)

# Проверка существования
exists = await cache.exists(key)

# Закрытие
await cache.close()

Documentation

README.md - Основная документация (этот файл)
TESTING.md - Руководство по тестированию
NAKARTE_API.md - Документация по API nakarte.me
.env.example - Пример конфигурации

Contributing

Форкните репозиторий
Создайте feature branch
Внесите изменения
Добавьте тесты (если применимо)
Создайте pull request

License

Проект предоставляется "как есть" для образовательных и личных целей.

Support

При возникновении проблем:

Проверьте раздел Troubleshooting
Изучите логи для деталей ошибок
Используйте test_nakarte.py для локального тестирования
Откройте issue на GitHub

Acknowledgments

nakarte.me - Отличный картографический сервис
aiogram - Современный фреймворк для Telegram ботов
Playwright - Надежная автоматизация браузера

Roadmap

Планируемые улучшения:

Поддержка множественных треков в одном URL
Экспорт в другие форматы (KML, GeoJSON)
Webhook режим для масштабирования
Веб-интерфейс для мониторинга
Автоматические тесты (pytest)
Метрики и мониторинг (Prometheus)

Примечание: Этот бот не связан с nakarte.me. Пожалуйста, соблюдайте их условия использования и используйте ответственно.

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
src		src
.env.example		.env.example
.gitattributes		.gitattributes
.gitignore		.gitignore
Dockerfile		Dockerfile
PROJECT_STRUCTURE.md		PROJECT_STRUCTURE.md
QUICKSTART.md		QUICKSTART.md
README.md		README.md
TESTING.md		TESTING.md
app.js		app.js
docker-compose.yml		docker-compose.yml
requirements.txt		requirements.txt
test_nakarte.py		test_nakarte.py

eXpressionist/NakarteGPX

Folders and files

Latest commit

History

Repository files navigation