https://github.com/elisey/ipbot
https://github.com/elisey/ipbot
bot docker ip networking python telegram-bot
Last synced: 5 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/elisey/ipbot
- Owner: elisey
- License: mit
- Created: 2025-10-28T19:29:12.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2026-01-23T01:41:09.000Z (6 months ago)
- Last Synced: 2026-01-23T18:48:56.889Z (6 months ago)
- Topics: bot, docker, ip, networking, python, telegram-bot
- Language: Python
- Homepage:
- Size: 1.41 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# IP Bot
[](https://github.com/elisey/ipbot/actions/workflows/ci-docker-publish.yml)
A simple async Telegram bot that responds to the `/ip` command with the public IP address of the server where the bot is running.
The bot fetches the address using multiple external IP detection services in parallel for reliability, works behind NAT, and restricts access to a single authorized Telegram user defined in the configuration file.
## Features
- Async Telegram bot using python-telegram-bot
- **Resilient parallel fetching** from multiple IP providers (ipify.org, ident.me, ifconfig.me, ipinfo.io)
- **Consensus-based validation** - shows IP only when all providers agree
- **Detailed status view** - shows each provider's result with color-coded indicators
- Authorization based on Telegram user ID
- Dockerized deployment
- Configuration via environment variables
## Quick Start
### 1. Get Your Telegram Credentials
#### Create a Telegram Bot
1. Open Telegram and search for [@BotFather](https://t.me/BotFather)
2. Send `/newbot` command
3. Follow the prompts to choose a name and username for your bot
4. BotFather will give you a token like: `123456789:ABCdefGHIjklMNOpqrsTUVwxyz`
5. Save this token - you'll need it for configuration
#### Get Your Telegram User ID
1. Open Telegram and search for [@userinfobot](https://t.me/userinfobot)
2. Send `/start` command
3. The bot will reply with your user ID (a number like `123456789`)
4. Save this ID - only this user will be able to use your IP bot
### 2. Run the Bot with Docker
#### Option 1: Use Pre-built Image from GitHub Container Registry
Pull the latest image:
```bash
# Pull the image
docker pull ghcr.io/elisey/ipbot:latest
```
Create a `.env` file with your credentials:
```bash
TELEGRAM_TOKEN=your_bot_token_here
TELEGRAM_OWNER_ID=123456789
```
Create a `docker-compose.yml` file:
```yaml
services:
ip-bot:
image: ghcr.io/elisey/ipbot:latest
container_name: ipbot
env_file:
- .env
restart: always
```
Start the bot:
```bash
# Start the bot
docker compose up -d
# View logs
docker compose logs -f
# Stop the bot
docker compose down
```
#### Option 2: Build Locally
Clone the repository:
```bash
git clone https://github.com/elisey/ipbot.git
cd ipbot
```
Create a `.env` file:
```bash
cp .env.example .env
# Edit .env and add your TELEGRAM_TOKEN and TELEGRAM_OWNER_ID
```
Run with docker-compose:
```bash
docker compose up -d
```
### 3. Test the Bot
Open Telegram and send `/ip` to your bot. It should respond with your public IP address.
## Configuration
The bot is configured via environment variables in the `.env` file:
- `TELEGRAM_TOKEN` (required): Your bot token from @BotFather
- `TELEGRAM_OWNER_ID` (required): Your Telegram user ID - only this user can use the bot
- `FETCHER_STRATEGY_ORDER` (optional): IP fetchers to use, default: `all`
### Available IP Fetchers
The bot supports multiple IP detection providers:
- `ipify` - ipify.org JSON API
- `identme` - ident.me plain text API
- `ifconfig` - ifconfig.me plain text API
- `ipinfo` - ipinfo.io plain text API
- `custom` - custom plain text API
**Example configurations:**
```bash
# Use all fetchers (default - most reliable)
FETCHER_STRATEGY_ORDER=all
# Use specific fetchers only
FETCHER_STRATEGY_ORDER=ipify,identme,ifconfig
# Use only two fetchers
FETCHER_STRATEGY_ORDER=ipify,identme
# Use single fetcher (less reliable)
FETCHER_STRATEGY_ORDER=ipify
```
**The `all` keyword:** When you set `FETCHER_STRATEGY_ORDER=all`, the bot automatically uses all available IP providers. This is the recommended configuration as it provides maximum reliability. If you add new custom fetchers to your deployment, they will automatically be included when using `all`.
### How the Bot Works
The bot fetches your IP from **all configured providers in parallel**:
1. **All providers agree** → Shows your IP with green checkmarks ✅
2. **Some providers fail** → Shows IP if remaining providers agree, marks failures with ❌
3. **Providers return different IPs** → Shows "unknown" and displays all results with ⚠️
## Troubleshooting
### Bot doesn't respond to commands
**Check your user ID:**
- Verify `TELEGRAM_OWNER_ID` in `.env` matches your actual Telegram user ID
- Get your ID from [@userinfobot](https://t.me/userinfobot) to confirm
**Check bot token:**
- Verify `TELEGRAM_TOKEN` is correct (no extra spaces)
- Test the token by visiting: `https://api.telegram.org/bot/getMe`
### "Unauthorized" message
Your Telegram user ID doesn't match `TELEGRAM_OWNER_ID` in the configuration. Only the specified owner can use the bot.
### Check logs
```bash
# View bot logs
docker compose logs -f ip-bot
# View last 100 lines
docker compose logs --tail 100 ip-bot
```
## Documentation
- **[Contributing Guide](doc/CONTRIBUTION.md)** - Development setup, testing, and architecture
- **[Deployment Guide](doc/DEPLOYMENT.md)** - Production deployment with Docker and systemd
## License
MIT