Docs: docker.md (#105)

Co-authored-by: Sridhar Ratnakumar <srid@srid.ca>

doc/howto.md

@@ -0,0 +1,5 @@
+# HOWTO
+
+```query
+path:./*
+```

doc/howto/docker.md

@@ -0,0 +1,96 @@
+---
+slug: docker
+---
+
+# Building a docker image
+
+Building a docker image is much simpler with Nix compared to writing `Dockerfile`. Since the entire build process is handled by Nix flakes, most of what's left to do for docker image creation is copying of the derivations and configuration.
+
+## Writing the Nix to build the docker image
+
+Consider a haskell-flake project "foo". To copy the binaries generated by the `default` package to `/bin` on the image,  one can use `copyToRoot` attribute offered by [`dockerTools.buildImage`](https://nixos.org/manual/nixpkgs/stable/#sec-pkgs-dockerTools). For example:
+
+```nix
+{
+  # Inside perSystem
+  packages.dockerImage = pkgs.dockerTools.buildImage {
+    name = "foo";
+    copyToRoot = pkgs.buildEnv {
+      paths = with pkgs; [
+        self'.packages.default
+      ];
+      name = "foo-root";
+      pathsToLink = [ "/bin" ];
+    };
+  };
+}
+```
+
+In addition to copying over the flake `packages`, we may also copy *paths* in the project. `self` can be added to `paths` to expose the project directory. 
+```nix
+{
+  copyToRoot = pkgs.buildEnv {
+    paths = with pkgs; [
+      coreutils
+      bash
+      self
+    ];
+    name = "foo-root";
+    pathsToLink = [ "/foo_sub" "/bin" ];
+  };
+}
+```
+If you'd like your docker image to run your haskell project's default package when the container starts, use the following config:
+```nix
+{
+  # Inside dockerImage's `buildImage`
+  config = {
+    Cmd = [ "${pkgs.lib.getExe self'.packages.default}" ];
+  };
+}
+```
+
+## Build the docker image
+
+To build the docker image *as a Nix derivation*, run:
+
+```bash
+nix build .#dockerImage
+```
+
+To load this image into your local docker image registry, run:
+
+```bash
+docker load -i $(nix build .#dockerImage --print-out-link)
+```
+
+## Tips
+
+If you don't want `docker images` showing that the image was created several decades ago, use the following:
+```nix
+{
+  # Inside perSystem.packages' `dockerImage`:
+  pkgs.dockerTools.buildImage {
+    name = "foo";
+    created = "now";
+  };
+}
+```
+
+If you want to tag the images with the commit id of the working copy:
+
+```nix
+{
+  # Inside perSystem.packages' `dockerImage`:
+  pkgs.dockerTools.buildImage {
+    name = "foo";
+    tag = builtins.substring 0 9 (self.rev or "dev");
+  };
+}
+```
+[`builtins.substring 0 9 self.rev`](https://nixos.org/manual/nix/stable/language/builtins.html#builtins-substring) is the same as `git rev-parse --short HEAD`. `self.rev` is non-null only on a clean working copy and hence the tag is set to `dev` when the working copy is dirty.
+
+
+## Example
+
+- [Sample flake-parts module for docker](https://github.com/nammayatri/nammayatri/pull/14/files#diff-18ea3dd9a6a84702796b8dac608d0cad8e396a7c2e8c52732fcb7e5f52d1b0b9)