From a118a70649ca2be9c36e526269ee54bc87ea06d4 Mon Sep 17 00:00:00 2001
From: Rok Garbas <rok@garbas.si>
Date: Thu, 11 Nov 2021 16:03:09 +0100
Subject: [PATCH] Documenting how to use/build Nix' Docker image

---
 doc/manual/src/SUMMARY.md.in                  |  1 +
 .../src/installation/installing-docker.md     | 59 +++++++++++++++++++
 2 files changed, 60 insertions(+)
 create mode 100644 doc/manual/src/installation/installing-docker.md

diff --git a/doc/manual/src/SUMMARY.md.in b/doc/manual/src/SUMMARY.md.in
index 3869f4791..8d9b061ba 100644
--- a/doc/manual/src/SUMMARY.md.in
+++ b/doc/manual/src/SUMMARY.md.in
@@ -9,6 +9,7 @@
     - [Prerequisites](installation/prerequisites-source.md)
     - [Obtaining a Source Distribution](installation/obtaining-source.md)
     - [Building Nix from Source](installation/building-source.md)
+  - [Using Nix within Docker](installation/installing-docker.md)
   - [Security](installation/nix-security.md)
     - [Single-User Mode](installation/single-user.md)
     - [Multi-User Mode](installation/multi-user.md)
diff --git a/doc/manual/src/installation/installing-docker.md b/doc/manual/src/installation/installing-docker.md
new file mode 100644
index 000000000..3d2255b7a
--- /dev/null
+++ b/doc/manual/src/installation/installing-docker.md
@@ -0,0 +1,59 @@
+# Using Nix within Docker
+
+To run the latest stable release of Nix with Docker run the following command:
+
+```console
+$ docker -ti run nixos/nix
+Unable to find image 'nixos/nix:latest' locally
+latest: Pulling from nixos/nix
+5843afab3874: Pull complete
+b52bf13f109c: Pull complete
+1e2415612aa3: Pull complete
+Digest: sha256:27f6e7f60227e959ee7ece361f75d4844a40e1cc6878b6868fe30140420031ff
+Status: Downloaded newer image for nixos/nix:latest
+35ca4ada6e96:/# nix --version
+nix (Nix) 2.3.12
+35ca4ada6e96:/# exit
+```
+
+# What is included in Nix' Docker image?
+
+The official Docker image is created using `pkgs.dockerTools.buildLayeredImage`
+(and not with `Dockerfile` as it is usual with Docker images). You can still
+base your custom Docker image on it as you would do with any other Docker
+image.
+
+The Docker image is also not based on any other image and includes minimal set
+of runtime dependencies that are required to use Nix:
+
+ - pkgs.nix
+ - pkgs.bashInteractive
+ - pkgs.coreutils-full
+ - pkgs.gnutar
+ - pkgs.gzip
+ - pkgs.gnugrep
+ - pkgs.which
+ - pkgs.curl
+ - pkgs.less
+ - pkgs.wget
+ - pkgs.man
+ - pkgs.cacert.out
+ - pkgs.findutils
+
+# Docker image with the latest development version of Nix
+
+To get the latest image that was built by [Hydra](https://hydra.nixos.org) run
+the following command:
+
+```console
+$ curl -L https://hydra.nixos.org/job/nix/master/dockerImage.x86_64-linux/latest/download/1 | docker load
+$ docker run -ti nix:2.5pre20211105
+```
+
+You can also build a Docker image from source yourself:
+
+```console
+$ nix build ./\#hydraJobs.dockerImage.x86_64-linux
+$ docker load -i ./result
+$ docker run -ti nix:2.5pre20211105
+```