From 206ecde1e86c799d6d05fd4a8db62ad5e9ce7c03 Mon Sep 17 00:00:00 2001
From: Minijackson <minijackson@riseup.net>
Date: Thu, 19 Oct 2023 13:44:18 +0200
Subject: [PATCH] doc/nixos/phoebus-save-and-restore: init guide

---
 doc/_quarto.yml                              |  1 +
 doc/nixos/guides/phoebus-save-and-restore.md | 50 ++++++++++++++++++++
 2 files changed, 51 insertions(+)
 create mode 100644 doc/nixos/guides/phoebus-save-and-restore.md

diff --git a/doc/_quarto.yml b/doc/_quarto.yml
index 90fdee3..b9bd75f 100644
--- a/doc/_quarto.yml
+++ b/doc/_quarto.yml
@@ -76,6 +76,7 @@ website:
           contents:
             - ./nixos/guides/ca-gateway.md
             - ./nixos/guides/phoebus-alarm.md
+            - ./nixos/guides/phoebus-save-and-restore.md
         - section: Explanations
         - section: References
           contents:
diff --git a/doc/nixos/guides/phoebus-save-and-restore.md b/doc/nixos/guides/phoebus-save-and-restore.md
new file mode 100644
index 0000000..49609f3
--- /dev/null
+++ b/doc/nixos/guides/phoebus-save-and-restore.md
@@ -0,0 +1,50 @@
+---
+title: Phoebus Save-and-restore setup
+---
+
+The Phoebus Save-and-restore service is used by clients
+to manage configuration and snapshots of PV values.
+These snapshots can then be used by clients for comparison or for restoring PVs.
+
+This guide focuses on installing and configuring the Save-and-Restore service on a single server.
+
+For more details and documentation about Phoebus Save-and-Restore,
+you can examine the [Save-and-restore official documentation].
+
+  [Save-and-restore official documentation]: https://control-system-studio.readthedocs.io/en/latest/services/save-and-restore/doc/index.html
+
+<!-- TODO: {{< include _pre-requisites.md >}} -->
+
+# Enabling the Phoebus Save-and-restore service
+
+To enable the Phoebus Save-and-restore service,
+add this to your configuration:
+
+``` nix
+{lib, ...}: {
+  services.phoebus-save-and-restore = {
+    enable = true;
+    openFirewall = true;
+  };
+
+  # Elasticsearch, needed by Phoebus Save-and-restore, 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
+# Replace the IP address with your server's IP address or domain name
+org.phoebus.applications.saveandrestore/jmasar.service.url=http://192.168.1.42:8080
+```
+
+::: callout-warning
+URLs for future versions of Phoebus Save-and-restore will need to change to:
+`http://192.168.1.42:8080/save-restore`
+:::