apcupsd Uptime Kuma Bridge

A lightweight Docker container that bridges apcupsd UPS monitoring with Uptime Kuma notifications and provides HTTP API endpoints for UPS status monitoring.

Features

• Real-time UPS monitoring: Connects to remote apcupsd daemon via NIS protocol
• Event-driven notifications: Alerts on power loss, battery low, high load, etc.
• HTTP API endpoints: REST API for UPS status monitoring and health checks
• Multiple operation modes: Uptime Kuma notifications, HTTP-only, or combined mode
• Smart thresholds: Automatically detects apcupsd configuration for battery and time limits
• Comprehensive monitoring: Tracks 30+ UPS metrics including battery charge, load percentage, and time remaining
• Docker deployment: Easy deployment as a containerized service
• Robust error handling: Graceful handling of network issues and UPS disconnections

Quick Start

Using Docker Compose (Recommended)

1. Download the compose file:

   curl -O https://raw.githubusercontent.com/hedger/apcupsd-uptime-kuma-bridge/main/docker-compose.yml
   curl -O https://raw.githubusercontent.com/hedger/apcupsd-uptime-kuma-bridge/main/.env.example

2. Configure environment:

   cp .env.example .env
   # Edit .env with your settings

3. Deploy:

   docker compose up -d

Using Docker CLI

docker run -d \
  --name apcupsd-uptime-kuma-bridge \
  --restart unless-stopped \
  -p 8080:8080 \
  -e APCUPSD_HOST=192.168.1.100 \
  -e UPTIME_KUMA_PUSH_URL="https://your-kuma.domain.com/api/push/XXXXXXXX" \
  ghcr.io/hedger/apcupsd-uptime-kuma-bridge:latest

Configuration

Environment Variables

Variable	Default	Description
APCUPSD_HOST	192.168.1.100	IP address of apcupsd server
APCUPSD_PORT	3551	Port of apcupsd daemon
UPTIME_KUMA_PUSH_URL	optional	Uptime Kuma push notification URL
HTTP_ENABLED	true	Enable HTTP API server
HTTP_PORT	8080	Port for HTTP API endpoints
HEARTBEAT_INTERVAL	60	Heartbeat interval in seconds
POLL_INTERVAL	10	UPS status polling interval in seconds
TZ	UTC	Timezone for logging

🔧 Operational Modes: You can run the monitor in three modes:

• Uptime Kuma + HTTP (default): Both push notifications and HTTP API endpoints
• Uptime Kuma only: Set HTTP_ENABLED=false to disable HTTP API
• HTTP only: Leave UPTIME_KUMA_PUSH_URL empty to run without push notifications

💡 Pro Tip: All status messages are now fully customizable! See CONFIG.md for complete documentation of message customization options including emoji support and multilingual messages.

Getting Uptime Kuma Push URL

1. Open your Uptime Kuma dashboard
2. Go to Settings > Monitors
3. Click Add New Monitor
4. Select Push as monitor type
5. Copy the generated push URL from the setup instructions

Monitored Events

The monitor will send notifications for:

Power Events

• UPS switches to battery power
• Power is restored
• UPS is shutting down

Battery Events

Load Events

• UPS load exceeds 90%

System Events

• Monitor startup/shutdown
• Connection failures to apcupsd

HTTP API

The service provides REST API endpoints for external monitoring:

Endpoints

• GET /health - Health check (returns simple health status)
• GET /status - Full UPS status (returns all apcupsd data)

Examples

# Check service health
curl http://localhost:8080/health

# Get full UPS status
curl http://localhost:8080/status

Development

Building Locally

# Build and run with Docker Compose
docker compose up --build

# Run in background
docker compose up --build -d

# View logs
docker compose logs -f

Testing

# Test connection to apcupsd
python3 test_apcupsd.py

# Test full monitoring
python3 test_monitor.py

Health Checks

The container includes health checks that verify connection to apcupsd daemon.

Check health status:

docker compose ps
# or
docker inspect apcupsd-uptime-kuma-bridge --format='{{.State.Health.Status}}'

Troubleshooting

Cannot connect to apcupsd

1. Verify APCUPSD_HOST and APCUPSD_PORT settings
2. Ensure apcupsd is configured to accept network connections:

   # In apcupsd.conf
   NETSERVER on
   NISIP 0.0.0.0
   NISPORT 3551

3. Check firewall rules on apcupsd server
4. Test connection manually:

   telnet your-apcupsd-host 3551

Notifications not reaching Uptime Kuma

1. Verify UPTIME_KUMA_PUSH_URL is correct (if using Uptime Kuma mode)
2. Test the URL manually:

   curl "YOUR_PUSH_URL&status=up&msg=test"

3. Check Uptime Kuma logs for errors

High CPU usage

1. Increase POLL_INTERVAL to reduce polling frequency
2. Increase HEARTBEAT_INTERVAL to reduce notification frequency

Container Images

Pre-built multi-architecture Docker images are available:

• GitHub Container Registry: ghcr.io/hedger/apcupsd-uptime-kuma-bridge:latest
• Architectures: linux/amd64, linux/arm64
• Tags: latest, main, version tags (e.g., v1.0.0)

Security

• Container runs as non-root user
• Minimal attack surface with distroless-style base image
• No sensitive data stored in container
• Network access limited to apcupsd and Uptime Kuma

Integration Examples

Home Assistant

Use with Home Assistant via Uptime Kuma integration:

# configuration.yaml
binary_sensor:
  - platform: uptime_kuma
    url: "https://your-kuma.domain.com"
    api_key: "your-api-key"

Prometheus/Grafana

Extend the script to expose metrics for Prometheus:

# Add to upsmon.py
from prometheus_client import start_http_server, Gauge

battery_charge = Gauge('ups_battery_charge_percent', 'UPS battery charge percentage')
load_percent = Gauge('ups_load_percent', 'UPS load percentage')

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Related Projects

• apcupsd - APC UPS daemon
• Uptime Kuma - Self-hosted monitoring tool
• aiohttp - Async HTTP client/server