From 404d68c8999a3f8cacd220c2bc93fb2439e08512 Mon Sep 17 00:00:00 2001
From: Shizun Ge <shizunge@gmail.com>
Date: Sun, 21 Jan 2024 22:10:35 -0800
Subject: [PATCH] Add readme

---
 Dockerfile                 |  2 +-
 README.md                  | 43 +++++++++++++++++++++++++++++++++++++-
 examples/README.md         |  4 ++--
 examples/blocky-config.yml |  8 +++----
 src/entrypoint.sh          |  2 +-
 5 files changed, 50 insertions(+), 9 deletions(-)

diff --git a/Dockerfile b/Dockerfile
index 6981a8d..ed318f8 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -10,8 +10,8 @@ LABEL org.opencontainers.image.licenses=GPLv3
 RUN mkdir -p /src
 RUN mkdir -p /web
 RUN mkdir -p /web/watch
-RUN mkdir -p /web/sources
 RUN mkdir -p /web/downloaded
+RUN mkdir -p /sources
 
 RUN apk add --update --no-cache curl tzdata inotify-tools bash
 
diff --git a/README.md b/README.md
index d3f6810..4826a8a 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,43 @@
-# blocky-list-downloader
+# blocky lists downloader
 Update lists without restarting [blocky](https://0xerr0r.github.io/blocky/) DNS.
+
+## Introduction
+
+## How it works
+
+## Configurations
+
+You can configure the most behaviors of *lists downloader* via environment variables.
+
+| Environment Variable  | Default |Description |
+|-----------------------|---------|------------|
+| BLD_BLOCKY_URL            |       | Enable [refresh request](https://0xerr0r.github.io/blocky/swagger.html#operation--lists-refresh-post) to blocky. The base URL for *lists downloader* to send refresh requests. Use an empty string to disable refresh requests. |
+| BLD_DESTINATION_FOLDER    | /web/downloaded | The location of aggregated lists. This should be under `BLD_WEB_FOLDER` thus blocky can read the files via the static-web-server. |
+| BLD_INITIAL_DELAY_SECONDS | 0     | Delay in seconds before the first download. |
+| BLD_INTERVAL_SECONDS      | 86400 | Interval between two downloads. Set to 0 to run once then exit. |
+| BLD_LOG_LEVEL             | INFO  | Control how many logs generated by Gantry. Valid values are `NONE`, `ERROR`, `WARN`, `INFO`, `DEBUG` (case sensitive). |
+| BLD_NODE_NAME             |       | Add node name to logs. |
+| BLD_NOTIFICATION_APPRISE_URL |    | Enable notification after each refresh with [apprise](https://github.com/djmaze/apprise-microservice). This must point to the notification endpoint, e.g. `http://apprise:8000/notify`. Use an empty string to disable notification. |
+| BLD_POST_DOWNLOAD_CMD     |       | A command or function running after downloading an aggregated list. The first argument will be the path to the aggregated file, i.e. you command will be eval as `your_command <file_path>`. This can be used to fix problems in the lists before the upstream maintainer fixing it. |
+| BLD_SOURCES_FOLDER | /sources   | The location to read sources lists. |
+| BLD_WATCH_FOLDER   | /web/watch | The location of user defined lists of domains. *lists downloader* watches changes in this folder and send refresh requests to blocky. This should be under `BLD_WEB_FOLDER` thus blocky can read the files via the static-web-server. Use an empty string to disable watching. |
+| BLD_WEB_FOLDER     | /web       | The location which the static-web-server services. Use an empty string to disable the web server. |
+| BLD_WEB_PORT       | 8080       | The port that static-web-server listens to. |
+
+## Caveats
+
+* No web UI
+
+    Blocky lists downloader bases on a set of shell scripts. It does not provide any UI to edit lists. You need an additional service for lists editing.
+
+* No group management
+
+    You still need to modify the blocky configuration file to edit groups.
+
+## Contacts
+
+If you have any problems or questions, please contact me through a [GitHub issue](https://github.com/shizunge/blocky-lists-downloader/issues).
+
+## Related projects
+
+You may also want to check my [blocky Postgresql dashboard](https://github.com/shizunge/blocky-postgresql).
\ No newline at end of file
diff --git a/examples/README.md b/examples/README.md
index a39708f..865523d 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -1,6 +1,6 @@
 # blocky lists downloader example
 
-`docker-compose.yml` demostrates how to configure lists downloader via environment variables, and to share volumes with a web UI for editing.
+`docker-compose.yml` demostrates how to configure *lists downloader* via environment variables, and to share volumes with a web UI for editing.
 
-`blocky-config.yml` demostrates how to define groups for blocky to read lists from the lists downloader.
+`blocky-config.yml` demostrates how to define groups for blocky to read lists from the *lists downloader*.
 
diff --git a/examples/blocky-config.yml b/examples/blocky-config.yml
index abc964f..946c542 100644
--- a/examples/blocky-config.yml
+++ b/examples/blocky-config.yml
@@ -10,9 +10,9 @@ blocking:
       - http://lists-downloader:8080/watch/blocked-list.txt
     default-lists:
       - http://lists-downloader:8080/downloaded/default-lists.txt
-    list-one:
+    group-one:
       - http://lists-downloader:8080/downloaded/list-one.txt
-    list-two:
+    group-two:
       - http://lists-downloader:8080/downloaded/list-two.txt
   whiteLists:
     my-lists:
@@ -22,8 +22,8 @@ blocking:
     default:
       - my-lists
       - default-lists
-      - list-one
-      - list-two
+      - group-one
+      - group-two
   blockType: zeroIp
   blockTTL: 1h
   loading:
diff --git a/src/entrypoint.sh b/src/entrypoint.sh
index 3e0605c..4e21a61 100755
--- a/src/entrypoint.sh
+++ b/src/entrypoint.sh
@@ -186,7 +186,7 @@ main() {
   local DESTINATION_FOLDER="${BLD_DESTINATION_FOLDER:-"/web/downloaded"}"
   local INITIAL_DELAY_SECONDS="${BLD_INITIAL_DELAY_SECONDS:-0}"
   local INTERVAL_SECONDS="${BLD_INTERVAL_SECONDS:-86400}"
-  local SOURCES_FOLDER="${BLD_SOURCES_FOLDER:-"/web/sources"}"
+  local SOURCES_FOLDER="${BLD_SOURCES_FOLDER:-"/sources"}"
   local WATCH_FOLDER="${BLD_WATCH_FOLDER:-"/web/watch"}"
   local WEB_FOLDER="${BLD_WEB_FOLDER:-"/web"}"
   local WEB_PORT="${BLD_WEB_PORT:-8080}"