Skip to content

README.md

Latest commit

 

History

History
176 lines (134 loc) · 3.96 KB

README.md

File metadata and controls

176 lines (134 loc) · 3.96 KB
Raw

IP Address Monitor with Telegram Notifications

A Python application that monitors your public IP address and sends Telegram notifications when it changes. Checks every minute and runs in a Docker container.

Features

  • 🔄 Monitors public IP address every 5 minutes
  • 📢 Sends Telegram notifications when IP changes
  • 🐳 Docker and Docker Compose support
  • 🐍 Python virtual environment for local testing
  • 🔒 Runs as non-root user in Docker
  • 📝 Detailed logging

Prerequisites

  • Python 3.11 or higher (for local development)
  • Docker and Docker Compose (for containerized deployment)
  • A Telegram account and bot token

Telegram Setup

1. Create a Telegram Bot

  1. Open Telegram and search for @BotFather
  2. Start a chat and send /newbot
  3. Follow the prompts to choose a name and username for your bot
  4. Copy the bot token (format: 123456789:ABCdefGHIjklMNOpqrsTUVwxyz)

2. Get Your Chat ID

Option A - Using @userinfobot:

  1. Search for @userinfobot on Telegram
  2. Start a chat and send any message
  3. It will reply with your user ID (this is your chat ID)

Option B - Using @RawDataBot:

  1. Search for @RawDataBot on Telegram
  2. Start a chat and send any message
  3. Look for "id": in the response (this is your chat ID)

Option C - Manual method:

  1. Send a message to your bot
  2. Visit: https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates
  3. Look for "chat":{"id": in the JSON response

Local Development Setup

1. Clone the repository

git clone <your-repo-url>
cd atlanteren_ip_inform_telegram

2. Set up Python virtual environment

chmod +x setup_venv.sh
./setup_venv.sh

Or manually:

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

3. Configure environment variables

cp .env.example .env

Edit .env and add your Telegram credentials:

TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrsTUVwxyz
TELEGRAM_CHAT_ID=123456789
TELEGRAM_HOST_NAME=MyServer

4. Run locally

source venv/bin/activate
python main.py

Press Ctrl+C to stop.

Docker Deployment

Using Docker Compose (Recommended)

  1. Configure environment variables:
cp .env.example .env
# Edit .env with your Telegram credentials
  1. Build and run:
docker-compose up -d
  1. View logs:
docker-compose logs -f
  1. Stop the service:
docker-compose down

Using Docker directly

  1. Build the image:
docker build -t ip-monitor .
  1. Run the container:
docker run -d \
  --name ip-monitor \
  --restart unless-stopped \
  -e TELEGRAM_BOT_TOKEN=your-bot-token-here \
  -e TELEGRAM_CHAT_ID=your-chat-id-here \
  -e TELEGRAM_HOST_NAME=MyServer \
  ip-monitor
  1. View logs:
docker logs -f ip-monitor
  1. Stop the container:
docker stop ip-monitor
docker rm ip-monitor

Configuration

Environment variables:

  • TELEGRAM_BOT_TOKEN (required): Your Telegram bot token from @BotFather
  • TELEGRAM_CHAT_ID (required): Your Telegram chat ID
  • TELEGRAM_HOST_NAME (optional): A friendly name to identify this device/server (default: "Not Specified")

How It Works

  1. The application fetches your public IP from https://ifconfig.me/ip
  2. On first run, it sends a Telegram message with your current IP
  3. Every 60 seconds, it checks if the IP has changed
  4. If changed, it sends a Telegram notification with old and new IP addresses
  5. All events are logged to stdout

Troubleshooting

Telegram authentication errors

  • Verify your TELEGRAM_BOT_TOKEN is correct
  • Ensure your TELEGRAM_CHAT_ID is correct (it should be a number)
  • Make sure you've started a chat with your bot first

IP fetch errors

  • Check internet connectivity
  • Verify https://ifconfig.me is accessible
  • Check firewall rules

Docker issues

  • Ensure Docker daemon is running
  • Check logs: docker-compose logs or docker logs ip-monitor
  • Verify .env file exists and has correct values

License

See LICENSE file for details.