From 0f6a1bd41f5e1e59f3da3583b677c8fcc4443def Mon Sep 17 00:00:00 2001
From: Robert Hensing <robert@roberthensing.nl>
Date: Tue, 18 Dec 2018 14:53:37 +0100
Subject: [PATCH] Doc improvements

---
 README.md                          | 56 ++++++++++++++++++++++++++++--
 examples/minimal/arion-compose.nix | 21 +++++++++++
 examples/minimal/arion-pkgs.nix    |  2 ++
 examples/todomvc/README.md         |  4 +++
 src/arion                          | 10 ++++++
 5 files changed, 91 insertions(+), 2 deletions(-)
 create mode 100644 examples/minimal/arion-compose.nix
 create mode 100644 examples/minimal/arion-pkgs.nix
 create mode 100644 examples/todomvc/README.md

diff --git a/README.md b/README.md
index 276def9..f27215f 100644
--- a/README.md
+++ b/README.md
@@ -29,6 +29,8 @@ want to either build images or manage garbage collection roots if you
 control the deployment host. Either of these has yet to be
 implemented.
 
+Support for other Linux than NixOS is untested.
+
 # Install
 
 Have [Nix](https://nixos.org/nix/) and Docker installed.
@@ -36,14 +38,57 @@ Have [Nix](https://nixos.org/nix/) and Docker installed.
     git clone git@github.com:hercules-ci/arion.git
     nix-env -iA arion -f .
 
-# Example of usage
+# Example `arion-compose.nix`
 
-The command line inherits most `docker-compose` commands.
+This Nix expression serves the Nix manual at host port 8000 when launched with `arion up`. It is a function from a package set (`pkgs`) to a configuration.
+
+```
+{ pkgs, ... }:
+{
+  config.docker-compose.services = {
+
+    webserver = {
+      service.useHostStore = true;
+      # service.depends_on = [ "backend" ];
+      service.command = [ "sh" "-c" ''
+                  cd "$$WEB_ROOT"
+                  ${pkgs.python3}/bin/python -m http.server
+                '' ];
+      service.ports = [
+        "8000:8000" # host:container
+      ];
+      service.environment.WEB_ROOT = "${pkgs.nix.doc}/share/doc/nix/manual";
+    };
+
+    # backend = { ... }
+  };
+}
+```
+
+The `pkgs` argument comes from a file called `arion-pkgs.nix`. It can be as simple as `import <nixpkgs> {}` to use the Nixpkgs from your `$NIX_PATH`.
+
+# A full featured example
+
+To see how Arion can be used in a project, have a look at [todomvc-nix](https://github.com/nix-community/todomvc-nix/tree/master/deploy/arion).
 
     git clone git@github.com:nix-community/todomvc-nix.git
     cd todomvc-nix/deploy/arion
     arion up
 
+# How it works
+
+Arion is essentially a thin wrapper around Nix and docker-compose.
+When it runs, it does the following:
+
+ - Evaluate the configuration using Nix, producing a `docker-compose.yaml` and a garbage collection root
+ - Invoke `docker-compose`
+ - Clean up the garbage collection root
+
+Most of the interesting stuff happens in Arion's Nix expressions,
+where it runs the module system (known from NixOS) and provides the configuration that makes the Docker Compose file do the things it needs to do.
+
+The interesting part is of course the [service-host-store.nix module](src/nix/service-host-store.nix) which performs the bind mounts to make the host Nix store available in the container.
+
 # "FAQ"
 
 ### Do I need to use Hercules CI?
@@ -72,6 +117,13 @@ safe with respect to garbage collection. A deployment that is more
 serious than local development must leave a GC root on the deployment
 host. This use case is not supported as of now.
 
+### What is messing with my environment variables?
+
+Docker Compose performs its own environment variable
+substitution. This can be a little annoying in `services.command` for
+example. Either reference a script from `pkgs.writeScript` or escape
+the dollar sign as `$$`.
+
 ### Why "Arion"?
 
 Arion comes from Greek mythology. Poseidon, the god of ~Docker~ the
diff --git a/examples/minimal/arion-compose.nix b/examples/minimal/arion-compose.nix
new file mode 100644
index 0000000..7c85e7e
--- /dev/null
+++ b/examples/minimal/arion-compose.nix
@@ -0,0 +1,21 @@
+{ pkgs, ... }:
+{
+  config.docker-compose.services = {
+
+    webserver = {
+      service.useHostStore = true;
+      # service.depends_on = [ "backend" ];
+      service.command = [ "sh" "-c" ''
+                  cd "$$WEB_ROOT"
+                  ${pkgs.python3}/bin/python -m http.server
+                '' ];
+      service.ports = [
+        "8000:8000" # host:container
+      ];
+      service.environment.WEB_ROOT = "${pkgs.nix.doc}/share/doc/nix/manual";
+    };
+
+    # backend = { ... }
+  };
+}
+    
diff --git a/examples/minimal/arion-pkgs.nix b/examples/minimal/arion-pkgs.nix
new file mode 100644
index 0000000..d13a605
--- /dev/null
+++ b/examples/minimal/arion-pkgs.nix
@@ -0,0 +1,2 @@
+# Instead of pinning Nixpkgs, we can opt to use the one in NIX_PATH
+import <nixpkgs> {}
diff --git a/examples/todomvc/README.md b/examples/todomvc/README.md
new file mode 100644
index 0000000..69457e4
--- /dev/null
+++ b/examples/todomvc/README.md
@@ -0,0 +1,4 @@
+
+# todomvc
+
+This is the most full-featured example of a project. It's a [demo/template repo in its own right.](https://github.com/nix-community/todomvc-nix/tree/master/deploy/arion).
diff --git a/src/arion b/src/arion
index 454cfbc..300fa1d 100755
--- a/src/arion
+++ b/src/arion
@@ -79,6 +79,16 @@ Usage:
   arion docker-compose help
   arion docker-compose help up|logs|...
 
+Top-level arion options
+
+  These must be provided before the command.
+
+  --file FILE       Use FILE instead of the default ./arion-compose.nix
+                    Can be specified multiple times for a merged configuration.
+  --pkgs EXPR       Use EXPR instead of ./arion-pkgs.nix to get the
+                    Nixpkgs attrset used for bootstrapping and evaluating
+                    the configuration.
+
 EOF
         exit 0
         ;;