Add participation key expiration notification service (#20)

Author: hsoerensen

.gitignore

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

README.md

@@ -61,6 +61,42 @@ 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).
+
 ## Setting a Custom Telemetry Name
 
 To set a custom telemetry name, set the VOINETWORK_TELEMETRY_NAME environment variable to your desired name:
@@ -197,9 +233,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