From 0caf752169eaa7dfb63c681f6b95075c61a2f0f5 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Gon=C3=A7alo=20Val=C3=A9rio?= <gon@ovalerio.net>
Date: Tue, 19 May 2020 23:43:48 +0100
Subject: [PATCH] Add a description to the readme and some instructions

---
 README.md | 71 +++++++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 67 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 8f3bcb7..c5c730d 100644
--- a/README.md
+++ b/README.md
@@ -1,8 +1,71 @@
 # Worker DDNS
 
-Workers as a proxy in a DDNS setup that uses the cloudflare API.
+This repository provides two simple scripts that together will allow you to build a
+simple and efficient DDNS system using Cloudflare workers.
 
-Both scripts, `worker.js` and `agent.py` don't require any extra dependencies,
-so it is very simple to deploy/setup. Just copy the files and you're done.
+**Example use case:** You have a machine where the IP address is dynamically assigned and
+changes frequently.
 
-More detailed documentation will be added soon.
+The `agent.py` should regularly contact a CF worker running the `worker.js` code,
+that will in turn use the cloudflare API to update the DNS record in question
+with the new IP address.
+
+## Why use Workers
+
+Because we don't want to signup to an extra external service, we want to apply
+the principle of the least privilege and the name should belong to a domain we
+control.
+
+Since Cloudflare API Token permissions aren't granular enough to limit the token
+access to a single DNS record, we place a worker in front of it.
+
+## Usage
+
+Both scripts (`worker.js` and `agent.py`) don't require any extra dependencies,
+so they just be copied right out of the repository.
+
+Before starting create a new API Token on your Cloudflare's profile page with
+permissions to edit the DNS records of one of your domains (Zone).
+
+### Worker
+
+The next step is to create a new worker and then set `worker.js` as its content.
+This can be easily done using the "Quick Edit" button on the worker's detail page.
+
+Add the following environment variables on the worker settings tab:
+
+- `CF_API_TOKEN` - The token you just created. You just also click on the
+  "encrypt" button.
+- `SHARED_KEY` - Generate a long and random string and put it here. Click encrypt.
+- `DNS_RECORD` - the DNS record that should be updated. Something like
+  `<somename>.<your-domain>`.
+- `ZONE` - The zone_id of your domain. You can find it on the sidebar of the domain
+  overview page.
+
+Then deploy the worker.
+
+### Agent
+
+Copy the `agent.py` file to the machine you want your subdomain/domain
+"pointed to".
+
+Set the following environment variables:
+
+- `SHARED_KEY` - The same long and random string you generated for the worker.
+- `WORKER_URL` - The URL of your worker.
+
+Then execute the script:
+
+```bash
+$ ./agent.py
+```
+
+In the most common scenario you will want to run it periodically. So you will need to
+use scheduler like `cron` or a `systemd timer unit`. Below is a simple example
+that can be inserted after running `crontab -e`:
+
+```
+SHARED_KEY=<your-generated-key>
+WORKER_URL=<cf-worker-url>
+*/5 * * * *  /path/to/agent.py
+```