Restructuring Documentation

[luc-ass]

Hey @oliveratgithub, I've restructured the documentation. Mind having a look at it? I like the way you started the part about custom templates. Perhaps we could add an example that's more complex or change the template.js to contain some lines that are just commented out...?

Just some ideas...

[oliveratgithub]

Hi @luc-ass,
I like the soft-update / restructuring of the documentation, also feels quite comprehensive and easy to adapt from my point of view (as I said before: less but precise = is more 😊).

In general I had some thoughts on the Messages customizations. My personal "pain point" with it's current state is, that I need to have a dedicated template.js file & then bind and overwrite it in the Docker container. This gives me a dependency and a slightly increased complexity, in regards to making my Docker solution better portable.

So I think this could as well be achieved using the environment: settings, instead (or in addition, to keep it backwards-compatible). Sounds like here now is a good place to drop in that idea ^^

Here's an outline:

Customizable Notification Messages using environment variables

Example:

services:
  notifier:
    image: lorcas/docker-telegram-notifier:latest
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      # (Current / Backwards-compatibility only) Bind customized file to /templates/* in the container:
      # → make this obsolete: ./my-template.js:/usr/src/app/templates.js:ro
    environment:
      # (Proposal) new way to customize messages
      CONNECTION_MESSAGE: "Connected to docker v${version} on ${hostname}\nOS: ${type}/${architecture} (${os}), ${cpu} CPU, ${memory} RAM"
      CONTAINER_START: "▶️ <b>${name}</b> started\n${image}"
      NORMAL_EXIT: "⏹️ <b>${name}</b> stopped!\n${image}\n${exitCodeMessage}"
      NONNORMAL_EXIT: "⚠️ <b>${name}</b> stopped!\n${image}\n${exitCodeMessage}"
      EXIT_CODE_0: "Successful shutdown: Exit code 0"
      # …etc.

Explanation

• Basically every message can be customized using an ENV var
• These message ENV vars should support dynamic insertions like currently, this may require nodejs to search-replace?
• It would omit the requirement of modifying a full template.js file → and binding this file to the container
• Then nodejs this way could be scalable, to handle a) more messaging options, and b) formattings that take away responsibility by maintainers:
  • Theoretically using a new ENV var like MESSAGE_FORMAT: "markdown" could add support besides (default) html format for Telegram Bot Api's MarkdownV2
  • Also all formatting could be done by nodejs, maybe even line-break (making the use of manual \n by the maintainer no longer necessary).

Remarks

• It does require some refactoring & changing how the current templates.js is used - most likely it would make sense using a new message_parser.js or so, which…
  • 1st tries to load the template.js (for backwards-compatibility) & uses these message strings,
  • 2nd tries to use the new environment: variables,
  • 3rd if none of 1 or 2 exist: use defaults ( as now in default templates )

Sooo ultimately I was asking myself: would it be worth to support something like this / what are the added benefits that currently don't exist? Or is the current solution already flexible enough & should even keep this flexibility (it does allow a LOT of customization, one just has to use nodejs code; but I think that's not a big deal).

Looking forward to your thoughts on this.

Cheers

---

P.s. the current README: there's one small mistake in one of the code examples I added, that I fixed locally but forgot to update the Pull request:

docker-telegram-notifier/README.md

Line 259 in 5c760ab

(${e.Actor.Attributes['mycustom.telegram.container-info']} ? `NOTE: ${e.Actor.Attributes['mycustom.telegram.container-info']}` : '')

→ for the if-condition the variable reference shouldn't be interpolated with ${e.Actor.Attributes['mycustom.telegram.container-info']} ? … but simply ( e.Actor.Attributes['mycustom.telegram.container-info'] ? …

[luc-ass]

Thank you so much for your input! I am very much on the fence about which way to pursue. I am afraid of making this project so complex, that getting started becomes too complex.

My main points are:

• a template.js is easier to understand/read for people just getting started
• the environment: option is super flexible and makes this container even easier to deploy from compose files etc.

Having both ways seems feasible to me, the only thing that would be needed is a clear way to structure the environment tags, so that they can be parsed easily. What do you think about:

[...]
environment:
  MSG_START_NOTIFIER:
  MSG_START_CONTAINER:
  MSG_STOP_CONTAINER_NORMAL:
  MSG_STOP_CONTAINER_NONNORMAL:
  MSG_STOP_CONTAINER_CODE_0:

This would allow for custom error codes, if needed.

In any case both way should be structured and documented extremely well.

[oliveratgithub]

Yeah, having a clear naming convention does definitely help 👍

Some more thoughts:

Consider that you will always need a fallback in case not all and every message type is defined - and hence missing definitions should use a default.

And ENV vars are somewhat flexible and reusable in combination with a custom docker-compose .env:

MY_TELEGRAM_MESSAGE="Container ${image} is "
SERVICE_START_MESSAGE="${MY_TELEGRAM_MESSAGE} started"
SERVICE_STOP_MESSAGE= "${MY_TELEGRAM_MESSAGE} stopped"
MY_ERROR_CODE_A=23
MY_ERROR_CODE_B=5
# ...

And even in the docker-compose service config it allows some dynamics (aka interpolated variables):

[...]
environment:
  MSG_START_NOTIFIER: "${MY_CONNECT_MESSAGE:-}"
  MSG_START_CONTAINER: "${SERVICE_START_MESSAGE:-Service ${image} started}"
  MSG_STOP_CONTAINER_NORMAL: "${SERVICE_STOP_MESSAGE:-Container ${image} exited}"
  MSG_STOP_CONTAINER_NONNORMAL:
  MSG_STOP_CONTAINER_CODE_0: "${MY_TELEGRAM_ERRORMESSAGE:-}"
  NORMAL_EXIT_CODES: "0, 200${MY_ERROR_CODE_A:+, ${MY_ERROR_CODE_A}}"
  NONNORMAL_EXIT_CODES: "1, 2, 5, 128,${MY_ERROR_CODE_B:+, ${MY_ERROR_CODE_B}}"

Another point then would be: how can a certain message be disabled? Ideally I think it it is set / defined but empty (""), would make the notifier to "omit" it (= do not send it).

[luc-ass]

An update, since this has been open a while.

The documentation part of this issue is done. The examples in sections 3.2.1 to 3.2.3 had four separate errors — including the interpolated if condition you spotted, an Attirbutes typo, a <code> tag closed with <code>, and Attributes.container, which does not exist on container events at all, so that example printed undefined. The variable table is now taken from a real captured event and states the thing that was never written down: every label on the container is reachable the same way, which is what makes custom container information work.

On the ENV template proposal: holding it for now rather than closing it. v1.5.0 has just gone out with a fair amount of change — reconnect handling, rate limiting, HTML escaping, configuration validation — and the customization documentation has only just been corrected. Adding a second way to configure messages on top of that seems likely to confuse rather than help, and your own concern about complexity is the one I keep coming back to.

If the idea does get built, the shape you outlined is the right one: MSG_-prefixed variables with a narrow placeholder renderer for ${name}, ${image} and ${exitCode} — no eval, no template literals evaluated from the environment — with the order being environment, then a mounted templates.js, then the defaults.

Leaving this open as the record of that.