diff --git a/README.md b/README.md index cf270ca..385c348 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Cloudflare DDNS Updater -Cloudflare DDNS Updater keeps Cloudflare DNS records pointed at the machine's current public IPv4 and/or IPv6 address. +Keeps Cloudflare DNS records pointed at the machine's current public IPv4 and/or IPv6 address. The container reads: @@ -15,14 +15,12 @@ Pull the published image: docker pull ghcr.io/yuzuzensai/cloudflare-ddns-updater:latest ``` -Create `.env` from the example: +Create `.env` from the example and set your Cloudflare API token: ```sh cp .env.example .env ``` -Edit `.env` and set your Cloudflare API token: - ```env NODE_ENV=production EXAMPLE_SITE_TOKEN=replace-with-cloudflare-api-token @@ -88,8 +86,6 @@ services: - ./configs:/home/node/app/configs ``` -Start it with: - ```sh docker compose up -d ``` @@ -98,127 +94,52 @@ docker compose up -d `configs/UpdaterConfig.json` is an array of Cloudflare account/token configurations. -Each top-level object uses these fields: +Each top-level object: -- `token`: Cloudflare API token, or an environment reference like `{ENV_TOKEN:EXAMPLE_SITE_TOKEN}`. -- `updateInterval`: update interval in seconds. -- `zone`: DNS records to manage. +| Field | Description | +| ---------------- | --------------------------------------------------------------------------------------- | +| `token` | Cloudflare API token, or an environment reference like `{ENV_TOKEN:EXAMPLE_SITE_TOKEN}` | +| `updateInterval` | Update interval in seconds | +| `zone` | DNS records to manage | -Each `zone` entry uses these fields: +Each `zone` entry: -- `id`: Cloudflare zone ID. -- `type`: DNS record type, usually `A` or `AAAA`. -- `name`: DNS record name, for example `example.com` or `home.example.com`. -- `content`: `{CURRENT_IPv4}` for an `A` record or `{CURRENT_IPv6}` for an `AAAA` record. -- `ttl`: Cloudflare TTL. Use `1` for automatic TTL. -- `proxied`: Cloudflare proxy status, `true` or `false`. +| Field | Description | +| --------- | ------------------------------------------------------------------------- | +| `id` | Cloudflare zone ID | +| `type` | DNS record type, usually `A` or `AAAA` | +| `name` | DNS record name, e.g. `example.com` or `home.example.com` | +| `content` | `{CURRENT_IPv4}` for an `A` record, `{CURRENT_IPv6}` for an `AAAA` record | +| `ttl` | Cloudflare TTL. Use `1` for automatic | +| `proxied` | Cloudflare proxy status, `true` or `false` | -Important: keep the JSON property order shown in the examples. The current config validator expects exact key order. +## Cloudflare Zone ID and API Token -## Cloudflare Zone ID And Token +**Zone ID** — In the [Cloudflare dashboard](https://dash.cloudflare.com/), select the domain, open its overview page, and copy `Zone ID` from the `API` section of the right sidebar into `zone[].id`. -You need two Cloudflare values before running the updater: +**API token** — In the dashboard, go to your profile icon → `My Profile` → `API Tokens` → `Create Token`. Use the built-in `Edit zone DNS` template (recommended) or a custom token with `Zone > DNS > Edit` and `Zone > Zone > Read` permissions. Either way, scope `Zone Resources` to `Include` → `Specific zone` → your domain, then create and copy the token — Cloudflare only shows it once. Don't use your Global API Key; the updater only needs a scoped token for the zones it manages. -- Zone ID: identifies the Cloudflare zone/domain that contains the DNS records. -- API token: authorizes the updater to read and edit DNS records in that zone. - -The Zone ID goes in `configs/UpdaterConfig.json` as `zone[].id`. - -The API token should go in `.env`, then `configs/UpdaterConfig.json` references it with `{ENV_TOKEN:VARIABLE_NAME}`. The variable name is up to you. `EXAMPLE_SITE_TOKEN`, `HOME_SITE_TOKEN`, `MY_DOMAIN_TOKEN`, or any other valid environment variable name will work as long as both files use the same name. - -### Get Your Zone ID - -1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/). -2. Select the domain you want to update. -3. Open the domain overview page. -4. Find `Zone ID` in the right sidebar under `API`. -5. Copy that value into each matching `zone[].id` field in `configs/UpdaterConfig.json`. - -Example: - -```json -{ - "id": "023e105f4ecef8ad9ca31a8372d0c353", - "type": "A", - "name": "home.example.com", - "content": "{CURRENT_IPv4}", - "ttl": 1, - "proxied": false -} -``` - -### Create an API Token - -1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/). -2. Click your profile icon in the top-right corner. -3. Open `My Profile`. -4. Open `API Tokens`. -5. Select `Create Token`. - -The easiest option is the built-in template: - -1. Find the `Edit zone DNS` template. -2. Select `Use template`. -3. Under `Zone Resources`, select `Include` > `Specific zone` > your domain. -4. Leave the permissions as DNS edit/read permissions. -5. Select `Continue to summary`. -6. Review the token summary. -7. Select `Create Token`. -8. Copy the token immediately. Cloudflare only shows it once. - -If you create a custom token instead, use this setup: - -1. Select `Create Custom Token`. -2. Give it a clear name, for example `Cloudflare DDNS Updater`. -3. Add these permissions: - -- `Zone` > `DNS` > `Edit` -- `Zone` > `Zone` > `Read` - -Set the zone resource scope: - -1. Under `Zone Resources`, choose `Include`. -2. Choose `Specific zone`. -3. Select the domain this updater will manage. -4. Select `Continue to summary`. -5. Review the token summary. -6. Select `Create Token`. -7. Copy the token immediately. Cloudflare only shows it once. - -Do not use your Global API Key. This app only needs a scoped API token with DNS access for the selected zone. - -After creating the token, copy it into `.env`. The name before `=` is the environment variable name. You can change it. +Put the token in `.env` under any variable name you like, then reference that same name from `UpdaterConfig.json`: ```env -EXAMPLE_SITE_TOKEN=your-cloudflare-api-token -``` - -If you change the variable name in `.env`, update the `token` value in `configs/UpdaterConfig.json` to match it exactly. - -Example: - -```env -HOME_SITE_TOKEN=your-token +HOME_SITE_TOKEN=your-cloudflare-api-token ``` ```json "token": "{ENV_TOKEN:HOME_SITE_TOKEN}" ``` -Another example with a different name: +Avoid writing the literal token directly into `UpdaterConfig.json` — `{ENV_TOKEN:...}` keeps the secret in `.env`, which is gitignored. -```env -MY_DOMAIN_TOKEN=your-token +## Development + +```sh +bun install +bun run dev # run with --watch +bun run check # typecheck + format + lint + test ``` -```json -"token": "{ENV_TOKEN:MY_DOMAIN_TOKEN}" -``` - -Do not include the literal token in `UpdaterConfig.json` unless you intentionally want the secret stored there. Using `{ENV_TOKEN:...}` keeps the token in `.env`, which is ignored by git. - ## Notes -- The updater fetches IPv4 from `https://api.ipify.org?format=json`. -- The updater fetches IPv6 from `https://api64.ipify.org/?format=json`. -- If `configs/UpdaterConfig.json` is missing, the app creates one from the bundled example, but you must edit it before real use. +- IPv4 is looked up via `https://api.ipify.org?format=json`, IPv6 via `https://api64.ipify.org/?format=json`. +- If `configs/UpdaterConfig.json` is missing, the app creates one from the bundled example — edit it before real use.