A production-ready Python network monitoring application with async ICMP ping, port scanning, Telegram bot, email alerts, web portal, REST API, and user management.
- Auto Ping — APScheduler pings all devices on a configurable interval (10s – 1h)
- Ping Center — Ping all, by device type, by location, or single device on demand
- Ping Logs — Full history with device name, IP, type, location, response time
- Alerts — Email & Telegram notifications when devices go down or recover
- Telegram Bot —
/pingall,/ping,/status,/devices,/scan, and more - Import / Export — CSV, XLSX, JSON, YAML device import and export
- User Management — Admin / Viewer roles, activate/deactivate, reset password
- Dark Mode — Persistent dark/light theme
- REST API — Full FastAPI with interactive docs at
/api/docs
cd C:\path\to\pyping
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
copy .env.example .envEdit .env with your settings (at minimum set SECRET_KEY), then:
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000Open: http://localhost:8000
Register the first account — it is automatically promoted to Admin.
cd /path/to/pyping
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env # edit as needed
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000cp .env.example .env # fill in your secrets
docker compose up --buildIf you registered before the auto-promote logic was in place, run once:
.venv\Scripts\python fix_admin.pyThis sets is_superuser = True for all admin-role accounts in the database.
| Variable | Default | Description |
|---|---|---|
DATABASE_URL |
sqlite+aiosqlite:///./pyping.db |
Database — use postgresql+asyncpg:// for production |
SECRET_KEY |
— | Required. JWT signing secret (min 32 chars) |
ACCESS_TOKEN_EXPIRE_MINUTES |
480 |
JWT token lifetime (8 hours) |
GOOGLE_CLIENT_ID |
— | Google OAuth2 client ID (optional) |
GOOGLE_CLIENT_SECRET |
— | Google OAuth2 client secret (optional) |
TELEGRAM_BOT_TOKEN |
— | Telegram bot token from @BotFather |
TELEGRAM_ALLOWED_USER_IDS |
— | Comma-separated Telegram user IDs allowed to use the bot. Leave empty to allow everyone. |
SMTP_HOST |
smtp.gmail.com |
SMTP server |
SMTP_PORT |
587 |
SMTP port |
SMTP_USER |
— | SMTP username |
SMTP_PASSWORD |
— | SMTP password |
SMTP_TLS |
true |
Use STARTTLS |
SMTP_FROM |
— | From address for alert emails |
APP_NAME |
PyPing |
Application display name |
APP_BASE_URL |
http://localhost:8000 |
Base URL (used in alert emails) |
LOG_LEVEL |
INFO |
Logging level |
-
Open Telegram → search @BotFather → send
/newbot -
Copy the token into
.env:TELEGRAM_BOT_TOKEN=7123456789:AAFxxxxxxxxxxxxxxxxx
-
Get your user ID — search @userinfobot on Telegram, send any message, it replies with your ID:
TELEGRAM_ALLOWED_USER_IDS=123456789
Multiple users:
TELEGRAM_ALLOWED_USER_IDS=123456789,987654321
Leave empty to allow anyone. -
Restart the server — you'll see
Telegram bot started.in the logs.
| Command | Description |
|---|---|
/pingall |
Ping ALL active devices and show full results |
/ping <ip_or_name> |
Ping a single device |
/status |
Network overview — online / offline counts |
/devices |
List all devices with status |
/devices online |
Only online devices |
/devices offline |
Only offline devices |
/scan <ip_or_name> [ports] |
Port scan a device |
/alerts |
Show active alert rules |
/mute <device> <minutes> |
Mute alerts for a device |
/pause |
Pause auto-ping scheduler |
/resume |
Resume auto-ping scheduler |
/help |
Show all commands |
- Go to console.cloud.google.com → APIs & Services → Credentials
- Create OAuth 2.0 Client ID (Web application)
- Add to Authorized redirect URIs:
http://localhost:8000/api/v1/auth/google/callback - Copy into
.env:GOOGLE_CLIENT_ID=your-client-id GOOGLE_CLIENT_SECRET=your-client-secret
Go to Import / Export page and upload a file. Supported formats: CSV, XLSX, JSON, YAML, DOCX
Example CSV:
name,ip,model,device_type,location,notes
Router-01,192.168.1.1,Cisco ISR,router,Server Room,Core router
Switch-01,192.168.1.2,HP ProCurve,switch,Floor 1,Access switch
Camera-01,192.168.2.10,,camera,Lobby,Front entrance
NAS-01,192.168.1.20,Synology DS920+,nas,Server Room,Tick Upsert to update existing devices by name/IP instead of skipping duplicates.
router switch access_point firewall load_balancer modem vpn_gateway wireless_controller
server web_server database_server mail_server dns_server file_server hypervisor
nas san
workstation laptop tablet phone voip_phone
printer scanner
camera nvr dvr
ups pdu
iot smart_tv raspberry_pi plc
pos other
| Role | Permissions |
|---|---|
| Admin | Full access — manage devices, users, settings, import/export |
| Viewer | Read-only — view devices, logs, dashboard |
- First registered user is automatically promoted to Admin
- Admins can change roles, reset passwords, activate/deactivate accounts
- Profile name and password editable from the sidebar (bottom-left avatar)
Base path: /api/v1/
GET /devices List devices (page, status, device_type, search)
POST /devices Create device [admin]
GET /devices/{id} Get device
PUT /devices/{id} Update device [admin]
DELETE /devices/{id} Delete device [admin]
POST /devices/{id}/ping Ping device now
POST /devices/ping-bulk Ping multiple devices by filter
GET /devices/locations List distinct locations
GET /logs Ping logs (page, device_id, status, search, date_from, date_to)
DELETE /logs/clear Delete logs (older_than_days, device_id) [admin]
GET /alerts List alert rules
POST /alerts Create alert rule [admin]
PUT /alerts/{id} Update alert rule [admin]
DELETE /alerts/{id} Delete alert rule [admin]
GET /settings List all settings
PUT /settings/{key} Update setting [admin]
POST /settings/test-smtp Test SMTP connection [admin]
POST /settings/test-telegram Test Telegram bot [admin]
POST /scheduler/pause Pause auto-ping [admin]
POST /scheduler/resume Resume auto-ping [admin]
POST /scheduler/trigger Run ping cycle now (force) [admin]
POST /import Upload import file [admin]
GET /export?format=csv|xlsx|json|yaml Download export
GET /dashboard/stats Summary stats + 24h ping history
GET /users-admin List all users [admin]
PUT /users-admin/{id}/role Change user role [admin]
PUT /users-admin/{id}/active Activate / deactivate user [admin]
PUT /users-admin/{id}/password Reset user password [admin]
DELETE /users-admin/{id} Delete user [admin]
Full interactive docs: http://localhost:8000/api/docs
# PostgreSQL
DATABASE_URL=postgresql+asyncpg://user:password@localhost/pyping
# Install asyncpg driver
pip install asyncpg
# Run with multiple workers
uvicorn app.main:app --host 0.0.0.0 --port 8000 --workers 4- Place behind nginx or Caddy with HTTPS
- Use systemd or supervisor to keep the process running
- For multi-worker deployments, APScheduler should only run in one worker — use an external lock or run the scheduler as a separate process
pyping/
├── app/
│ ├── auth/ # FastAPI-Users auth, JWT, Google SSO, dependencies
│ ├── models/ # SQLAlchemy models (Device, PingLog, User, Setting)
│ ├── routers/ # API endpoints (devices, logs, alerts, settings, users…)
│ ├── schemas/ # Pydantic schemas
│ ├── services/ # Ping engine, alert service, import/export
│ ├── scheduler/ # APScheduler tasks
│ ├── telegram/ # Telegram bot handlers
│ ├── templates/ # Jinja2 HTML templates (Tailwind + Alpine.js)
│ ├── config.py # Settings from .env
│ ├── database.py # Async SQLAlchemy engine
│ └── main.py # FastAPI app, lifespan, routes
├── fix_admin.py # One-time script to fix admin permissions in DB
├── requirements.txt
├── .env.example
├── docker-compose.yml
└── README.md
MIT