Merge pull request #89 from wickedyoda/macos-update

Macos update
This commit is contained in:
WickedYoda authored and GitHub committed 2026-08-05 13:20:24 -05:00
commit 1e25e36ce6
195 files changed
+152301

No files matched your search

+94
View File
@@ -0,0 +1,94 @@
# Uptime Updates Bot
This directory contains a bot that keeps Uptime Kuma Docker monitor container IDs in sync when containers are recreated.
## Files
- `config.yml` - Uptime Kuma URL, API key, and bot behavior settings.
- `container-monitor-map.yaml` - Docker host/container to Uptime monitor ID mappings.
- `uptime-bot.py` - Continuous sync bot runner.
- `setup-update_uptime-bot.sh` - Installer/updater for Linux systemd.
- `requirements.txt` - Python dependencies used by the bot virtualenv.
## Requirements
- Linux host with systemd
- Root or sudo access
- Docker remote API reachable for each mapped host (`host_api`)
## Configure
1. Edit `config.yml`:
- Set `uptime_kuma.url`
- Set `uptime_kuma.api_key`
- Optional: adjust `bot.poll_interval_seconds`
2. Edit `container-monitor-map.yaml`:
- Add one mapping per container
- Set `host_api`, `container_name`, and `uptime_monitor_id`
## Install And Start Service
Run from this directory:
```bash
sudo bash setup-update_uptime-bot.sh
```
What this does:
- Installs/updates files under `/opt/uptime-updates`
- Ensures compatible Python is available (for `uptime-bot.py`)
- Creates virtualenv and installs dependencies from `requirements.txt`
- Writes/updates systemd service
- Enables service on boot and restarts it
## Update After Changes
After editing files in this directory, re-run:
```bash
sudo bash setup-update_uptime-bot.sh
```
The installer is idempotent and acts as both installer and updater.
By default on update:
- Existing live `/opt/uptime-updates/config.yml` is preserved
- Existing live `/opt/uptime-updates/container-monitor-map.yaml` is preserved
Use overwrite flags only when you want to replace live files from repo copies.
## Common Commands
```bash
systemctl status uptime-updates-bot.service
journalctl -u uptime-updates-bot.service -f
systemctl restart uptime-updates-bot.service
systemctl stop uptime-updates-bot.service
systemctl disable uptime-updates-bot.service
```
## Installer Options
```bash
sudo bash setup-update_uptime-bot.sh --help
```
Useful options:
- `--install-dir PATH`
- `--service-name NAME`
- `--user USER`
- `--group GROUP`
- `--no-enable`
- `--no-start`
- `--min-python-version 3.9`
- `--overwrite-config`
- `--overwrite-map`
- `--overwrite-all`
- `--dry-run`
## Notes
- If using Docker TCP API (`tcp://host:2375`), secure network access appropriately.
- `expected_uptime_type: docker` in mapping items helps prevent accidental updates to non-docker monitors.
- The bot reloads `config.yml` and `container-monitor-map.yaml` each cycle, so most config changes do not require service restart.
+9
View File
@@ -0,0 +1,9 @@
uptime_kuma:
url: "http://127.0.0.1:3001"
api_key: "PUT_YOUR_API_KEY_HERE"
# Optional bot behavior settings
bot:
dry_run: false
request_timeout_seconds: 10
poll_interval_seconds: 60
+43
View File
@@ -0,0 +1,43 @@
# Container to Uptime Kuma monitor mapping
#
# Fill in one item per container you want tracked.
# The bot can read this file to know:
# 1) which Docker host to query
# 2) which container on that host to watch
# 3) which Uptime Kuma monitor to update when container ID changes
#
# Notes:
# - uptime_monitor_id is the numeric ID in Uptime Kuma.
# You can get it from the monitor URL, e.g. /dashboard/42 -> 42
# - host_api should be the Docker API endpoint for that host.
# Example: tcp://10.0.84.21:2375
# - container_name should match docker container name used by that host.
#
# Optional fields:
# - enabled: true/false (default true)
# - expected_uptime_type: set to "docker" to protect against wrong monitor type updates
mappings:
- name: "media-server jellyfin"
enabled: true
host_label: "media-server"
host_api: "tcp://10.0.84.21:2375"
container_name: "jellyfin"
uptime_monitor_id: 21
expected_uptime_type: "docker"
- name: "nas immich"
enabled: true
host_label: "nas"
host_api: "tcp://10.0.84.22:2375"
container_name: "immich-server"
uptime_monitor_id: 34
expected_uptime_type: "docker"
- name: "lab pihole"
enabled: false
host_label: "lab"
host_api: "tcp://10.0.84.30:2375"
container_name: "pihole"
uptime_monitor_id: 56
expected_uptime_type: "docker"
@@ -0,0 +1,52 @@
#!/usr/bin/env bash
set -euo pipefail
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
OUT_DIR="${SCRIPT_DIR}/watchtower-export"
BUNDLE_NAME="uptime-watchtower-bundle-$(date +%Y%m%d-%H%M%S).tar.gz"
mkdir -p "${OUT_DIR}"
cp -f "${SCRIPT_DIR}/uptime-bot.py" "${OUT_DIR}/uptime-bot.py"
cp -f "${SCRIPT_DIR}/requirements.txt" "${OUT_DIR}/requirements.txt"
cp -f "${SCRIPT_DIR}/config.yml" "${OUT_DIR}/config.yml"
cp -f "${SCRIPT_DIR}/container-monitor-map.yaml" "${OUT_DIR}/container-monitor-map.yaml"
if [[ ! -f "${OUT_DIR}/Dockerfile" ]]; then
echo "Missing ${OUT_DIR}/Dockerfile"
exit 1
fi
if [[ ! -f "${OUT_DIR}/docker-compose.watchtower-uptime-sync.yml" ]]; then
echo "Missing ${OUT_DIR}/docker-compose.watchtower-uptime-sync.yml"
exit 1
fi
if [[ ! -f "${OUT_DIR}/docker-compose.watchtower-embedded.yml" ]]; then
echo "Missing ${OUT_DIR}/docker-compose.watchtower-embedded.yml"
exit 1
fi
if [[ ! -f "${OUT_DIR}/watchtower-embedded/Dockerfile.watchtower-with-uptime-bot" ]]; then
echo "Missing ${OUT_DIR}/watchtower-embedded/Dockerfile.watchtower-with-uptime-bot"
exit 1
fi
if [[ ! -f "${OUT_DIR}/watchtower-embedded/start-watchtower-with-uptime-bot.sh" ]]; then
echo "Missing ${OUT_DIR}/watchtower-embedded/start-watchtower-with-uptime-bot.sh"
exit 1
fi
cd "${OUT_DIR}"
tar -czf "${BUNDLE_NAME}" \
Dockerfile \
docker-compose.watchtower-uptime-sync.yml \
docker-compose.watchtower-embedded.yml \
uptime-bot.py \
requirements.txt \
config.yml \
container-monitor-map.yaml \
watchtower-embedded/Dockerfile.watchtower-with-uptime-bot \
watchtower-embedded/start-watchtower-with-uptime-bot.sh
echo "Bundle created: ${OUT_DIR}/${BUNDLE_NAME}"
+2
View File
@@ -0,0 +1,2 @@
uptime-kuma-api>=1.2.1
PyYAML>=6.0
+426
View File
@@ -0,0 +1,426 @@
#!/usr/bin/env bash
set -euo pipefail
# Installs or updates the uptime bot service and runtime files.
# Intended usage:
# sudo ./setup-update_uptime-bot.sh
APP_NAME="uptime-updates-bot"
SERVICE_NAME="${APP_NAME}.service"
INSTALL_DIR="/opt/uptime-updates"
RUN_AS_USER="root"
RUN_AS_GROUP="root"
ENABLE_ON_BOOT="true"
START_AFTER_INSTALL="true"
DRY_RUN="false"
MIN_PYTHON_VERSION="3.9"
VENV_DIR=""
OVERWRITE_CONFIG="false"
OVERWRITE_MAP="false"
TIMESTAMP="$(date +%Y%m%d-%H%M%S)"
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
SYSTEMD_DIR="/etc/systemd/system"
RUNNER_FILE=""
RUNNER_EXEC=""
log() {
echo "[INFO] $*"
}
warn() {
echo "[WARN] $*" >&2
}
err() {
echo "[ERROR] $*" >&2
}
usage() {
cat <<EOF
Usage:
sudo bash setup-update_uptime-bot.sh [options]
Options:
--install-dir PATH Install directory (default: /opt/uptime-updates)
--service-name NAME systemd unit name (default: uptime-updates-bot.service)
--user USER User to run service as (default: root)
--group GROUP Group to run service as (default: root)
--no-enable Do not enable service on boot
--no-start Do not start/restart service after install
--min-python-version V Minimum Python version if using uptime-bot.py (default: 3.9)
--overwrite-config Replace existing installed config.yml with repo copy
--overwrite-map Replace existing installed container-monitor-map.yaml with repo copy
--overwrite-all Replace both installed config/map files with repo copies
--dry-run Print actions without changing the system
-h, --help Show this help
Notes:
- This script is idempotent: re-run it after making changes to bot files.
- Source files are read from the same directory as this script.
EOF
}
run_cmd() {
if [[ "${DRY_RUN}" == "true" ]]; then
echo "[DRY-RUN] $*"
else
eval "$@"
fi
}
require_root() {
if [[ "${EUID}" -ne 0 ]]; then
err "Please run as root or with sudo."
exit 1
fi
}
version_ge() {
local actual="$1"
local required="$2"
[[ "$(printf '%s\n%s\n' "${required}" "${actual}" | sort -V | head -n1)" == "${required}" ]]
}
detect_package_manager() {
if command -v apt-get >/dev/null 2>&1; then
echo "apt-get"
elif command -v dnf >/dev/null 2>&1; then
echo "dnf"
elif command -v yum >/dev/null 2>&1; then
echo "yum"
elif command -v zypper >/dev/null 2>&1; then
echo "zypper"
elif command -v pacman >/dev/null 2>&1; then
echo "pacman"
elif command -v apk >/dev/null 2>&1; then
echo "apk"
else
echo ""
fi
}
install_python3() {
local pm
pm="$(detect_package_manager)"
if [[ -z "${pm}" ]]; then
err "No supported package manager found to install Python automatically."
err "Install Python ${MIN_PYTHON_VERSION}+ manually, then re-run this script."
exit 1
fi
log "Attempting to install Python 3 using ${pm}"
case "${pm}" in
apt-get)
run_cmd "apt-get update"
run_cmd "apt-get install -y python3 python3-venv python3-pip"
;;
dnf)
run_cmd "dnf install -y python3 python3-pip"
;;
yum)
run_cmd "yum install -y python3 python3-pip"
;;
zypper)
run_cmd "zypper --non-interactive install python3 python3-pip"
;;
pacman)
run_cmd "pacman -Sy --noconfirm python python-pip"
;;
apk)
run_cmd "apk add --no-cache python3 py3-pip"
;;
*)
err "Unsupported package manager: ${pm}"
exit 1
;;
esac
}
setup_python_environment() {
local venv_python
local requirements_path
VENV_DIR="${INSTALL_DIR}/.venv"
venv_python="${VENV_DIR}/bin/python"
requirements_path="${INSTALL_DIR}/requirements.txt"
log "Creating/updating Python virtual environment at ${VENV_DIR}"
run_cmd "python3 -m venv \"${VENV_DIR}\""
log "Installing Python dependencies for uptime bot"
run_cmd "\"${venv_python}\" -m pip install --upgrade pip"
if [[ -f "${requirements_path}" ]]; then
run_cmd "\"${venv_python}\" -m pip install -r \"${requirements_path}\""
else
warn "requirements.txt not found in install dir. Falling back to default dependencies."
run_cmd "\"${venv_python}\" -m pip install uptime-kuma-api PyYAML"
fi
}
ensure_python3_compatible() {
local py_ver
if ! command -v python3 >/dev/null 2>&1; then
warn "python3 not found; attempting automatic install."
install_python3
fi
if ! command -v python3 >/dev/null 2>&1; then
err "python3 is still unavailable after install attempt."
exit 1
fi
if [[ "${DRY_RUN}" == "true" ]]; then
log "Dry-run: skipping python version verification command."
return
fi
py_ver="$(python3 -c 'import sys; print(f"{sys.version_info.major}.{sys.version_info.minor}")')"
if version_ge "${py_ver}" "${MIN_PYTHON_VERSION}"; then
log "Detected python3 ${py_ver} (required: ${MIN_PYTHON_VERSION}+)"
return
fi
warn "Detected python3 ${py_ver}, but ${MIN_PYTHON_VERSION}+ is required. Trying to upgrade python3."
install_python3
py_ver="$(python3 -c 'import sys; print(f"{sys.version_info.major}.{sys.version_info.minor}")')"
if ! version_ge "${py_ver}" "${MIN_PYTHON_VERSION}"; then
err "python3 ${py_ver} is still below required ${MIN_PYTHON_VERSION}+ after install/upgrade attempt."
err "Please install a newer Python manually, then re-run this script."
exit 1
fi
log "Python upgraded to compatible version: ${py_ver}"
}
parse_args() {
while [[ $# -gt 0 ]]; do
case "$1" in
--install-dir)
shift
[[ $# -gt 0 ]] || { err "Missing value for --install-dir"; exit 1; }
INSTALL_DIR="$1"
;;
--service-name)
shift
[[ $# -gt 0 ]] || { err "Missing value for --service-name"; exit 1; }
SERVICE_NAME="$1"
;;
--user)
shift
[[ $# -gt 0 ]] || { err "Missing value for --user"; exit 1; }
RUN_AS_USER="$1"
;;
--group)
shift
[[ $# -gt 0 ]] || { err "Missing value for --group"; exit 1; }
RUN_AS_GROUP="$1"
;;
--no-enable)
ENABLE_ON_BOOT="false"
;;
--no-start)
START_AFTER_INSTALL="false"
;;
--min-python-version)
shift
[[ $# -gt 0 ]] || { err "Missing value for --min-python-version"; exit 1; }
MIN_PYTHON_VERSION="$1"
;;
--overwrite-config)
OVERWRITE_CONFIG="true"
;;
--overwrite-map)
OVERWRITE_MAP="true"
;;
--overwrite-all)
OVERWRITE_CONFIG="true"
OVERWRITE_MAP="true"
;;
--dry-run)
DRY_RUN="true"
;;
-h|--help)
usage
exit 0
;;
*)
err "Unknown argument: $1"
usage
exit 1
;;
esac
shift
done
}
check_prereqs() {
command -v systemctl >/dev/null 2>&1 || { err "systemctl is required."; exit 1; }
command -v install >/dev/null 2>&1 || { err "install is required."; exit 1; }
if [[ -f "${SCRIPT_DIR}/uptime-bot.py" ]]; then
ensure_python3_compatible
RUNNER_FILE="uptime-bot.py"
VENV_DIR="${INSTALL_DIR}/.venv"
RUNNER_EXEC="${VENV_DIR}/bin/python ${INSTALL_DIR}/uptime-bot.py"
elif [[ -f "${SCRIPT_DIR}/uptime-bot.sh" ]]; then
RUNNER_FILE="uptime-bot.sh"
RUNNER_EXEC="/usr/bin/env bash ${INSTALL_DIR}/uptime-bot.sh"
else
err "No runner found. Create uptime-bot.py or uptime-bot.sh in ${SCRIPT_DIR}."
exit 1
fi
[[ -f "${SCRIPT_DIR}/config.yml" ]] || { err "Missing ${SCRIPT_DIR}/config.yml"; exit 1; }
[[ -f "${SCRIPT_DIR}/container-monitor-map.yaml" ]] || { err "Missing ${SCRIPT_DIR}/container-monitor-map.yaml"; exit 1; }
}
install_files() {
local src_config
local dst_config
local src_map
local dst_map
src_config="${SCRIPT_DIR}/config.yml"
dst_config="${INSTALL_DIR}/config.yml"
src_map="${SCRIPT_DIR}/container-monitor-map.yaml"
dst_map="${INSTALL_DIR}/container-monitor-map.yaml"
log "Installing files into ${INSTALL_DIR}"
run_cmd "mkdir -p \"${INSTALL_DIR}\""
if [[ -f "${dst_config}" && "${OVERWRITE_CONFIG}" != "true" ]]; then
warn "Keeping existing installed config.yml (use --overwrite-config to replace)."
else
if [[ -f "${dst_config}" && "${OVERWRITE_CONFIG}" == "true" ]]; then
run_cmd "cp -a \"${dst_config}\" \"${dst_config}.bak.${TIMESTAMP}\""
log "Backed up existing config.yml to ${dst_config}.bak.${TIMESTAMP}"
fi
run_cmd "install -m 0644 \"${src_config}\" \"${dst_config}\""
fi
if [[ -f "${dst_map}" && "${OVERWRITE_MAP}" != "true" ]]; then
warn "Keeping existing installed container-monitor-map.yaml (use --overwrite-map to replace)."
else
if [[ -f "${dst_map}" && "${OVERWRITE_MAP}" == "true" ]]; then
run_cmd "cp -a \"${dst_map}\" \"${dst_map}.bak.${TIMESTAMP}\""
log "Backed up existing container-monitor-map.yaml to ${dst_map}.bak.${TIMESTAMP}"
fi
run_cmd "install -m 0644 \"${src_map}\" \"${dst_map}\""
fi
if [[ -f "${SCRIPT_DIR}/requirements.txt" ]]; then
run_cmd "install -m 0644 \"${SCRIPT_DIR}/requirements.txt\" \"${INSTALL_DIR}/requirements.txt\""
fi
run_cmd "install -m 0755 \"${SCRIPT_DIR}/${RUNNER_FILE}\" \"${INSTALL_DIR}/${RUNNER_FILE}\""
run_cmd "install -m 0755 \"${SCRIPT_DIR}/setup-update_uptime-bot.sh\" \"${INSTALL_DIR}/setup-update_uptime-bot.sh\""
run_cmd "chown -R ${RUN_AS_USER}:${RUN_AS_GROUP} \"${INSTALL_DIR}\""
}
write_service() {
local service_path="${SYSTEMD_DIR}/${SERVICE_NAME}"
log "Writing service unit ${service_path}"
if [[ "${DRY_RUN}" == "true" ]]; then
cat <<EOF
[DRY-RUN] Would write:
[Unit]
Description=Uptime Updates Bot (container ID sync)
After=network-online.target
Wants=network-online.target
[Service]
Type=simple
User=${RUN_AS_USER}
Group=${RUN_AS_GROUP}
WorkingDirectory=${INSTALL_DIR}
ExecStart=${RUNNER_EXEC}
Restart=always
RestartSec=5
[Install]
WantedBy=multi-user.target
EOF
return
fi
cat > "${service_path}" <<EOF
[Unit]
Description=Uptime Updates Bot (container ID sync)
After=network-online.target
Wants=network-online.target
[Service]
Type=simple
User=${RUN_AS_USER}
Group=${RUN_AS_GROUP}
WorkingDirectory=${INSTALL_DIR}
ExecStart=${RUNNER_EXEC}
Restart=always
RestartSec=5
[Install]
WantedBy=multi-user.target
EOF
}
reload_and_apply_service() {
log "Reloading systemd"
run_cmd "systemctl daemon-reload"
if [[ "${ENABLE_ON_BOOT}" == "true" ]]; then
log "Enabling ${SERVICE_NAME}"
run_cmd "systemctl enable ${SERVICE_NAME}"
else
warn "Skipping enable step (--no-enable used)."
fi
if [[ "${START_AFTER_INSTALL}" == "true" ]]; then
if [[ "${DRY_RUN}" == "true" ]]; then
echo "[DRY-RUN] systemctl restart ${SERVICE_NAME}"
else
if systemctl list-unit-files | grep -q "^${SERVICE_NAME}"; then
log "Restarting ${SERVICE_NAME}"
systemctl restart "${SERVICE_NAME}"
else
log "Starting ${SERVICE_NAME}"
systemctl start "${SERVICE_NAME}"
fi
fi
else
warn "Skipping start/restart step (--no-start used)."
fi
}
print_summary() {
echo
echo "Install/update complete."
echo "Service: ${SERVICE_NAME}"
echo "Install dir: ${INSTALL_DIR}"
echo "Runner: ${RUNNER_FILE}"
echo
echo "Useful commands:"
echo " systemctl status ${SERVICE_NAME}"
echo " journalctl -u ${SERVICE_NAME} -f"
}
main() {
parse_args "$@"
require_root
check_prereqs
install_files
if [[ "${RUNNER_FILE}" == "uptime-bot.py" ]]; then
setup_python_environment
fi
write_service
reload_and_apply_service
print_summary
}
main "$@"
+277
View File
@@ -0,0 +1,277 @@
#!/usr/bin/env python3
"""Continuously sync Docker container IDs into Uptime Kuma docker monitors.
This bot reads:
- config.yml
- container-monitor-map.yaml
From the same directory as this script.
"""
from __future__ import annotations
import json
import logging
import os
import signal
import sys
import time
import urllib.error
import urllib.parse
import urllib.request
from typing import Any, Dict, List, Optional
import yaml
from uptime_kuma_api import UptimeKumaApi
BASE_DIR = os.path.dirname(os.path.abspath(__file__))
CONFIG_PATH = os.getenv("UPTIME_BOT_CONFIG", os.path.join(BASE_DIR, "config.yml"))
MAP_PATH = os.getenv("UPTIME_BOT_MAP", os.path.join(BASE_DIR, "container-monitor-map.yaml"))
STOP = False
def _signal_handler(signum: int, _frame: Any) -> None:
global STOP
STOP = True
logging.info("Received signal %s, shutting down...", signum)
def _load_yaml(path: str) -> Dict[str, Any]:
with open(path, "r", encoding="utf-8") as handle:
data = yaml.safe_load(handle) or {}
if not isinstance(data, dict):
raise ValueError(f"YAML root in {path} must be a mapping")
return data
def _normalize_docker_host_url(raw_url: str) -> str:
if raw_url.startswith("tcp://"):
return "http://" + raw_url[len("tcp://") :]
if raw_url.startswith("http://") or raw_url.startswith("https://"):
return raw_url
raise ValueError(f"Unsupported host_api scheme: {raw_url}")
def _docker_get_container_id(host_api: str, container_name: str, timeout_seconds: int) -> Optional[str]:
"""Resolve a container name on a Docker host to its full container ID.
Uses Docker remote API endpoint: /containers/{name}/json
"""
base_url = _normalize_docker_host_url(host_api).rstrip("/")
encoded_name = urllib.parse.quote(container_name, safe="")
url = f"{base_url}/containers/{encoded_name}/json"
request = urllib.request.Request(url=url, method="GET", headers={"Accept": "application/json"})
try:
with urllib.request.urlopen(request, timeout=timeout_seconds) as response:
payload = json.loads(response.read().decode("utf-8"))
except urllib.error.HTTPError as exc:
if exc.code == 404:
logging.warning("Container not found on host %s: %s", host_api, container_name)
return None
raise
container_id = payload.get("Id")
if not container_id:
raise RuntimeError(f"Docker API response missing Id for {container_name} on {host_api}")
return str(container_id)
def _api_login(url: str, api_key: str) -> UptimeKumaApi:
api = UptimeKumaApi(url)
# Uptime Kuma API key auth in wrapper is login_by_token.
api.login_by_token(api_key)
return api
def _update_monitor_container_id(
api: UptimeKumaApi,
monitor_id: int,
new_container_id: str,
dry_run: bool,
) -> bool:
"""Attempt to update docker_container for a monitor.
Returns True if monitor was updated, False if unchanged or dry-run.
"""
monitor = api.get_monitor(monitor_id)
if not isinstance(monitor, dict):
raise RuntimeError(f"Unexpected monitor payload for id {monitor_id}: {type(monitor)}")
current_id = str(monitor.get("docker_container") or "")
if current_id == new_container_id:
return False
if dry_run:
logging.info(
"Dry-run: would update monitor %s docker_container from %s to %s",
monitor_id,
current_id,
new_container_id,
)
return False
last_error: Optional[Exception] = None
# Try minimal edit call patterns first.
for call in (
lambda: api.edit_monitor(monitor_id, docker_container=new_container_id),
lambda: api.edit_monitor(id=monitor_id, docker_container=new_container_id),
):
try:
call()
logging.info(
"Updated monitor %s docker_container from %s to %s",
monitor_id,
current_id,
new_container_id,
)
return True
except Exception as exc: # noqa: BLE001
last_error = exc
if last_error is None:
raise RuntimeError(f"Failed to update monitor {monitor_id} for unknown reason")
raise RuntimeError(f"Failed to update monitor {monitor_id}: {last_error}")
def _run_once(config: Dict[str, Any], mapping: Dict[str, Any]) -> None:
uptime_cfg = config.get("uptime_kuma") or {}
bot_cfg = config.get("bot") or {}
uptime_url = str(uptime_cfg.get("url") or "").strip()
api_key = str(uptime_cfg.get("api_key") or "").strip()
dry_run = bool(bot_cfg.get("dry_run", False))
timeout_seconds = int(bot_cfg.get("request_timeout_seconds", 10))
if not uptime_url:
raise ValueError("config.yml missing uptime_kuma.url")
if not api_key or api_key == "PUT_YOUR_API_KEY_HERE":
raise ValueError("config.yml missing real uptime_kuma.api_key")
mappings = mapping.get("mappings") or []
if not isinstance(mappings, list):
raise ValueError("container-monitor-map.yaml: mappings must be a list")
if not mappings:
logging.info("No mappings configured. Nothing to do.")
return
api = _api_login(uptime_url, api_key)
updated = 0
try:
for item in mappings:
if not isinstance(item, dict):
logging.warning("Skipping invalid mapping item (not a mapping): %r", item)
continue
if item.get("enabled", True) is False:
continue
name = str(item.get("name") or "unnamed")
host_api = str(item.get("host_api") or "").strip()
container_name = str(item.get("container_name") or "").strip()
expected_type = str(item.get("expected_uptime_type") or "").strip().lower()
monitor_id_raw = item.get("uptime_monitor_id")
try:
monitor_id = int(monitor_id_raw)
except Exception as exc: # noqa: BLE001
logging.error("[%s] Invalid uptime_monitor_id: %r (%s)", name, monitor_id_raw, exc)
continue
if not host_api or not container_name:
logging.error("[%s] Missing host_api or container_name", name)
continue
try:
container_id = _docker_get_container_id(host_api, container_name, timeout_seconds)
if not container_id:
continue
monitor = api.get_monitor(monitor_id)
monitor_type = str((monitor or {}).get("type") or "").lower()
if expected_type and monitor_type and monitor_type != expected_type:
logging.error(
"[%s] Monitor %s type mismatch. expected=%s actual=%s",
name,
monitor_id,
expected_type,
monitor_type,
)
continue
changed = _update_monitor_container_id(api, monitor_id, container_id, dry_run)
if changed:
updated += 1
except Exception as exc: # noqa: BLE001
logging.exception("[%s] Failed to process mapping: %s", name, exc)
finally:
try:
api.disconnect()
except Exception: # noqa: BLE001
pass
logging.info("Cycle complete. monitors_updated=%s", updated)
def main() -> int:
signal.signal(signal.SIGINT, _signal_handler)
signal.signal(signal.SIGTERM, _signal_handler)
logging.basicConfig(
level=logging.INFO,
format="%(asctime)s %(levelname)s %(message)s",
)
if not os.path.exists(CONFIG_PATH):
logging.error("Missing config file: %s", CONFIG_PATH)
return 1
if not os.path.exists(MAP_PATH):
logging.error("Missing mapping file: %s", MAP_PATH)
return 1
config = _load_yaml(CONFIG_PATH)
mapping = _load_yaml(MAP_PATH)
bot_cfg = config.get("bot") or {}
interval_seconds = int(bot_cfg.get("poll_interval_seconds", 60))
if interval_seconds < 5:
logging.warning("poll_interval_seconds too low (%s), forcing to 5", interval_seconds)
interval_seconds = 5
logging.info("Starting uptime bot. interval=%ss", interval_seconds)
while not STOP:
try:
_run_once(config, mapping)
except Exception as exc: # noqa: BLE001
logging.exception("Cycle failed: %s", exc)
if STOP:
break
slept = 0
while slept < interval_seconds and not STOP:
time.sleep(1)
slept += 1
# Reload config/map each cycle so file changes apply without restart.
try:
config = _load_yaml(CONFIG_PATH)
mapping = _load_yaml(MAP_PATH)
bot_cfg = config.get("bot") or {}
new_interval = int(bot_cfg.get("poll_interval_seconds", interval_seconds))
interval_seconds = max(5, new_interval)
except Exception as exc: # noqa: BLE001
logging.warning("Failed to reload config/map, using previous values: %s", exc)
logging.info("Uptime bot stopped")
return 0
if __name__ == "__main__":
sys.exit(main())
@@ -0,0 +1,15 @@
FROM python:3.12-alpine
WORKDIR /app
COPY requirements.txt /app/requirements.txt
RUN pip install --no-cache-dir -r /app/requirements.txt
COPY uptime-bot.py /app/uptime-bot.py
COPY config.yml /app/config.yml
COPY container-monitor-map.yaml /app/container-monitor-map.yaml
ENV UPTIME_BOT_CONFIG=/app/config.yml
ENV UPTIME_BOT_MAP=/app/container-monitor-map.yaml
CMD ["python", "/app/uptime-bot.py"]
@@ -0,0 +1,50 @@
# Watchtower Export Bundle
This folder is a portable package with two Docker deployment modes:
- Standalone bot + separate watchtower container
- Embedded bot inside a custom watchtower image
## Included Files
- Dockerfile
- docker-compose.watchtower-uptime-sync.yml
- docker-compose.watchtower-embedded.yml
- uptime-bot.py
- requirements.txt
- config.yml
- container-monitor-map.yaml
- watchtower-embedded/Dockerfile.watchtower-with-uptime-bot
- watchtower-embedded/start-watchtower-with-uptime-bot.sh
## Create Export Tarball
From uptime-updates directory:
```bash
bash export-watchtower-bundle.sh
```
This creates a timestamped tar.gz in this folder.
## Run Standalone Mode (Recommended)
In this folder:
```bash
docker compose -f docker-compose.watchtower-uptime-sync.yml up -d --build
```
## Run Embedded Watchtower Mode
In this folder:
```bash
docker compose -f docker-compose.watchtower-embedded.yml up -d --build
```
## Notes
- The bot uses Docker host API endpoints listed in container-monitor-map.yaml.
- Keep config.yml and container-monitor-map.yaml updated with your real values.
- These Docker deployments do not require systemd.
@@ -0,0 +1,9 @@
uptime_kuma:
url: "http://127.0.0.1:3001"
api_key: "PUT_YOUR_API_KEY_HERE"
# Optional bot behavior settings
bot:
dry_run: false
request_timeout_seconds: 10
poll_interval_seconds: 60
@@ -0,0 +1,43 @@
# Container to Uptime Kuma monitor mapping
#
# Fill in one item per container you want tracked.
# The bot can read this file to know:
# 1) which Docker host to query
# 2) which container on that host to watch
# 3) which Uptime Kuma monitor to update when container ID changes
#
# Notes:
# - uptime_monitor_id is the numeric ID in Uptime Kuma.
# You can get it from the monitor URL, e.g. /dashboard/42 -> 42
# - host_api should be the Docker API endpoint for that host.
# Example: tcp://10.0.84.21:2375
# - container_name should match docker container name used by that host.
#
# Optional fields:
# - enabled: true/false (default true)
# - expected_uptime_type: set to "docker" to protect against wrong monitor type updates
mappings:
- name: "media-server jellyfin"
enabled: true
host_label: "media-server"
host_api: "tcp://10.0.84.21:2375"
container_name: "jellyfin"
uptime_monitor_id: 21
expected_uptime_type: "docker"
- name: "nas immich"
enabled: true
host_label: "nas"
host_api: "tcp://10.0.84.22:2375"
container_name: "immich-server"
uptime_monitor_id: 34
expected_uptime_type: "docker"
- name: "lab pihole"
enabled: false
host_label: "lab"
host_api: "tcp://10.0.84.30:2375"
container_name: "pihole"
uptime_monitor_id: 56
expected_uptime_type: "docker"
@@ -0,0 +1,14 @@
version: "3.8"
services:
watchtower-with-uptime-bot:
build:
context: .
dockerfile: watchtower-embedded/Dockerfile.watchtower-with-uptime-bot
container_name: watchtower-with-uptime-bot
restart: unless-stopped
volumes:
- /var/run/docker.sock:/var/run/docker.sock
- ./config.yml:/opt/uptime-bot/config.yml:ro
- ./container-monitor-map.yaml:/opt/uptime-bot/container-monitor-map.yaml:ro
command: --interval 300 --cleanup
@@ -0,0 +1,23 @@
version: "3.8"
services:
watchtower:
image: containrrr/watchtower:latest
container_name: watchtower
restart: unless-stopped
volumes:
- /var/run/docker.sock:/var/run/docker.sock
command: --interval 300 --cleanup
uptime-sync-bot:
build:
context: .
dockerfile: Dockerfile
container_name: uptime-sync-bot
restart: unless-stopped
volumes:
- ./config.yml:/app/config.yml:ro
- ./container-monitor-map.yaml:/app/container-monitor-map.yaml:ro
environment:
- UPTIME_BOT_CONFIG=/app/config.yml
- UPTIME_BOT_MAP=/app/container-monitor-map.yaml
@@ -0,0 +1,2 @@
uptime-kuma-api>=1.2.1
PyYAML>=6.0
@@ -0,0 +1,277 @@
#!/usr/bin/env python3
"""Continuously sync Docker container IDs into Uptime Kuma docker monitors.
This bot reads:
- config.yml
- container-monitor-map.yaml
From the same directory as this script.
"""
from __future__ import annotations
import json
import logging
import os
import signal
import sys
import time
import urllib.error
import urllib.parse
import urllib.request
from typing import Any, Dict, List, Optional
import yaml
from uptime_kuma_api import UptimeKumaApi
BASE_DIR = os.path.dirname(os.path.abspath(__file__))
CONFIG_PATH = os.getenv("UPTIME_BOT_CONFIG", os.path.join(BASE_DIR, "config.yml"))
MAP_PATH = os.getenv("UPTIME_BOT_MAP", os.path.join(BASE_DIR, "container-monitor-map.yaml"))
STOP = False
def _signal_handler(signum: int, _frame: Any) -> None:
global STOP
STOP = True
logging.info("Received signal %s, shutting down...", signum)
def _load_yaml(path: str) -> Dict[str, Any]:
with open(path, "r", encoding="utf-8") as handle:
data = yaml.safe_load(handle) or {}
if not isinstance(data, dict):
raise ValueError(f"YAML root in {path} must be a mapping")
return data
def _normalize_docker_host_url(raw_url: str) -> str:
if raw_url.startswith("tcp://"):
return "http://" + raw_url[len("tcp://") :]
if raw_url.startswith("http://") or raw_url.startswith("https://"):
return raw_url
raise ValueError(f"Unsupported host_api scheme: {raw_url}")
def _docker_get_container_id(host_api: str, container_name: str, timeout_seconds: int) -> Optional[str]:
"""Resolve a container name on a Docker host to its full container ID.
Uses Docker remote API endpoint: /containers/{name}/json
"""
base_url = _normalize_docker_host_url(host_api).rstrip("/")
encoded_name = urllib.parse.quote(container_name, safe="")
url = f"{base_url}/containers/{encoded_name}/json"
request = urllib.request.Request(url=url, method="GET", headers={"Accept": "application/json"})
try:
with urllib.request.urlopen(request, timeout=timeout_seconds) as response:
payload = json.loads(response.read().decode("utf-8"))
except urllib.error.HTTPError as exc:
if exc.code == 404:
logging.warning("Container not found on host %s: %s", host_api, container_name)
return None
raise
container_id = payload.get("Id")
if not container_id:
raise RuntimeError(f"Docker API response missing Id for {container_name} on {host_api}")
return str(container_id)
def _api_login(url: str, api_key: str) -> UptimeKumaApi:
api = UptimeKumaApi(url)
# Uptime Kuma API key auth in wrapper is login_by_token.
api.login_by_token(api_key)
return api
def _update_monitor_container_id(
api: UptimeKumaApi,
monitor_id: int,
new_container_id: str,
dry_run: bool,
) -> bool:
"""Attempt to update docker_container for a monitor.
Returns True if monitor was updated, False if unchanged or dry-run.
"""
monitor = api.get_monitor(monitor_id)
if not isinstance(monitor, dict):
raise RuntimeError(f"Unexpected monitor payload for id {monitor_id}: {type(monitor)}")
current_id = str(monitor.get("docker_container") or "")
if current_id == new_container_id:
return False
if dry_run:
logging.info(
"Dry-run: would update monitor %s docker_container from %s to %s",
monitor_id,
current_id,
new_container_id,
)
return False
last_error: Optional[Exception] = None
# Try minimal edit call patterns first.
for call in (
lambda: api.edit_monitor(monitor_id, docker_container=new_container_id),
lambda: api.edit_monitor(id=monitor_id, docker_container=new_container_id),
):
try:
call()
logging.info(
"Updated monitor %s docker_container from %s to %s",
monitor_id,
current_id,
new_container_id,
)
return True
except Exception as exc: # noqa: BLE001
last_error = exc
if last_error is None:
raise RuntimeError(f"Failed to update monitor {monitor_id} for unknown reason")
raise RuntimeError(f"Failed to update monitor {monitor_id}: {last_error}")
def _run_once(config: Dict[str, Any], mapping: Dict[str, Any]) -> None:
uptime_cfg = config.get("uptime_kuma") or {}
bot_cfg = config.get("bot") or {}
uptime_url = str(uptime_cfg.get("url") or "").strip()
api_key = str(uptime_cfg.get("api_key") or "").strip()
dry_run = bool(bot_cfg.get("dry_run", False))
timeout_seconds = int(bot_cfg.get("request_timeout_seconds", 10))
if not uptime_url:
raise ValueError("config.yml missing uptime_kuma.url")
if not api_key or api_key == "PUT_YOUR_API_KEY_HERE":
raise ValueError("config.yml missing real uptime_kuma.api_key")
mappings = mapping.get("mappings") or []
if not isinstance(mappings, list):
raise ValueError("container-monitor-map.yaml: mappings must be a list")
if not mappings:
logging.info("No mappings configured. Nothing to do.")
return
api = _api_login(uptime_url, api_key)
updated = 0
try:
for item in mappings:
if not isinstance(item, dict):
logging.warning("Skipping invalid mapping item (not a mapping): %r", item)
continue
if item.get("enabled", True) is False:
continue
name = str(item.get("name") or "unnamed")
host_api = str(item.get("host_api") or "").strip()
container_name = str(item.get("container_name") or "").strip()
expected_type = str(item.get("expected_uptime_type") or "").strip().lower()
monitor_id_raw = item.get("uptime_monitor_id")
try:
monitor_id = int(monitor_id_raw)
except Exception as exc: # noqa: BLE001
logging.error("[%s] Invalid uptime_monitor_id: %r (%s)", name, monitor_id_raw, exc)
continue
if not host_api or not container_name:
logging.error("[%s] Missing host_api or container_name", name)
continue
try:
container_id = _docker_get_container_id(host_api, container_name, timeout_seconds)
if not container_id:
continue
monitor = api.get_monitor(monitor_id)
monitor_type = str((monitor or {}).get("type") or "").lower()
if expected_type and monitor_type and monitor_type != expected_type:
logging.error(
"[%s] Monitor %s type mismatch. expected=%s actual=%s",
name,
monitor_id,
expected_type,
monitor_type,
)
continue
changed = _update_monitor_container_id(api, monitor_id, container_id, dry_run)
if changed:
updated += 1
except Exception as exc: # noqa: BLE001
logging.exception("[%s] Failed to process mapping: %s", name, exc)
finally:
try:
api.disconnect()
except Exception: # noqa: BLE001
pass
logging.info("Cycle complete. monitors_updated=%s", updated)
def main() -> int:
signal.signal(signal.SIGINT, _signal_handler)
signal.signal(signal.SIGTERM, _signal_handler)
logging.basicConfig(
level=logging.INFO,
format="%(asctime)s %(levelname)s %(message)s",
)
if not os.path.exists(CONFIG_PATH):
logging.error("Missing config file: %s", CONFIG_PATH)
return 1
if not os.path.exists(MAP_PATH):
logging.error("Missing mapping file: %s", MAP_PATH)
return 1
config = _load_yaml(CONFIG_PATH)
mapping = _load_yaml(MAP_PATH)
bot_cfg = config.get("bot") or {}
interval_seconds = int(bot_cfg.get("poll_interval_seconds", 60))
if interval_seconds < 5:
logging.warning("poll_interval_seconds too low (%s), forcing to 5", interval_seconds)
interval_seconds = 5
logging.info("Starting uptime bot. interval=%ss", interval_seconds)
while not STOP:
try:
_run_once(config, mapping)
except Exception as exc: # noqa: BLE001
logging.exception("Cycle failed: %s", exc)
if STOP:
break
slept = 0
while slept < interval_seconds and not STOP:
time.sleep(1)
slept += 1
# Reload config/map each cycle so file changes apply without restart.
try:
config = _load_yaml(CONFIG_PATH)
mapping = _load_yaml(MAP_PATH)
bot_cfg = config.get("bot") or {}
new_interval = int(bot_cfg.get("poll_interval_seconds", interval_seconds))
interval_seconds = max(5, new_interval)
except Exception as exc: # noqa: BLE001
logging.warning("Failed to reload config/map, using previous values: %s", exc)
logging.info("Uptime bot stopped")
return 0
if __name__ == "__main__":
sys.exit(main())
@@ -0,0 +1,23 @@
FROM containrrr/watchtower:latest
USER root
RUN apk add --no-cache python3 py3-pip
WORKDIR /opt/uptime-bot
COPY requirements.txt /opt/uptime-bot/requirements.txt
RUN pip3 install --no-cache-dir -r /opt/uptime-bot/requirements.txt
COPY uptime-bot.py /opt/uptime-bot/uptime-bot.py
COPY config.yml /opt/uptime-bot/config.yml
COPY container-monitor-map.yaml /opt/uptime-bot/container-monitor-map.yaml
COPY watchtower-embedded/start-watchtower-with-uptime-bot.sh /usr/local/bin/start-watchtower-with-uptime-bot.sh
RUN chmod +x /usr/local/bin/start-watchtower-with-uptime-bot.sh
ENV UPTIME_BOT_CONFIG=/opt/uptime-bot/config.yml
ENV UPTIME_BOT_MAP=/opt/uptime-bot/container-monitor-map.yaml
ENTRYPOINT ["/usr/local/bin/start-watchtower-with-uptime-bot.sh"]
CMD ["--interval", "300", "--cleanup"]
@@ -0,0 +1,50 @@
#!/bin/sh
set -eu
BOT_SCRIPT="/opt/uptime-bot/uptime-bot.py"
WATCHTOWER_BIN="/watchtower"
if [ ! -x "${WATCHTOWER_BIN}" ]; then
echo "[ERROR] watchtower binary not found at ${WATCHTOWER_BIN}" >&2
exit 1
fi
if [ ! -f "${BOT_SCRIPT}" ]; then
echo "[ERROR] bot script not found at ${BOT_SCRIPT}" >&2
exit 1
fi
python3 "${BOT_SCRIPT}" &
BOT_PID=$!
"${WATCHTOWER_BIN}" "$@" &
WT_PID=$!
shutdown() {
kill "${BOT_PID}" 2>/dev/null || true
kill "${WT_PID}" 2>/dev/null || true
wait "${BOT_PID}" 2>/dev/null || true
wait "${WT_PID}" 2>/dev/null || true
}
trap shutdown INT TERM
while :; do
if ! kill -0 "${BOT_PID}" 2>/dev/null; then
echo "[ERROR] uptime bot exited; stopping watchtower" >&2
kill "${WT_PID}" 2>/dev/null || true
wait "${WT_PID}" 2>/dev/null || true
wait "${BOT_PID}" 2>/dev/null || true
exit 1
fi
if ! kill -0 "${WT_PID}" 2>/dev/null; then
echo "[ERROR] watchtower exited; stopping uptime bot" >&2
kill "${BOT_PID}" 2>/dev/null || true
wait "${BOT_PID}" 2>/dev/null || true
wait "${WT_PID}" 2>/dev/null || true
exit 1
fi
sleep 2
done