🚀 Aternos Watcher

A strictly typed Python 3.13 monitor for Aternos Minecraft servers. It intelligently filters out "Ghost Proxies" (Aternos servers that appear online but are actually in a standby/offline state).

✨ Features

• Ghost Proxy Filtering: Detects the difference between a truly online server and the Aternos "Offline" or "Preparing" MOTD.
• Discord Notifications: Standardized embeds for state changes (Online/Offline) with full customization.
• ANSI MOTD Support: Automatically converts Minecraft formatting codes (§) to ANSI for colorful MOTD display in Discord.
• Debounce Logic: Prevents notification spam during server startup flickers.
• Strictly Typed: Built with Python 3.13 type hints for reliability.

🛠️ Installation & Setup

Prerequisites

• uv (Recommended) or Python 3.13+

Configuration

Create a .env file or set the following environment variables:

⚙️ Core Configuration

Variable	Description	Default
ATERNOS_WATCHER_HOST	Your Aternos server address	localhost
ATERNOS_WATCHER_PORT	Server port	25565
ATERNOS_WATCHER_UPDATE_TIME	Polling interval in seconds	30
ATERNOS_WATCHER_VERBOSE	Enable debug logging	false
ATERNOS_WATCHER_WEBHOOK_URL	Discord Webhook URL	Required

🎨 Embed Customization

Variable	Description	Default
ATERNOS_WATCHER_OFFLINE_COLOR	Hex color when server is offline	ff4040
ATERNOS_WATCHER_OFFLINE_TITLE	Title when server is offline	🔴 Server OFFLINE
ATERNOS_WATCHER_ONLINE_COLOR	Hex color when server is online	30c030
ATERNOS_WATCHER_ONLINE_TITLE	Title when server is online	🟢 Server ONLINE!
ATERNOS_WATCHER_STOPPING_COLOR	Hex color when server is stopping	ff8c00
ATERNOS_WATCHER_STOPPING_TITLE	Title when server is stopping	🛑 Server STOPPING...
ATERNOS_WATCHER_WAITING_COLOR	Hex color when server is waiting	ffff00
ATERNOS_WATCHER_WAITING_MESSAGE	Message shown during WAITING state	Please connect in less than 7 minutes to make it stay open!
ATERNOS_WATCHER_WAITING_TITLE	Title when server is waiting for connection	⏳ Server WAITING...

📝 Embed Metadata

Variable	Description	Default
ATERNOS_WATCHER_AUTHOR_ICON	Author icon URL	None
ATERNOS_WATCHER_AUTHOR_NAME	Author name in the embed	None
ATERNOS_WATCHER_AUTHOR_URL	Author link URL	None
ATERNOS_WATCHER_FOOTER_ICON	Footer icon URL	None
ATERNOS_WATCHER_FOOTER_TEXT	Footer text in the embed	Aternos Watcher
ATERNOS_WATCHER_MENTION	Content to ping (e.g. @everyone)	None
ATERNOS_WATCHER_THUMBNAIL_URL	Thumbnail image URL	None

🔍 Display Options

Variable	Description	Default
ATERNOS_WATCHER_SHOW_MOTD	Show MOTD in embed	true
ATERNOS_WATCHER_SHOW_PLAYERS	Show player count in embed	true

🚀 Running Locally

# Install dependencies and run
uv run main.py

🐳 Docker Deployment

Docker Compose (Recommended)

Create a docker-compose.yml file:

services:
  watcher:
    image: ghcr.io/astral-sh/uv:python3.13-bookworm-slim
    container_name: aternos-watcher
    restart: unless-stopped
    volumes:
      - .:/app
    working_dir: /app
    environment:
      - ATERNOS_WATCHER_HOST=your-server.aternos.me
      - ATERNOS_WATCHER_WEBHOOK_URL=https://discord.com/api/webhooks/...
    command: uv run main.py

Run with:

docker compose up -d

☁️ Dokploy Deployment

If you are using Dokploy, use the following configuration:

1. Build Type: Nixpacks
2. Environment Variables: Set the variables listed in the Configuration section.
3. Start Command: uv run main.py