Merge pull request #32 from epics-extensions/phoebus-alarm-docs

Phoebus Alarm docs single setup guide
epics-extensions · Oct 27, 2023 · e1c4ae7 · e1c4ae7
2 parents 0e04d46 + f687f17
commit e1c4ae7
Show file tree

Hide file tree

Showing 5 changed files with 289 additions and 13 deletions.
diff --git a/doc/_quarto.yml b/doc/_quarto.yml
@@ -73,6 +73,8 @@ website:
           contents:
             - ./nixos/tutorials/archiver-appliance.md
         - section: User Guides
+          contents:
+            - ./nixos/guides/phoebus-alarm.md
         - section: Explanations
         - section: References
           contents:

diff --git a/doc/_vale/Vocab/EPNix/accept.txt b/doc/_vale/Vocab/EPNix/accept.txt
@@ -1,4 +1,6 @@
 and so on
+alarm
+Alarm
 Archiver Appliance
 colmena
 disnix

diff --git a/doc/nixos/guides/_pre-requisites.md b/doc/nixos/guides/_pre-requisites.md
@@ -0,0 +1,40 @@
+# Pre-requisites
+
+-   Having a NixOS machine with a flake configuration.
+
+If you're not sure how to do this,
+you can follow the [Archiver Appliance tutorial],
+which is a good introduction on how to make a NixOS VM.
+
+If you have such a configuration,
+make sure that:
+
+-   You have the `epnix` flake input
+-   You have added `epnix` as an argument to your flake outputs
+-   You have imported EPNix' NixOS module
+
+For example:
+
+``` {.diff filename="flake.nix"}
+ {
+   # ...
++  inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixos-23.05";
+
+   # ...
+   outputs = {
+     self,
+     nixpkgs,
++    epnix,
+   }: {
+     nixosConfigurations.nixos = nixpkgs.lib.nixosSystem {
+       modules = [
++        epnix.nixosModules.nixos
+
+         # ...
+       ];
+     };
+   };
+ }
+```
+
+  [Archiver Appliance tutorial]: ../tutorials/archiver-appliance.md
diff --git a/doc/nixos/guides/phoebus-alarm.md b/doc/nixos/guides/phoebus-alarm.md
@@ -0,0 +1,175 @@
+---
+title: Phoebus Alarm single server setup
+---
+
+The Phoebus Alarm collection of services enables monitoring EPICS PVs,
+and report alarms in a server.
+Phoebus clients can then contact this server,
+to see a list of current alarms, earlier alarms, and so on.
+
+This guide focuses on installing and configuring these services on a single server.
+
+For more information about these services,
+examine the official documentation:
+
+-   [Service Architecture]
+-   [Alarm Server]
+-   [the README of Alarm Server] for reference only, don't follow this guide on NixOS
+-   [Alarm Logging Service]
+
+The Phoebus Alarm Logging Service can also be called the Phoebus Alarm Logger.
+
+  [Service Architecture]: https://control-system-studio.readthedocs.io/en/latest/services_architecture.html
+  [Alarm Server]: https://control-system-studio.readthedocs.io/en/latest/services/alarm-server/doc/index.html
+  [the README of Alarm Server]: https://github.com/ControlSystemStudio/phoebus/blob/master/app/alarm/Readme.md
+  [Alarm Logging Service]: https://control-system-studio.readthedocs.io/en/latest/services/alarm-logger/doc/index.html
+
+{{< include _pre-requisites.md >}}
+
+# Enabling the Phoebus Alarm services
+
+To enable the Phoebus Alarm server and the Phoebus Alarm Logger,
+add this to your configuration:
+
+``` nix
+{config, lib, ...}: let
+  kafkaPort = toString config.services.apache-kafka.port;
+  # Replace this with your machine's IP address
+  # or DNS domain name
+  ip = "192.168.1.42";
+  kafkaSock = "${ip}:${kafkaPort}";
+in {
+  # The Phoebus Alarm server also automatically enables the Phoebus Alarm Logger
+  services.phoebus-alarm = {
+    enable = true;
+    openFirewall = true;
+    settings."org.phoebus.applications.alarm/server" = "${kafkaSock}";
+  };
+
+  # Tell Apache Kafka to listen on this IP address
+  # If you don't have a DNS domain name, it's best to set a specific, non-local IP address.
+  services.apache-kafka.extraProperties = ''
+    listeners=PLAINTEXT://${kafkaSock}
+  '';
+
+  # Elasticsearch, needed by Phoebus Alarm Logger, is not free software (SSPL | Elastic License).
+  # To accept the license, add the code below:
+  nixpkgs.config.allowUnfreePredicate = pkg:
+    builtins.elem (lib.getName pkg) [
+      "elasticsearch"
+    ];
+}
+```
+
+From the Phoebus graphical client side,
+add this configuration:
+
+``` ini
+# For the Phoebus Alarm Server:
+# Replace the IP address with your server's IP address or DNS domain name
+org.phoebus.applications.alarm/server=192.168.1.42:9092
+
+# For the Phoebus Alarm Logger:
+# Replace the IP address again
+org.phoebus.applications.alarm.logging.ui/service_uri=http://192.168.1.42:8080
+```
+
+# Configuring topics
+
+The Phoebus Alarm system uses "topics" as a way of grouping alarms.
+These topics are the available roots of your alarm tree.
+You need to synchronize the topic names between:
+
+-   Phoebus Alarm Server
+-   Phoebus Alarm Logger
+-   Phoebus graphical clients
+
+Changing the topic names in the Phoebus Alarm Server NixOS modules automatically creates them.
+
+::: callout-warning
+Currently, the Phoebus Alarm Server doesn't support several topics.
+:::
+
+For example,
+if you want to have the topic `Project`,
+add this configuration to the server:
+
+``` nix
+{config, lib, ...}: let
+  topics = ["Project"];
+in {
+  services.phoebus-alarm-server = {
+    # ...
+    settings = {
+      # ...
+      "org.phoebus.applications.alarm/config_names" = topics;
+    };
+  };
+
+  services.phoebus-alarm-logger.settings.alarm_topics = topics;
+}
+```
+
+For the Phoebus graphical client,
+add this configuration:
+
+``` ini
+# config_name is only used in the Phoebus graphical client
+org.phoebus.applications.alarm/config_name = Project
+org.phoebus.applications.alarm/config_names = Project
+```
+
+# Configuring the address list
+
+If you want to limit the IOCs reachable by the Phoebus Alarm Server,
+use these option:
+
+``` nix
+{
+  services.phoebus-alarm-server = {
+    # ...
+    settings = {
+      # ...
+
+      # The Phoebus Alarm Server will only have access to these IOCs
+      "org.phoebus.pv.ca/addr_list" = ["192.168.1.5" "192.168.1.42"];
+      "org.phoebus.pv.ca/auto_addr_list" = false;
+    };
+  };
+}
+```
+
+# Configuring email support
+
+To enable email support,
+set the `org.phoebus.email/mailport` setting.
+Here is a list of options you might want to set:
+
+``` nix
+{
+  services.phoebus-alarm-server = {
+    # ...
+    settings = {
+      # ...
+
+      "org.phoebus.email/mailhost" = "smtp.my-company.org";
+
+      # Optional:
+
+      # 25 for plain SMTP
+      "org.phoebus.email/mailport" = 25;
+      # If authentication is needed:
+      "org.phoebus.email/username" = "user";
+      "org.phoebus.email/password" = "password";
+      # Default address to be used for From:
+      # if unspecified, then the last used "from" address is used
+      "org.phoebus.email/from" = "Sender <[email protected]>";
+    };
+  };
+}
+```
+
+::: callout-warning
+Currently, Phoebus Alarm Server only supports plain SMTP.
+:::
+
diff --git a/nixos/modules/phoebus/alarm-server.nix b/nixos/modules/phoebus/alarm-server.nix
@@ -76,17 +76,18 @@ in {
             defaultText = lib.literalExpression ''"localhost:''${toString config.services.apache-kafka.port}"'';
           };
 
