Document Xamal-style unit generation

Author: dannote

README.md

@@ -36,7 +36,7 @@ The package depends on [`rebus`](https://hex.pm/packages/rebus) for the D-Bus wi
 
 APIs return idiomatic `{:ok, value}` / `{:error, %Systemd.Error{}}` tuples. Permission and polkit failures are classified with `category: :permission` and can be checked with `Systemd.Error.permission?/1`.
 
-See `examples/` for service, timer, and user-bus snippets.
+See `examples/` for service, timer, and user-bus snippets, and `guides/xamal-style-deployment.md` for a deployment-oriented template unit example.
 
 ## Permissions
 

guides/xamal-style-deployment.md

@@ -0,0 +1,42 @@
+# Xamal-style deployment units
+
+`systemdkit` can build and validate template service units like the ones used by
+Xamal-style blue/green deployments. The port is the instance identifier, so
+`my_app@4000.service` and `my_app@4001.service` can be started independently.
+
+```elixir
+unit_file =
+  Systemd.UnitFile.service(
+    unit: [
+      description: "my_app (%i)",
+      after: "network.target"
+    ],
+    service: [
+      type: :exec,
+      user: "deploy",
+      working_directory: "/opt/xamal/my-app/current",
+      environment_file: "-/opt/xamal/my-app/env/app.env",
+      environment: ["PORT=%i", "RELEASE_NODE=my_app_%i"],
+      exec_start: "/opt/xamal/my-app/current/bin/my_app start",
+      restart: "on-failure",
+      restart_sec: 5,
+      timeout_stop_sec: 30,
+      limit_nofile: 1_048_576
+    ],
+    install: [wanted_by: "multi-user.target"]
+  )
+
+:ok = Systemd.UnitFile.validate(unit_file, :service)
+Systemd.UnitFile.to_string(unit_file)
+```
+
+For local systemd managers, D-Bus operations can be used directly:
+
+```elixir
+:ok = Systemd.reload()
+:ok = Systemd.start_unit("my_app@4000.service")
+{:ok, state} = Systemd.unit_state("my_app@4000.service")
+```
+
+For remote deployment tools, generate and validate unit files locally, then use
+the tool's remote execution layer to install the rendered unit on the host.

lib/systemd/unit_file/builder.ex

@@ -7,6 +7,10 @@ defmodule Systemd.UnitFile.Builder do
 
   @type directives :: keyword() | %{optional(atom() | String.t()) => term()}
 
+  @directive_names %{
+    limit_nofile: "LimitNOFILE"
+  }
+
   @doc """
   Builds a unit file from common `Unit`, `Service`, and `Install` sections.
   """
@@ -46,9 +50,11 @@ defmodule Systemd.UnitFile.Builder do
   end
 
   defp normalize_name(name) when is_atom(name) do
-    name
-    |> Atom.to_string()
-    |> Macro.camelize()
+    Map.get_lazy(@directive_names, name, fn ->
+      name
+      |> Atom.to_string()
+      |> Macro.camelize()
+    end)
   end
 
   defp normalize_name(name) when is_binary(name), do: name

mix.exs

@@ -62,7 +62,8 @@ defmodule Systemd.MixProject do
       main: "readme",
       source_url: @source_url,
       source_ref: "v#{@version}",
-      extras: ["README.md", "CHANGELOG.md", "LICENSE"]
+      extras: ["README.md", "CHANGELOG.md", "LICENSE", "guides/xamal-style-deployment.md"],
+      groups_for_extras: [Guides: ~r/guides\//]
     ]
   end
 

test/systemd/unit_file_test.exs

@@ -84,7 +84,7 @@ defmodule Systemd.UnitFileTest do
     unit_file =
       UnitFile.service(
         unit: [description: "My app", after: ["network.target", "postgresql.service"]],
-        service: [exec_start: "/opt/app/bin/app start", restart: :always, LimitNOFILE: 1_048_576],
+        service: [exec_start: "/opt/app/bin/app start", restart: :always, limit_nofile: 1_048_576],
         install: [wanted_by: "multi-user.target"]
       )