favonia / cloudflare-ddns

🌟 A small, feature-rich, and robust Cloudflare DDNS updater
Apache License 2.0
924 stars 41 forks source link

Improve the README structure #983

Open NotaInutilis opened 1 week ago

NotaInutilis commented 1 week ago

Hi! I've got an issue with passing the cloudflare API token via a secret on docker compose file. It works when pasting it as an environment variable but outputs an error 😞 Failed to check the existence of a zone named DOMAIN: Invalid request headers (6003) when using a secret. I first asked for help on the formatting of my compose file, but it doesn't seem that there is any issue with it so instead of bashing my head on my keyboard, I'm asking for some help here.

services:
  cloudflare-ddns:
    container_name: cloudflare-ddns
    image: favonia/cloudflare-ddns
    restart: always
    user: ${USER}
    read_only: true
    cap_drop: [all]
    security_opt: [no-new-privileges:true]
    environment:
      - CLOUDFLARE_API_TOKEN=/run/secrets/CLOUDFLARE_API_TOKEN
      - DOMAINS=DOMAIN
      - PROXIED=false
    secrets:
      - CLOUDFLARE_API_TOKEN

secrets:
  CLOUDFLARE_API_TOKEN:
    file: ./secrets/CLOUDFLARE_API_TOKEN.txt
favonia commented 1 week ago

Hi! Thanks for opening the issue. The environment variable name for secrets should be CLOUDFLARE_API_TOKEN_FILE instead of CLOUDFLARE_API_TOKEN. Do you think there's something we can change in README to clarify this?

NotaInutilis commented 1 week ago

Aaah! It was thar simple, thank you!

I think there are several things that ca be done with the readme.

  1. While I understand why you chose to expand each section (this readme is LONG), it disables search with ctrl+f in the folded sections. I also believe thar just browsing the full extended page, that info would have caught my eye. Tables are easy to recognize and are always used to give configuration info in readmes.
  2. The Compose File section and the All Settings are separated by two other sections (Building and Running, FAQ). I think grouping all the relevant information together would make more sense. I was searching for info around the compose file, not further away in the document.
  3. Adding some keywords like "txt file" and "secrets file" around the API token section of the compose file so that the user knows there are other options they can look for.

I'd say the same for the Proxied option: it looks like a simple binary choice when the more useful info is also hidden.

favonia commented 1 week ago

@NotaInutilis You are not the only one tripping over the expandable descriptions. I now think I should remove all of the folding.