Merge pull request #12 from samuelrb/feature/add_ephemeral_run_to_doc

Ephemeral run, remove -x option in script and json logs

Author: samuelrb

README.md

@@ -16,27 +16,50 @@ A Docker container that monitors your internet connection speed (download and up
 
 ## 🐳 Usage
 
+### 🚀 Quickstart (Docker run)
+
+#### 🔹 Using Docker Run
+
+Run the container directly from Docker Hub with scheduled checks and environment configuration:
+
+```bash
+docker run -d \
+  --name speedtest-monitor \
+  -e CRON_SCHEDULE="30 * * * *" \
+  -e MIN_DOWNLOAD=270 \
+  -e MIN_UPLOAD=260 \
+  -e TELEGRAM_BOT_TOKEN="" \
+  -e TELEGRAM_CHAT_ID="" \
+  --restart unless-stopped \
+  samuelrb/speedtest-monitor:latest
+```
+
+#### 🔹 Using Docker Compose
+```bash
+docker compose up -d
+```
+
 ### Build
 ```bash
-docker build -t speedtest-monitor .
+docker build -t speedtest-monitor docker
 ```
 ### Run simple (without telegram notifications)
 ```bash
-docker run -d --restart=always --name speedtest-monitor speedtest-monitor
+docker run -d --restart=always --name speedtest-monitor samuelrb/speedtest-monitor
 ```
 ### Run with options all options (remove unused options)
 
 ```bash
 docker run -d \
-  -e MIN_DOWNLOAD=1000 \ 
-  -e MIN_UPLOAD=1000 \ 
+  -e MIN_DOWNLOAD=1000 \
+  -e MIN_UPLOAD=1000 \
   -e SERVER_ID=12345 \
   -e TELEGRAM_BOT_TOKEN="1234567:AABCC123_asdfjnnASDF" \
   -e TELEGRAM_CHAT_ID="12345667" \
   -e CRON_SCHEDULE="* * * * *" \
   --restart=always \
   --name speedtest-monitor \
-  speedtest-monitor
+  samuelrb/speedtest-monitor
 ```
 
 ### Output
@@ -56,7 +79,7 @@ docker logs -f speedtest-monitor
 
 You can receive speed alerts via Telegram if the measured download or upload speeds fall below the configured thresholds.
 
-To enable this feature, set the environment variables `TELEGRAM_BOT_TOKEN` and `TELEGRAM_CHAT_ID.
+To enable this feature, set the environment variables `TELEGRAM_BOT_TOKEN` and `TELEGRAM_CHAT_ID`.
 
 #### 📤 Example Telegram message
 
@@ -70,10 +93,10 @@ To enable this feature, set the environment variables `TELEGRAM_BOT_TOKEN` and `
 ### ⚙️ Environment Variables
 
 | Variable | Description                            | Default |
-|---------|----------------------------------------|---------|
-| `MIN_DOWNLOAD` | Minimum download speed threshold (Mbps) | 200     |
-| `MIN_UPLOAD` | Minimum upload speed threshold (Mbps)  | 200     |
-| `SERVER_ID` | Optional Speedtest server ID to use.   | Auto    |
+|---------|----------------------------------------|------|
+| `MIN_DOWNLOAD` | Minimum download speed threshold (Mbps) | 200  |
+| `MIN_UPLOAD` | Minimum upload speed threshold (Mbps)  | 200  |
+| `SERVER_ID` | Optional Speedtest server ID to use.   | Auto |
 | `TELEGRAM_BOT_TOKEN`  | Your Telegram bot's token              | void |
 | `TELEGRAM_CHAT_ID`    | Your personal chat ID or group chat ID | void |
 | `CRON_SCHEDULE`      | The cron expression to schedule script | 0 * * * * |
@@ -90,6 +113,28 @@ By default, Speedtest runs every hour. You can modify the schedule by editing th
 0 * * * * /usr/local/bin/speedtest-check.sh >> /proc/1/fd/1 2>&1
 ```
 
+## 🔹 Using Host Cron (ephemeral container)
+This method allows the container to run only when scheduled by the host system. Ideal for minimizing resource usage.
+
+Create a cron job on your machine (host) with the following line:
+
+```bash
+0 * * * * docker run -d --rm \
+  -e MIN_DOWNLOAD=270 \
+  -e MIN_UPLOAD=260 \
+  -e TELEGRAM_BOT_TOKEN="your_bot_token" \
+  -e TELEGRAM_CHAT_ID="your_chat_id" \
+  samuelrb/speedtest-monitor:latest /usr/local/bin/speedtest-check.sh
+```
+
+Save it with `crontab -e`
+
+No `CRON_SCHEDULE` is needed, since the scheduling is external.
+
+This overrides the default CMD and directly executes the check script.
+
+✅ This is the most lightweight approach — Docker runs only during the test, then shuts down.
+
 ## 🧪 Tests (Optional)
 To validate the container before publishing, you can test the script with:
 

docker/scripts/init.sh

@@ -1,6 +1,5 @@
 #!/bin/bash
 set -e
-set -x
 
 export CRON_SCHEDULE=${CRON_SCHEDULE:-"0 * * * *"}
 

docker/scripts/speedtest-check.sh

@@ -1,11 +1,18 @@
 #!/bin/bash
 set -e
-set -x
 
 set -a
 [ -f /etc/environment ] && . /etc/environment
 set +a
 
+echo_log() {
+  local level="${2:-info}"
+  local timestamp
+  timestamp=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+  echo "{\"timestamp\":\"$timestamp\",\"level\":\"$level\",\"message\":\"$1\"}"
+}
+
 MIN_DOWNLOAD=${MIN_DOWNLOAD:-200}
 MIN_UPLOAD=${MIN_UPLOAD:-200}
 SERVER_ID=${SERVER_ID:-}
@@ -25,12 +32,12 @@ RESULT_URL=$(echo "${RESULT}" | jq -r '.result.url')
 DOWNLOAD_MBPS=$(echo "scale=2; ${DOWNLOAD_BPS} * 8 / 1000000" | bc -l)
 UPLOAD_MBPS=$(echo "scale=2; ${UPLOAD_BPS} * 8 / 1000000" | bc -l)
 
-echo "${DATE} - Result: ${RESULT}"
-echo "${DATE} - Download: ${DOWNLOAD_MBPS} Mbps, Upload: ${UPLOAD_MBPS} Mbps"
+echo_log "Result: ${RESULT}"
+echo_log "Download: ${DOWNLOAD_MBPS} Mbps, Upload: ${UPLOAD_MBPS} Mbps"
 
 if (( $(echo "${DOWNLOAD_MBPS} < ${MIN_DOWNLOAD}" | bc -l) )) || \
    (( $(echo "${UPLOAD_MBPS} < ${MIN_UPLOAD}" | bc -l) )); then
-  echo "${DATE} - ⚠️ Warning: low speed (Download: ${DOWNLOAD_MBPS}, Upload: ${UPLOAD_MBPS})
+  echo_log "⚠️ Warning: low speed (Download: ${DOWNLOAD_MBPS}, Upload: ${UPLOAD_MBPS})
   threshold (Download: ${MIN_DOWNLOAD}, Upload: ${MIN_UPLOAD})"
   if [[ -n "${TELEGRAM_BOT_TOKEN}" && -n "${TELEGRAM_CHAT_ID}" ]]; then
     ALERT_MSG=$(cat <<EOF

version.txt

@@ -1 +1 @@
-1.3.0
+1.4.0