Add participation key expiration notification service (#20)

Author: hsoerensen

.gitignore

@@ -0,0 +1,3 @@
+./.idea/**/*
+
+/docker-swarm/notification.yml

README.md

@@ -50,7 +50,7 @@ export VOINETWORK_SKIP_WALLET_SETUP=1
 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/VoiNetwork/docker-swarm/main/install.sh)"
 ```
 
-## Updating Participation Key
+## Updating Your Participation Key
 
 If your Voi node's participation key is nearing its expiry date (less than 14 days left), you can renew it by running
 the installation script again. This script is programmed to create new participation keys when the current ones are
@@ -61,6 +61,50 @@ expire, rerun the installation script to generate a new key.
 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/VoiNetwork/docker-swarm/main/install.sh)"
 ```
 
+## Setting up Participation Key Expiry Notifications (Recommended)
+
+Each online account has a participation key that needs to be valid for the account to participate in the Voi network.
+A participation key is valid for a certain number of rounds, which is approximately 14 days. When the participation key
+expires the node runner will no longer be able to propose or vote on blocks. To avoid this situation you need to renew
+the participation key before expiration.
+
+To receive a notification when the participation key is about to expire, you can do the following:
+
+### Copy the example file
+
+Start by copying the example notification.yml file to the voi/docker-swarm directory:
+
+`cp ~/voi/docker-swarm/notification.yml.example ~/voi/docker-swarm/notification.yml`
+
+### Update the notification.yml file
+
+Update the notification.yml file with your preferred notification mechanism by updating the NOTIFICATION_URLS
+environment variable. The notification mechanism can be a webhook, email, push, or any other notification mechanism that
+is available via [Apprise notifications](https://github.com/caronc/apprise?tab=readme-ov-file#supported-notifications)
+
+If you want to use multiple mechanisms, separate them with a comma. For example, to use both Discord and Pushbullet for
+notification, you would set the `NOTIFICATION_URLS` value in the `notification.yml` file  to:
+
+```yaml
+NOTIFICATION_URLS="discord://<webhook_id>/<webhook_token>,pushbullet://<access_token>"
+```
+
+### Updating notification schedule
+
+To modify the notification schedule, adjust the `- swarm.cronjob.schedule=0 16 * * *` label in the copied example file.
+This is by default set to run daily at 4 PM UTC. Adjust this to your preferred time, accounting for your
+timezone's UTC offset. Use a resource like [dateful.com](https://dateful.com/time-zone-converter) for timezone conversion.
+
+The format of the schedule is following the standard [cronjob format](https://en.wikipedia.org/wiki/Cron#Overview).
+
+### Applying notification configuration to the stack
+
+To apply your notification configuration to the stack, rerun the installation script:
+
+```bash
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/VoiNetwork/docker-swarm/main/install.sh)"
+```
+
 ## Setting a Custom Telemetry Name
 
 To set a custom telemetry name, set the VOINETWORK_TELEMETRY_NAME environment variable to your desired name:
@@ -197,9 +241,3 @@ The `get-node-status` command performs checks using:
 ### Inspect service
 
 `docker inspect voinetwork_algod`
-
-## TODO
-
-- [ ] Add apprise / alarming on scaling events in docker-compose.yml
-- [ ] Add script for participation key management
-- [ ] Add mechanism for a user to specify notification mechanism for key expiration

docker-swarm/compose.yml

@@ -1,23 +1,25 @@
 version: "3.8"
 services:
   algod:
-    build: ..
     image: ghcr.io/voinetwork/docker-participation-node:latest
-    volumes:
-      - /var/lib/voi/algod/data:/algod/data/:rw
     environment:
       TELEMETRY_NAME: ${VOINETWORK_TELEMETRY_NAME}
     logging:
       driver: "local"
+    volumes:
+      - /var/lib/voi/algod/data:/algod/data/:rw
     deploy:
       replicas: 1
       restart_policy:
         condition: on-failure
+    networks:
+      - notification
   shepherd:
-    build: ..
     image: containrrr/shepherd
     environment:
       RUN_ONCE_AND_EXIT: "true"
+      ROLLBACK_ON_FAILURE: "true"
+      IMAGE_AUTOCLEAN_LIMIT: "5"
     logging:
       driver: "local"
     volumes:
@@ -28,22 +30,25 @@ services:
         condition: none
       labels:
         - swarm.cronjob.enable=true
-        - swarm.cronjob.schedule=0 0 * * *
+        - swarm.cronjob.schedule=0 16 * * *
         - swarm.cronjob.skip-running=true
       placement:
         constraints:
           - node.role == manager
   scheduler:
-    image: crazymax/swarm-cronjob:latest
+    image: ghcr.io/voinetwork/swarm-cronjob:edge
     logging:
       driver: "local"
-    volumes:
-      - /var/run/docker.sock:/var/run/docker.sock:ro
     environment:
-      - "TZ=Europe/London"
+      - "TZ=UTC"
       - "LOG_LEVEL=info"
       - "LOG_JSON=false"
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock:ro
     deploy:
       placement:
         constraints:
           - node.role == manager
+
+networks:
+  notification:

docker-swarm/notification.yml.example

@@ -0,0 +1,29 @@
+version: "3.8"
+services:
+  notify:
+    image: mazzolino/apprise-microservice:0.2
+    environment:
+      ## Reference https://github.com/caronc/apprise?tab=readme-ov-file#productivity-based-notifications supported formats and setup
+      NOTIFICATION_URLS: discord://.....,slack://.....,pbul://
+    logging:
+      driver: "local"
+    networks:
+      - notification
+  partkey_checker:
+    image: ghcr.io/voinetwork/docker-swarm-partkey-monitoring:edge
+    logging:
+      driver: "local"
+    volumes:
+      - /var/lib/voi/algod/data/voitest-v1/:/voi/:rw
+    networks:
+      - notification
+    depends_on:
+      - notify
+    deploy:
+      replicas: 0
+      restart_policy:
+        condition: none
+      labels:
+        - swarm.cronjob.enable=true
+        - swarm.cronjob.skip-running=true
+        - swarm.cronjob.schedule=0 16 * * *

install.sh

@@ -83,6 +83,22 @@ start_docker_swarm() {
   fi
 }
 
+start_stack() {
+  command="env VOINETWORK_TELEMETRY_NAME=$VOINETWORK_TELEMETRY_NAME docker stack deploy -c ${voi_home}/docker-swarm/compose.yml"
+
+  if [[ -f "${voi_home}/docker-swarm/notification.yml" ]]; then
+      command+=" -c ${voi_home}/docker-swarm/notification.yml"
+  fi
+
+  command+=" voinetwork"
+  execute_sudo "$command"
+
+  # shellcheck disable=SC2181
+  if [[ $? -ne 0 ]]; then
+    abort "Error starting stack. Exiting the program."
+  fi
+}
+
 wait_for_stack_to_be_ready() {
   while true; do
     service_info=$(execute_sudo 'docker stack ps voinetwork --format json' | grep 'voinetwork_algod')
@@ -563,11 +579,7 @@ curl -L https://api.github.com/repos/VoiNetwork/docker-swarm/tarball/main --outp
 tar -xzf "${voi_home}"/docker-swarm.tar.gz -C "${voi_home}" --strip-components=1
 rm "${voi_home}"/docker-swarm.tar.gz
 
-execute_sudo "env VOINETWORK_TELEMETRY_NAME=$VOINETWORK_TELEMETRY_NAME docker stack deploy -c ${voi_home}/docker-swarm/compose.yml voinetwork"
-# shellcheck disable=SC2181
-if [[ $? -ne 0 ]]; then
-  abort "Error starting stack. Exiting the program."
-fi
+start_stack
 
 wait_for_stack_to_be_ready