A standalone web dashboard for monitoring domain renewals. This project extends the Domain Expiry API with a modern web interface featuring:
- 🎨 Light/Dark/System Themes - Automatic theme switching that follows your OS
- 📊 Color-Coded Status - Red (≤3 months), Yellow (3-6 months), Green (>6 months)
- ⏱️ Live Countdown - Shows time until next refresh
- 🔄 Auto-Refresh - Configurable interval (default 1 hour)
- 📱 Responsive Design - Works on desktop, tablet, and mobile
- 🌍 Locale-Aware Date Formatting - Auto-detects browser locale or choose from 5 manual formats
- ⚙️ Configurable Thresholds - Set your own Red/Yellow day values directly in the UI
- ⚡ Zero Dependencies - Pure HTML/CSS/JavaScript + nginx
- Docker & Docker Compose installed
- Available ports: 80 (web UI) and 8088 (API)
Step 1: Create a project directory
mkdir domain-expiry-web
cd domain-expiry-webStep 2: Download the required files
wget https://raw.githubusercontent.com/Hackpig1974/domain-expiry-web/main/compose.yml
wget https://raw.githubusercontent.com/Hackpig1974/domain-expiry-web/main/.env.example -O .envStep 3: Configure your domains
nano .envAdd your domains:
DOMAINS=example.com,mysite.com,portfolio.io
RDAP_BASE=https://rdap.org/domain
ALERT_DAYS=183
TZ=America/DenverStep 4: Start Services
docker compose up -dDocker will pull both images automatically on first run. No local web files needed.
Step 5: Access Web UI
Open your browser to:
- Local: http://localhost
- Remote: http://YOUR_SERVER_IP
Both containers are published to Docker Hub. Updates to the web UI and API are delivered via new image versions:
docker compose pull
docker compose up -dThat's it — no git, no local file management.
| Variable | Required | Default | Description |
|---|---|---|---|
DOMAINS |
✅ Yes | - | Comma-separated list of domains |
RDAP_BASE |
✅ Yes | - | RDAP server (use https://rdap.org/domain) |
ALERT_DAYS |
✅ Yes | - | Show alert when days ≤ this value |
REFRESH_MINUTES |
No | 360 | API cache duration (6 hours) |
TZ |
No | UTC | Timezone (e.g., America/Denver) |
WHOIS_FALLBACK_ENABLED |
No | false | Enable WHOIS fallback for .uk/.ca/.fr |
WHOISXML_API_KEY |
No | - | API key for ALL TLDs (500 free/month) |
Edit compose.yml to change ports:
ports:
- "8089:80" # Web UI on port 8089
- "8090:8000" # API on port 8090- Light Theme: Clean white/gray design
- Dark Theme: Blue-green slate accents
- System Theme: Follows OS preference automatically
- Persistent: Theme choice saved in browser
- 🔴 Red: ≤90 days remaining (3 months)
- 🟡 Yellow: 91-184 days (3-6 months)
- 🟢 Green: >184 days (over 6 months)
- ⚪ Gray: Status unknown
- ⚙️ Settings gear (top right) opens the settings panel with two sections:
- Date Format — Auto (Browser Locale) default, or choose from DD/MM/YYYY, DD-MM-YYYY, MM/DD/YYYY, MM-DD-YYYY, YYYY-MM-DD
- Status Thresholds — Set your own Red alert and Yellow warning day values. Defaults to 90 and 184 days if not customized
- Persistent: All settings saved in browser localStorage
Footer displays time until next auto-refresh: Next refresh: 59m 30s
Click "🔄 Refresh Now" to update immediately and reset countdown.
Check containers are running:
docker psShould see both domain-expiry and domain-expiry-webserver.
Check logs:
docker logs domain-expiry
docker logs domain-expiry-webserverAPI may not be able to fetch domain data. Options:
-
Enable WHOIS fallback (for .uk, .ca, .fr):
WHOIS_FALLBACK_ENABLED=true
-
Add WhoisXML API key (for ALL TLDs):
WHOISXML_API_KEY=your-key-here
Get free key: https://whoisxmlapi.com (500 requests/month)
Restart after config changes:
docker compose restartIf port 80 is occupied, edit compose.yml:
ports:
- "8089:80"Then access via: http://localhost:8089
┌─────────────────┐
│ Browser │
│ (port 80) │
└────────┬────────┘
│ HTTP
▼
┌─────────────────┐
│ domain-expiry │ Serves static HTML/CSS/JS
│ -webserver │ Proxies /api/* to backend
└────────┬────────┘
│ HTTP
▼
┌─────────────────┐
│ domain-expiry │ Domain expiry data
│ (API) │ RDAP/WHOIS queries
└─────────────────┘
Data Flow:
- Browser loads static files from the webserver container
- JavaScript fetches
/api/status(proxied to API container) - API queries RDAP/WHOIS for domain data
- JavaScript updates table with color-coded results
- Auto-refresh repeats every hour
- Keep refresh interval at 1+ hour (API caches for 6 hours)
- Monitor 10-20 domains max per instance
- Web UI adds minimal overhead (~15MB RAM)
- Don't expose to internet without authentication
- Run behind reverse proxy (nginx/Traefik) with auth
- No sensitive data stored (public WHOIS info only)
Use domain-expiry-web when:
- ✅ You want a standalone dashboard
- ✅ You don't use Homepage
- ✅ You want theme customization
- ✅ You prefer a dedicated interface
Use domain-expiry (original) when:
- ✅ You already use Homepage dashboard
- ✅ You want all services in one place
- ✅ You need Homepage's widget features
Both can run simultaneously on different ports.
Original domain-expiry (Homepage):
- Shows 🔴 red emoji when domain expires in ≤183 days (configurable via ALERT_DAYS)
- No visual indicator for domains with >183 days remaining
- Single threshold based on ALERT_DAYS setting
domain-expiry-web:
- Three-tier color system: Red (≤90d) / Yellow (91-184d) / Green (>184d)
- Visual status for ALL domains at a glance
- Independent thresholds (configurable via Settings panel in UI)
- Themed colors adapt to Light/Dark mode
Found a bug? Open an issue. Have a feature request or question? Start a Discussion. Want to contribute code? Submit a PR with improvements and share screenshots of your setup!
Want to modify the web UI or build your own image:
git clone https://github.com/Hackpig1974/domain-expiry-web.git
cd domain-expiry-webEdit files in webserver/, then build locally:
docker build -t domain-expiry-webserver:dev .- Domain Expiry API - The backend service
- Homepage - Alternative dashboard platform
- nginx - Web server powering the UI
GPL-3.0 License - see LICENSE file
Built on the Domain Expiry API by @Hackpig1974
Made with ❤️ for the homelab community