From 7139d6a13cb7d2a04880629f9caf8a374e793417 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?J=C3=B6rg=20Thalheim?= <joerg@thalheim.io>
Date: Fri, 18 Aug 2023 18:10:55 +0200
Subject: [PATCH] templates: improve docs

---
 README.md | 77 ++++++++++++++++++++++++++++++++++++++++---------------
 1 file changed, 57 insertions(+), 20 deletions(-)

diff --git a/README.md b/README.md
index 9508160a..78497e3d 100644
--- a/README.md
+++ b/README.md
@@ -933,28 +933,59 @@ can be used together with sops-nix.
 
 ## Templates
 
-If you need secrets in a configuration file you can use the template feature to interpolate them:
+If your setup requires embedding secrets within a configuration file, the `template` feature of `sops-nix` provides a seamless way to do this. 
 
-```nix
-{
-  sops.secrets.your-secret = { };
-  # At activation file, sops-nix will replace the placeholder with the configuration content
-  sops.templates."your-config-with-secrets.toml".content = ''
-    password = "${config.sops.placeholder.your-secret}"
-  '';
-  sops.templates."your-config-with-secrets.toml".owner = "servicuser";
-
-  systemd.services.myservice = {
-    # ...
-    serviceConfig = {
-      # you can refer to the rendered configuration with the secrets using the .path attribute.
-      ExecStart = "${pkgs.myservice}/bin/myservice --config ${config.sops.templates."your-config-with-secrets.toml".path}";
-      User = "serviceuser"
-    };
-  };
-}
-```
+Here's how to use it:
+
+1. **Define Your Secret**
+
+   Specify the secrets you intend to use. This will be encrypted and managed securely by `sops-nix`.
+
+   ```nix
+   {
+     sops.secrets.your-secret = { };
+   }
+   ```
+
+2. **Use Templates for Configuration with Secrets**
+
+   Create a template for your configuration file and utilize the placeholder where you'd like the secret to be inserted. 
+   During the activation phase, `sops-nix` will substitute the placeholder with the actual secret content.
 
+   ```nix
+   {
+     sops.templates."your-config-with-secrets.toml".content = ''
+       password = "${config.sops.placeholder.your-secret}"
+     '';
+   }
+   ```
+
+   You can also define ownership properties for the configuration file:
+
+   ```nix
+   { 
+     sops.templates."your-config-with-secrets.toml".owner = "serviceuser";
+   }
+   ```
+
+3. **Reference the Rendered Configuration in Services**
+
+   When defining a service (e.g., using `systemd`), refer to the rendered configuration (with secrets in place) by leveraging the `.path` attribute.
+
+   ```nix
+   {
+     systemd.services.myservice = {
+       # ... (any other service attributes)
+
+       serviceConfig = {
+         ExecStart = "${pkgs.myservice}/bin/myservice --config ${config.sops.templates."your-config-with-secrets.toml".path}";
+         User = "serviceuser";
+       };
+     };
+   }
+   ```
+
+**Note:** Always ensure that secrets and configurations are managed with care, considering access rights and the principle of least privilege.
 
 ## Related projects
 
@@ -973,3 +1004,9 @@ We are building sops-nix very much as contributors to the community and are comm
 That said, many of us that are contributing to sops-nix also work for consultancies. If you want to contact one of those for paid-for support setting up sops-nix in your infrastructure you can do so here:
 * [Numtide](https://numtide.com/contact)
 * [Helsinki Systems](https://helsinki-systems.de/)
+
+
+Improved documentation on sops-nix:
+
+---
+