Try #92:

docs/modules/ROOT/pages/index.adoc

@@ -38,6 +38,7 @@ Arion allows to compose containers with different granularity:
   * <<NixOS: run only one systemd service>>
   * <<NixOS: run full OS>>
   * <<Docker image from DockerHub>>
+  * <<Docker image tar archive>>
 
 == Installation
 
@@ -178,6 +179,53 @@ Describe containers using NixOS-style modules. There are a few options:
 }
 ```
 
+==== Docker image tar archive
+
+`examples/custom-image/arion-compose.nix`:
+
+```nix
+{ pkgs, ... }:
+
+let
+  webRoot = "/www";
+
+  webserverImage = pkgs.dockerTools.buildLayeredImage {
+    name = "a-webserver";
+
+    config = {
+      Entrypoint = [
+        "${pkgs.darkhttpd}/bin/darkhttpd" webRoot
+      ];
+
+      Volumes = {
+        "${webRoot}" = {};
+      };
+    };
+  };
+in {
+  config.services = {
+
+    webserver = {
+      image.drv = webserverImage;
+      service.command = [ "--port" "8000" ];
+      service.ports = [
+        "8000:8000" # host:container
+      ];
+      service.volumes = [
+        "${webRoot}:${pkgs.nix.doc}/share/doc/nix/manual"
+      ];
+    };
+  };
+}
+```
+
+Note that `config.services.<service>.image.drv` accepts any derivation providing a
+https://docs.docker.com/engine/reference/commandline/image_load/[`docker image load`]able
+tar archive; it is not limited to derivations created with
+https://nixos.org/nixpkgs/manual/#ssec-pkgs-dockerTools-buildImage[`buildImage`]
+or https://nixos.org/nixpkgs/manual/#ssec-pkgs-dockerTools-buildLayeredImage[`buildLayeredImage`]
+from https://nixos.org/nixpkgs/manual/#sec-pkgs-dockerTools[`pkgs.dockerTools`].
+
 === Run
 
 Start containers and watch their logs:

docs/modules/ROOT/partials/NixOSOptions.adoc

@@ -179,6 +179,34 @@ Default::
 
 No Example:: {blank}
 
+== services.<name>.image.drv
+
+Docker image derivation to be `docker load`ed.
+
+By default, when `services.<name>.image.nixBuild` is enabled, this is
+the image produced using `services.<name>.image.command`,
+`services.<name>.image.contents`, and
+`services.<name>.image.rawConfig`.
+
+
+[discrete]
+=== details
+
+Type:: null or package
+Default::
++
+----
+{"_type":"literalExample","text":"pkgs.dockerTools.buildLayeredImage { ... };\n"}
+----
+
+
+Example::
++
+----
+{"_type":"literalExample","text":"let\n  myimage = pkgs.dockerTools.buildImage {\n    name = \"my-image\";\n    contents = [ pkgs.coreutils ];\n  };\nin\nconfig.services = {\n  myservice = {\n    image.drv = myimage;\n    # ...\n  };\n}\n"}
+----
+
+
 == services.<name>.image.name
 
 A human readable name for the docker image.

examples/custom-image/arion-compose.nix

@@ -0,0 +1,33 @@
+{ pkgs, ... }:
+
+let
+  webRoot = "/www";
+
+  webserverImage = pkgs.dockerTools.buildLayeredImage {
+    name = "a-webserver";
+
+    config = {
+      Entrypoint = [
+        "${pkgs.darkhttpd}/bin/darkhttpd" webRoot
+      ];
+
+      Volumes = {
+        "${webRoot}" = {};
+      };
+    };
+  };
+in {
+  config.services = {
+
+    webserver = {
+      image.drv = webserverImage;
+      service.command = [ "--port" "8000" ];
+      service.ports = [
+        "8000:8000" # host:container
+      ];
+      service.volumes = [
+        "${webRoot}:${pkgs.nix.doc}/share/doc/nix/manual"
+      ];
+    };
+  };
+}

examples/custom-image/arion-pkgs.nix

@@ -0,0 +1,6 @@
+# Instead of pinning Nixpkgs, we can opt to use the one in NIX_PATH
+import <nixpkgs> {
+  # We specify the architecture explicitly. Use a Linux remote builder when
+  # calling arion from other platforms.
+  system = "x86_64-linux";
+}

src/nix/modules/service/image.nix

@@ -41,6 +41,14 @@ in
       type = nullOr package;
       description = ''
         Docker image derivation to be `docker load`ed.
+
+        By default, when `services.<name>.image.nixBuild` is enabled, this is
+        the image produced using `services.<name>.image.command`,
+        `services.<name>.image.contents`, and
+        `services.<name>.image.rawConfig`.
+      '';
+      defaultText = lib.literalExample ''
+        pkgs.dockerTools.buildLayeredImage { ... };
       '';
       internal = true;
     };
@@ -105,9 +113,27 @@ in
       description = ''
       '';
     };
+    image.drv = mkOption {
+      type = nullOr package;
+      inherit (options.build.image) description defaultText;
+      example = lib.literalExample ''
+        let
+          myimage = pkgs.dockerTools.buildImage {
+            name = "my-image";
+            contents = [ pkgs.coreutils ];
+          };
+        in
+        config.services = {
+          myservice = {
+            image.drv = myimage;
+            # ...
+          };
+        }
+      '';
+    };
   };
   config = {
-    build.image = builtImage;
+    build.image = config.image.drv or builtImage;
     build.imageName = config.build.image.imageName;
     build.imageTag =
                  if config.build.image.imageTag != ""

tests/arion-test/default.nix

@@ -31,6 +31,7 @@ in
       # Pre-build the image because we don't want to build the world
       # in the vm.
       (preEval [ ../../examples/minimal/arion-compose.nix ]).config.out.dockerComposeYaml
+      (preEval [ ../../examples/custom-image/arion-compose.nix ]).config.out.dockerComposeYaml
       (preEval [ ../../examples/full-nixos/arion-compose.nix ]).config.out.dockerComposeYaml
       (preEval [ ../../examples/nixos-unit/arion-compose.nix ]).config.out.dockerComposeYaml
       pkgs.stdenv
@@ -40,27 +41,23 @@ in
     $machine->fail("curl localhost:8000");
     $machine->succeed("docker --version");
 
-    subtest "minimal", sub {
-      $machine->succeed("cp -r ${../../examples/minimal} work && cd work && NIX_PATH=nixpkgs='${pkgs.path}' arion up -d");
-      $machine->waitUntilSucceeds("curl localhost:8000");
-      $machine->succeed("cd work && NIX_PATH=nixpkgs='${pkgs.path}' arion down && rm -rf work");
-      $machine->waitUntilFails("curl localhost:8000");
-    };
+    my $makeSubtest = sub {
+      my ( $subtestName, $exampleSrc, @codeRefs ) = @_;
 
-    subtest "full-nixos", sub {
-      $machine->succeed("cp -r ${../../examples/full-nixos} work && cd work && NIX_PATH=nixpkgs='${pkgs.path}' arion up -d");
-      $machine->waitUntilSucceeds("curl localhost:8000");
-      # Also test exec with defaultExec
-      $machine->succeed("cd work && export NIX_PATH=nixpkgs='${pkgs.path}' && (echo 'nix run -f ~/h/arion arion -c arion exec webserver'; echo 'target=world; echo Hello \$target'; echo exit) | script /dev/null | grep 'Hello world'");
-      $machine->succeed("cd work && NIX_PATH=nixpkgs='${pkgs.path}' arion down && rm -rf work");
-      $machine->waitUntilFails("curl localhost:8000");
+      subtest $subtestName => sub {
+        $machine->succeed("rm -rf work && cp -frT $exampleSrc work && cd work && NIX_PATH=nixpkgs='${pkgs.path}' arion up -d");
+        $machine->waitUntilSucceeds("curl localhost:8000");
+        $_->() for @codeRefs;
+        $machine->succeed("cd work && NIX_PATH=nixpkgs='${pkgs.path}' arion down");
+        $machine->waitUntilFails("curl localhost:8000");
+      };
     };
 
-    subtest "nixos-unit", sub {
-      $machine->succeed("cp -r ${../../examples/nixos-unit} work && cd work && NIX_PATH=nixpkgs='${pkgs.path}' arion up -d");
-      $machine->waitUntilSucceeds("curl localhost:8000");
-      $machine->succeed("cd work && NIX_PATH=nixpkgs='${pkgs.path}' arion down && rm -rf work");
-      $machine->waitUntilFails("curl localhost:8000");
-    };
+    $makeSubtest->("minimal", "${../../examples/minimal}");
+    $makeSubtest->("custom-image", "${../../examples/custom-image}");
+    $makeSubtest->("full-nixos", "${../../examples/full-nixos}", sub {
+      $machine->succeed("cd work && export NIX_PATH=nixpkgs='${pkgs.path}' && (echo 'nix run -f ~/h/arion arion -c arion exec webserver'; echo 'target=world; echo Hello \$target'; echo exit) | script /dev/null | grep 'Hello world'");
+    });
+    $makeSubtest->("nixos-unit", "${../../examples/nixos-unit}");
   '';
 }