-          "org.phoebus.applications.alarm/config_name" = lib.mkOption {
-            description = ''
-              Name of alarm tree root.
-
-              Will be used as the name for the Kafka topic.
-            '';
-            type = lib.types.str;
-            # TODO: bug? From the code it seems that specifying multiple topics
-            # here with create_topics will have issues (AlarmServerMain.java:654)
-            default = "Accelerator";
-          };
+          # Waiting for: https://github.com/ControlSystemStudio/phoebus/issues/2843
+          #
+          #"org.phoebus.applications.alarm/config_name" = lib.mkOption {
+          #  description = ''
+          #    Name of alarm tree root.
+          #    Will be used as the name for the Kafka topic.
+          #  '';
+          #  type = lib.types.str;
+          #  # TODO: bug? From the code it seems that specifying multiple topics
+          #  # here with create_topics will have issues (AlarmServerMain.java:654)
+          #  default = "Accelerator";
+          #};
 
           "org.phoebus.applications.alarm/config_names" = lib.mkOption {
             description = ''
@@ -97,16 +98,72 @@ in {
             type = with lib.types; listOf str;
             # TODO: bug? From the code it seems that specifying multiple topics
             # here with create_topics will have issues (AlarmServerMain.java:654)
-            default = [cfg.settings."org.phoebus.applications.alarm/config_name"];
-            defaultText = lib.literalExpression ''[cfg.settings."org.phoebus.applications.alarm/config_name"]'';
+            default = ["Accelerator"];
             apply = lib.concatStringsSep ",";
           };
+
+          # Email options:
+          # ---
+
+          "org.phoebus.email/mailhost" = lib.mkOption {
+            description = ''
+              The SMTP server host.
+
+              If set to DISABLE (the default), email support is disabled.
+            '';
+            type = lib.types.str;
+            default = "DISABLE";
+          };
+
+          "org.phoebus.email/mailport" = lib.mkOption {
+            description = ''
+              The SMTP server port.
+            '';
+            type = lib.types.port;
+            default = 25;
+            apply = toString;
+          };
+
+          "org.phoebus.email/username" = lib.mkOption {
+            description = ''
+              Username for authenticating to the SMTP server.
+            '';
+            type = lib.types.str;
+            default = "";
+          };
+
+          "org.phoebus.email/password" = lib.mkOption {
+            description = ''
+              Password for authenticating to the SMTP server.
+
+              Note: the password will be put in plaintext, in the world-readable `/nix/store`.
+            '';
+            type = lib.types.str;
+            default = "";
+          };
+
+          "org.phoebus.email/from" = lib.mkOption {
+            description = ''
+              Default address to be used for the email field `From:`.
+
+              If left empty, then the last used from address is used.
+            '';
+            type = lib.types.str;
+            default = "";
+          };
         };
       };
     };
   };
 
   config = lib.mkIf cfg.enable {
+    assertions = [
+      {
+        assertion = !(lib.hasInfix "," cfg.settings."org.phoebus.applications.alarm/config_names");
+        message = "Phoebus Alarm Server doesn't support multiple topics, yet";
+      }
+    ];
+
     systemd.services.phoebus-alarm-server = {
       description = "Phoebus Alarm Server";