summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authortv <tv@krebsco.de>2019-02-26 21:38:32 +0100
committertv <tv@krebsco.de>2019-02-26 21:38:32 +0100
commitad4c3cad0a04d1e733b3d3007d4a1236b0b66353 (patch)
treed2b4b2973717b3530c94ef660c26dd488c22fe31
parent5dd80e884a8d303659f43547f587fcb128dddaa0 (diff)
README: document all the source types
-rw-r--r--README.md83
1 files changed, 83 insertions, 0 deletions
diff --git a/README.md b/README.md
index e455456..5a6cbc5 100644
--- a/README.md
+++ b/README.md
@@ -2,6 +2,7 @@
krops is a lightweigt toolkit to deploy NixOS systems, remotely or locally.
+
## Some Features
- store your secrets in [password store](https://www.passwordstore.org/)
@@ -9,6 +10,7 @@ krops is a lightweigt toolkit to deploy NixOS systems, remotely or locally.
- minimal overhead (it's basically just `nixos-rebuild switch`!)
- run from custom nixpkgs branch/checkout/fork
+
## Minimal Example
Create a file named `krops.nix` (name doesn't matter) with following content:
@@ -54,10 +56,91 @@ and run `$(nix-build --no-out-link krops.nix)` to deploy the target machine.
Under the hood, this will make the sources available on the target machine
below `/var/src`, and execute `nixos-rebuild switch -I /var/src`.
+
+## Source Types
+
+### `derivation`
+
+Nix expression to be built at the target machine.
+
+Supported attributes:
+
+* `text` -
+ Nix expression to be built.
+
+
+### `file`
+
+The file source type transfers local files (and folders) to the target
+using [`rsync`](https://rsync.samba.org/).
+
+Supported attributes:
+
+* `path` -
+ absolute path to files that should by transfered
+
+* `useChecksum` (optional) -
+ boolean that controls whether file contents should be checked to decide
+ whether a file has changed. This is useful when `path` points at files
+ with mangled timestamps, e.g. the Nix store.
+
+
+### `git`
+
+Git sources that will be fetched on the target machine.
+
+Supported attributes:
+
+* `url` -
+ URL of the Git repository that should be fetched.
+
+* `ref` -
+ Branch / tag / commit that should be fetched.
+
+* `clean.exclude` -
+ List of patterns that should be excluded from Git cleaning.
+
+
+### `pass`
+
+The pass source type transfers contents from a local
+[password store](https://www.passwordstore.org/) to the target machine.
+
+Supported attributes:
+
+* `dir` -
+ absolute path to the password store.
+
+* `name` -
+ sub-directory in the password store.
+
+
+### `pipe`
+
+Executes a local command, capture its stdout, and send that as a file to the
+target machine.
+
+Supported attributes:
+
+* `command` -
+ The (shell) command to run.
+
+### `symlink`
+
+Symlink to create at the target, relative to the target directory.
+This can be used to reference files in other sources.
+
+Supported attributes:
+
+* `target` -
+ Content of the symlink. This is typically a relative path.
+
+
## References
- [In-depth example](http://tech.ingolf-wagner.de/nixos/krops/) by [Ingolf Wagner](https://ingolf-wagner.de/)
+
## Communication
Comments, questions, pull-requests, etc. are very welcome, and can be directed