diff --git a/.editorconfig b/.editorconfig
index 750bddeb..1a74260d 100644
--- a/.editorconfig
+++ b/.editorconfig
@@ -14,6 +14,9 @@ insert_final_newline = unset
indent_style = space
indent_size = 2
+[*.md]
+indent_style = space
+
[*.py]
indent_style = space
indent_size = 4
diff --git a/.vale.ini b/.vale.ini
index 283850b8..fcd2acef 100644
--- a/.vale.ini
+++ b/.vale.ini
@@ -4,7 +4,7 @@ MinAlertLevel = suggestion
Vocab = EPNix
# External packages
-Packages = alex, Google, Microsoft, proselint, Readability, RedHat, write-good
+Packages = alex, Google, Microsoft, proselint, RedHat, write-good
# Only Markdown and .txt files; change to whatever you're using.
[*.md]
# List of styles to load.
@@ -20,7 +20,30 @@ RedHat.Contractions = NO
# Already done by Microsoft.We
Google.We = NO
-# ??? corresponds to 7th grade -> 12-13 years old
-Readability.AutomatedReadability = YES
+# Already done by Vale.Spelling
+RedHat.Spelling = NO
+
+# Already done by RedHat.PassiveVoice
+Google.Passive = NO
+Microsoft.Passive = NO
+write-good.Passive = NO
+
+# Already done by RedHat.Definitions
+Microsoft.Acronyms = NO
+Google.Acronyms = NO
+
+# Already done by RedHat.Headings
+Google.Headings = NO
+Microsoft.Headings = NO
+
+# Already done by Microsoft.SentenceLength, which is shorter
+RedHat.SentenceLength = NO
+
+# Already done by RedHat.Ellipses
+Google.Ellipses = NO
+Microsoft.Ellipses = NO
+
+# Already done by Microsoft.Quotes
+Google.Quotes = NO
write-good.E-Prime = NO
diff --git a/doc/_quarto.yml b/doc/_quarto.yml
index 60082153..fb69e66a 100644
--- a/doc/_quarto.yml
+++ b/doc/_quarto.yml
@@ -70,6 +70,8 @@ website:
- title: NixOS
file: ./nixos/introduction.md
- section: Tutorials
+ contents:
+ - ./nixos/tutorials/archiver-appliance.md
- section: User Guides
- section: Explanations
- section: References
diff --git a/doc/nixos/tutorials/archiver-appliance.md b/doc/nixos/tutorials/archiver-appliance.md
new file mode 100644
index 00000000..13e01ed8
--- /dev/null
+++ b/doc/nixos/tutorials/archiver-appliance.md
@@ -0,0 +1,363 @@
+---
+title: Creating an Archiver Appliance instance
+---
+
+In this tutorial,
+we're going to see how to create a virtual machine that runs Archiver Appliance,
+under the NixOS Linux distribution.
+
+Installing Archiver Appliance on a physical machine is definitely possible,
+but this tutorial focuses on virtual machines for simplicity's sake.
+
+You will need:
+
+- A virtual machine,
+- and the [NixOS ISO file].
+ Select the "Graphical ISO image."
+
+ [NixOS ISO file]: https://nixos.org/download#download-nixos
+
+# Installing NixOS
+
+First things first,
+create your virtual machine,
+and select the ISO image that you downloaded.
+
+Then, start the virtual machine.
+
+From the booted virtual machine,
+you can follow the graphical installation process,
+and reboot once finished.
+
+You can select any desktop environment,
+or no desktop.
+This tutorial only uses the command-line.
+
+# Making your configuration a flake
+
+The installation process created the `/etc/nixos` directory in your VM.
+This directory describes the complete configuration of your machine.
+
+EPNix is a "Nix flake",
+which a way of managing Nix projects.
+Using Nix flakes also enables you to use Nix code outside of your repository,
+in a controlled manner.
+For more information,
+see the [Nix flake command manual] and the [Flake wiki page].
+
+To be able to import EPNix into you NixOS configuration,
+you first need to turn your NixOS configuration into a Nix flake.
+
+As root, place yourself in the `/etc/nixos` directory in your virtual machine.
+Create a `flake.nix` file under it,
+by running `nano flake.nix`.
+Fill the file with these lines:
+
+``` {.nix filename="flake.nix" code-line-numbers="true"}
+{
+ description = "Configuration for running Archiver Appliance in a VM";
+
+ inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixos-23.05";
+ inputs.epnix.url = "github:epics-extensions/EPNix";
+
+ outputs = { self, nixpkgs, epnix }: {
+ nixosConfigurations.nixos = nixpkgs.lib.nixosSystem {
+ modules = [
+ epnix.nixosModules.nixos
+
+ ./configuration.nix
+ ];
+ };
+ };
+}
+```
+
+```{=html}
+
+
+```
+Save and quit by typing ``{=html}Ctrl-x``{=html}, ``{=html}y``{=html}, and ``{=html}Enter``{=html},
+and run `nixos-rebuild test` to test your changes.
+
+Some explanations:
+
+You can see in the `flake.nix` file that the flake has 2 inputs:
+`nixpkgs` and `epnix`,
+lines 4--5.
+
+Having the `nixpkgs` input enables you to use code from [Nixpkgs].
+This is what enables you to use all those NixOS options,
+and every package installed on your machine now.
+For more information,
+you can read the [Nixpkgs preface]
+With the current configuration,
+we are only using code from Nixpkgs.
+
+Having the `epnix` input is what's going to enable you to use [packages from EPNix],
+such as Archiver Appliance.
+It also enables you to use [EPNix' extra NixOS options],
+such as the options configuring Tomcat, the systemd service, the `archappl` user and group, MariaDB, and so on.
+
+ [Nix flake command manual]: https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-flake.html
+ [Flake wiki page]: https://nixos.wiki/wiki/Flakes
+ [Nixpkgs]: https://github.com/NixOS/nixpkgs
+ [Nixpkgs preface]: https://nixos.org/manual/nixpkgs/stable/#preface
+ [packages from EPNix]: ../../pkgs/packages.md
+ [EPNix' extra NixOS options]: ../options.md
+
+# Configuring Archiver Appliance
+
+Now for the fun part,
+actually using those EPNix options to install and configure Archiver Appliance,
+and all its dependencies.
+
+Create and edit the file `archiver-appliance.nix` under `/etc/nixos`.
+For now, here are the contents:
+
+``` {.nix filename="archiver-appliance.nix"}
+{
+ services.archiver-appliance.enable = true;
+}
+```
+
+In your `flake.nix`,
+import the newly created file by adding `./archiver-appliance.nix`,
+under `./configuration.nix`:
+
+``` diff
+ modules = [
+ epnix.nixosModules.nixos
+
+ ./configuration.nix
++ ./archiver-appliance.nix
+ ];
+```
+
+If you try to test your changes by running `nixos-rebuild test`,
+you will see a helpful error message:
+
+::: sourceCode
+``` sourcecode
+error: The option `services.archiver-appliance.stores.lts.location'
+ is used but not defined.
+(use '--show-trace' to show detailed location information)
+```
+:::
+
+This tells you that the `services.archiver-appliance.stores.lts.location` is mandatory,
+but we didn't set any value.
+
+To figure out what this option is about,
+you can examine the [options reference].
+
+The options reference gives a description for this option:
+
+> Backing directory containing the LTS.
+
+and an example:
+
+``` nix
+"/data/lts"
+```
+
+It tells us that you need to choose where the Long Term Store (LTS) is.
+See the "Architecture" section of the [Archiver Appliance Details] page for what the various stores are.
+
+Because this is a test VM,
+let's configure the LTS to a test location,
+like `/tmp/lts`.
+You will also need to configure the location of the Medium Term Store (MTS).
+
+Here's how to change `archiver-appliance.nix`:
+
+``` {.nix filename="archiver-appliance.nix"}
+{
+ services.archiver-appliance.enable = true;
+ services.archiver-appliance.stores.lts.location = "/tmp/lts";
+ services.archiver-appliance.stores.mts.location = "/tmp/mts";
+}
+```
+
+If you don't want to repeat yourself,
+you can also change it like so:
+
+``` {.nix filename="archiver-appliance.nix"}
+{
+ services.archiver-appliance = {
+ enable = true;
+ stores.lts.location = "/tmp/lts";
+ stores.mts.location = "/tmp/mts";
+ };
+}
+```
+
+And now,
+`nixos-rebuild test` should succeed:
+
+::: sourceCode
+``` sourcecode
+building the system configuration...
+activating the configuration...
+setting up /etc...
+reloading user units for admin...
+setting up tmpfiles
+reloading the following units: dbus.service
+the following new units were started: arch-lts-ArchiverStore.mount,
+ arch-mts-ArchiverStore.mount, arch-sts-ArchiverStore.mount,
+ mysql.service, tomcat.service
+```
+:::
+
+From the message,
+we can guess it started the Tomcat server running Archiver Appliance,
+the MySQL (in fact, MariaDB) server,
+and some mounted some partitions.
+Fantastic!
+
+You can run the `systemctl list-units` command to see if any systemd unit failed.
+
+In the default configuration,
+Archiver Appliance and Tomcat are configured to output logs to journald.
+You can see those logs by running:
+
+``` bash
+journalctl -xeu tomcat.service
+```
+
+You can also see the MariaDB logs by running:
+
+``` bash
+journalctl -xeu mysql.service
+```
+
+::: callout-note
+Here are some details on what was done by EPNix' `services.archiver-appliance` NixOS module:
+
+- Creation of the Linux user and group `archappl`
+- Installation and configuration of MariaDB:
+ - Creation of the `archappl` user,
+ with UNIX socket authentication
+ - Creation of the Archiver Appliance database
+ - Creation of the [various tables] in that database
+ - Giving access rights to this database for the `archappl` user
+- Installation and configuration of Tomcat:
+ - Installation of the WAR files of Archiver Appliance
+ - Installation of the MariaDB connector and its dependencies
+ - Configuring the MariaDB connector to authenticate to the database
+ - Logging configuration to `journald`
+- Configuring mounts so that:
+ - `/arch/lts` and `/arch/mts` are bind mounts to the configured locations,
+ with some added security options,
+ such as `nodev` and `noexec`
+ - Mounting `/arch/sts` as a new `tmpfs`
+:::
+
+Tomcat runs by default under port 8080,
+and NixOS has a firewall enabled by default.
+
+Change your `archiver-appliance.nix`:
+
+``` {.nix filename="archiver-appliance.nix"}
+{
+ services.archiver-appliance = {
+ enable = true;
+ stores.lts.location = "/tmp/lts";
+ stores.mts.location = "/tmp/mts";
+
+ # New option:
+ openFirewall = true;
+ };
+}
+```
+
+and run `nixos-rebuild test`.
+It will restart `firewall.service`,
+but configured to allow incoming connection on port 8080.
+
+Check the IP address of your VM with `ip a`,
+and open a browser to `http://:8080/mgmt/ui/index.html`.
+
+Finally,
+run `nixos-rebuild switch` to confirm your changes.
+This will apply your changes for the next reboot,
+by adding a new boot entry,
+enabling you to go back to a previous configuration.
+
+You have now configured Archiver Appliance on NixOS.
+
+ [options reference]: ../options.md
+ [Archiver Appliance Details]: https://slacmshankar.github.io/epicsarchiver_docs/details.html
+ [various tables]: https://github.com/slacmshankar/epicsarchiverap/blob/master/src/main/org/epics/archiverappliance/config/persistence/archappl_mysql.sql
+
+# Next steps
+
+This VM configuration has some problems:
+
+- It stores the LTS and MTS in `/tmp`,
+ which by default is cleaned on reboot
+- The size of the Short Term Store (STS) isn't configured
+- Both "management" and "retrieval" URLs are accessible without authentication
+
+The following sections are some pointers to fix these issues.
+
+## Configuring partitions
+
+If you want to change the location of the LST or MTS,
+you can change the value of the corresponding options:
+
+- `services.archiver-appliance.stores.lts.location`
+- `services.archiver-appliance.stores.mts.location`
+
+But these values won't mean much if the configured directories are not backed by the appropriate hardware.
+
+As an example given by the [Archiver Appliance Details] page,
+section "Architecture",
+we can have the LTS backed by a NAS or SAN,
+and the MTS backed by SSD or SAS storage.
+
+The way to do that is to configure the `fileSystems` NixOS option.
+See the [File Systems NixOS documentation] for more information.
+
+ [Archiver Appliance Details]: https://slacmshankar.github.io/epicsarchiver_docs/details.html
+ [File Systems NixOS documentation]: https://nixos.org/manual/nixos/stable/#ch-file-systems
+
+## Size of the short term store
+
+To configure the size of the short term store,
+use the `services.archiver-appliance.stores.sts.size` option.
+
+For example:
+
+``` {.nix filename="archiver-appliance.nix"}
+{
+ services.archiver-appliance = {
+ enable = true;
+ stores.lts.location = "/tmp/lts";
+ stores.mts.location = "/tmp/mts";
+
+ openFirewall = true;
+
+ # New option:
+ stores.sts.size = "20g";
+ };
+}
+```
+
+See the [`sts.size` option] in the reference for a more in-depth description.
+
+ [`sts.size` option]: ../options.md#services.archiver-appliance.stores.sts.size
+
+## Restricting access
+
+Allowing access to `mgmt` URLs to anyone can be dangerous,
+because it allows anyone to delete and archive PVs.
+
+To restrict access,
+you can close the firewall and put an nginx server in front.
+
+You can configure the nginx server to disallow access to the URLs you want.
+You can also configure nginx to require authentication.
+
+```{=html}
+
+```
diff --git a/doc/vale/Readability/AutomatedReadability.yml b/doc/vale/Readability/AutomatedReadability.yml
deleted file mode 100644
index dd9fe669..00000000
--- a/doc/vale/Readability/AutomatedReadability.yml
+++ /dev/null
@@ -1,8 +0,0 @@
-extends: metric
-message: "Try to keep the Automated Readability Index (%s) below 8."
-link: https://en.wikipedia.org/wiki/Automated_readability_index
-
-formula: |
- (4.71 * (characters / words)) + (0.5 * (words / sentences)) - 21.43
-
-condition: "> 8"
diff --git a/doc/vale/Readability/ColemanLiau.yml b/doc/vale/Readability/ColemanLiau.yml
deleted file mode 100644
index d478303c..00000000
--- a/doc/vale/Readability/ColemanLiau.yml
+++ /dev/null
@@ -1,8 +0,0 @@
-extends: metric
-message: "Try to keep the Coleman–Liau Index grade (%s) below 9."
-link: https://en.wikipedia.org/wiki/Coleman%E2%80%93Liau_index
-
-formula: |
- (0.0588 * (characters / words) * 100) - (0.296 * (sentences / words) * 100) - 15.8
-
-condition: "> 9"
diff --git a/doc/vale/Readability/FleschKincaid.yml b/doc/vale/Readability/FleschKincaid.yml
deleted file mode 100644
index 3f60f205..00000000
--- a/doc/vale/Readability/FleschKincaid.yml
+++ /dev/null
@@ -1,8 +0,0 @@
-extends: metric
-message: "Try to keep the Flesch–Kincaid grade level (%s) below 8."
-link: https://en.wikipedia.org/wiki/Flesch%E2%80%93Kincaid_readability_tests
-
-formula: |
- (0.39 * (words / sentences)) + (11.8 * (syllables / words)) - 15.59
-
-condition: "> 8"
diff --git a/doc/vale/Readability/FleschReadingEase.yml b/doc/vale/Readability/FleschReadingEase.yml
deleted file mode 100644
index 61797667..00000000
--- a/doc/vale/Readability/FleschReadingEase.yml
+++ /dev/null
@@ -1,8 +0,0 @@
-extends: metric
-message: "Try to keep the Flesch reading ease score (%s) above 70."
-link: https://en.wikipedia.org/wiki/Flesch%E2%80%93Kincaid_readability_tests
-
-formula: |
- 206.835 - (1.015 * (words / sentences)) - (84.6 * (syllables / words))
-
-condition: "< 70"
diff --git a/doc/vale/Readability/GunningFog.yml b/doc/vale/Readability/GunningFog.yml
deleted file mode 100644
index 302c0eeb..00000000
--- a/doc/vale/Readability/GunningFog.yml
+++ /dev/null
@@ -1,8 +0,0 @@
-extends: metric
-message: "Try to keep the Gunning-Fog index (%s) below 10."
-link: https://en.wikipedia.org/wiki/Gunning_fog_index
-
-formula: |
- 0.4 * ((words / sentences) + 100 * (complex_words / words))
-
-condition: "> 10"
diff --git a/doc/vale/Readability/LIX.yml b/doc/vale/Readability/LIX.yml
deleted file mode 100644
index f5b0f4e8..00000000
--- a/doc/vale/Readability/LIX.yml
+++ /dev/null
@@ -1,17 +0,0 @@
-extends: metric
-message: "Try to keep the LIX score (%s) below 35."
-
-link: https://en.wikipedia.org/wiki/Lix_(readability_test)
-# Very Easy: 20 - 25
-#
-# Easy: 30 - 35
-#
-# Medium: 40 - 45
-#
-# Difficult: 50 - 55
-#
-# Very Difficult: 60+
-formula: |
- (words / sentences) + ((long_words * 100) / words)
-
-condition: "> 35"
diff --git a/doc/vale/Readability/SMOG.yml b/doc/vale/Readability/SMOG.yml
deleted file mode 100644
index e7f5913b..00000000
--- a/doc/vale/Readability/SMOG.yml
+++ /dev/null
@@ -1,8 +0,0 @@
-extends: metric
-message: "Try to keep the SMOG grade (%s) below 10."
-link: https://en.wikipedia.org/wiki/SMOG
-
-formula: |
- 1.0430 * math.sqrt((polysyllabic_words * 30.0) / sentences) + 3.1291
-
-condition: "> 10"
diff --git a/doc/vale/Readability/meta.json b/doc/vale/Readability/meta.json
deleted file mode 100644
index 0ff71c30..00000000
--- a/doc/vale/Readability/meta.json
+++ /dev/null
@@ -1,4 +0,0 @@
-{
- "feed": "https://github.com/errata-ai/Readability/releases.atom",
- "vale_version": ">=2.13.0"
-}
\ No newline at end of file
diff --git a/doc/vale/RedHat/CaseSensitiveTerms.yml b/doc/vale/RedHat/CaseSensitiveTerms.yml
index 5039ef07..ae2659c9 100644
--- a/doc/vale/RedHat/CaseSensitiveTerms.yml
+++ b/doc/vale/RedHat/CaseSensitiveTerms.yml
@@ -9,18 +9,27 @@ action:
name: replace
swap:
"(?