From a1a2475be5d1b103a27ea61f3b147fc8f8473353 Mon Sep 17 00:00:00 2001
From: Robert Hensing <robert@roberthensing.nl>
Date: Fri, 11 Jun 2021 13:29:52 +0200
Subject: [PATCH] docs: Add repl and build with Nix sections

---
 docs/modules/ROOT/pages/index.adoc | 42 ++++++++++++++++++++++++++++++
 1 file changed, 42 insertions(+)

diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc
index 4d3279d..1cb8a5a 100644
--- a/docs/modules/ROOT/pages/index.adoc
+++ b/docs/modules/ROOT/pages/index.adoc
@@ -205,6 +205,48 @@ $ arion logs -f
 
 You can go to `examples/*/` and run these commands to give it a quick try.
 
+=== Inspect the config
+
+While developing an arion project, you can make use of `arion repl`, which launches
+a `nix repl` on the project configuration.
+
+```
+$ arion repl
+Launching a repl for you. To get started:
+
+To see deployment-wide configuration
+  type config. and use tab completion
+To bring the top-level Nixpkgs attributes into scope
+  type :a (config._module.args.pkgs) // { inherit config; }
+
+Welcome to Nix. Type :? for help.
+
+Loading '../../src/nix/eval-composition.nix'...
+Added 5 variables.
+
+nix-repl> config.services.webserver.service.command
+[ "sh" "-c" "cd \"$$WEB_ROOT\"\n/nix/store/66fbv9mmx1j4hrn9y06kcp73c3yb196r-python3-3.8.9/bin/python -m http.server\n" ]
+
+nix-repl>
+
+```
+
+== Build with Nix
+
+You can build a project with `nix-build` using an expression like
+
+```nix
+arion.build { modules = [ ./arion-compose.nix ]; pkgs = import ./arion-pkgs.nix; }
+```
+
+If you deploy with xref:hercules-ci-effects:ROOT:reference/nix-functions/runArion.adoc[integrate],
+and your `pkgs` variable is equivalent to `import ./arion-pkgs.nix`, you can use:
+
+```nix
+let
+  deployment = pkgs.effects.runArion { /* ... */ });
+in deployment.prebuilt
+```
 
 == Project Status