docs: update installation instructions

These instructions were not up-to-date (they didn't mention
the different storage backends, and some variables were
tagged as optional while they were mandatory). With this
update, they should (hopefully) be more accurate! :)

I also added instructions if someone wants to run Nixery
outside of the container image (I found it convenient when
working on Nixery's code).

1 files changed, 60 insertions, 12 deletions

diff --git a/tools/nixery/docs/src/run-your-own.md b/tools/nixery/docs/src/run-your-own.md
index 4ffb8c4d4b6e..eb7d494ee3e2 100644
--- a/tools/nixery/docs/src/run-your-own.md
+++ b/tools/nixery/docs/src/run-your-own.md
@@ -32,7 +32,16 @@ To run Nixery, you must have:
 * [Nix][] (to build Nixery itself)
 * Somewhere to run it (your own server, Google AppEngine, a Kubernetes cluster,
   whatever!)
-* A [Google Cloud Storage][gcs] bucket in which to store & serve layers
+* *Either* a [Google Cloud Storage][gcs] bucket in which to store & serve layers,
+  *or* a comfortable amount of disk space
+
+Note that while the main Nixery process is a server written in Go,
+it invokes a script that itself relies on Nix to be available.
+You can compile the main Nixery daemon without Nix, but it won't
+work without Nix.
+
+(If you are completely new to Nix and don't know how to get
+started, check the [Nix installation documentation][nixinstall].)
 
 ## 1. Choose a package set
 
@@ -54,8 +63,11 @@ use it with your own packages. There are three options available:
 
 ## 2. Build Nixery itself
 
-Building Nixery creates a container image. This section assumes that the
-container runtime used is Docker, please modify instructions correspondingly if
+### 2.1. With a container image
+
+The easiest way to run Nixery is to build a container image.
+This section assumes that the container runtime used is Docker,
+please modify instructions accordingly if
 you are using something else.
 
 With a working Nix installation, building Nixery is done by invoking `nix-build
@@ -64,23 +76,46 @@ With a working Nix installation, building Nixery is done by invoking `nix-build
 This will create a `result`-symlink which points to a tarball containing the
 image. In Docker, this tarball can be loaded by using `docker load -i result`.
 
+### 2.2. Without a container image
+
+*This method might be more convenient if you intend to work on
+the code of the Nixery server itself, because you won't have to
+rebuild (and reload) an image each time to test your changes.*
+
+You will need to run the two following commands at the root of the repo:
+
+* `go build` to build the `nixery` binary;
+* `nix-env --install --file prepare-image/default.nix` to build
+  the required helpers.
+
 ## 3. Prepare configuration
 
 Nixery is configured via environment variables.
 
 You must set *all* of these:
 
-* `BUCKET`: [Google Cloud Storage][gcs] bucket to store & serve image layers
+* `NIXERY_STORAGE_BACKEND` (must be set to `gcs` or `filesystem`)
 * `PORT`: HTTP port on which Nixery should listen
+* `WEB_DIR`: directory containing static files (see below)
 
-You may set *one* of these, if unset Nixery defaults to `nixos-20.09`:
+You must set *one* of these:
 
-* `NIXERY_CHANNEL`: The name of a Nix/NixOS channel to use for building
+* `NIXERY_CHANNEL`: The name of a [Nix/NixOS channel][nixchannel] to use for building,
+  for instance `nixos-21.05`
 * `NIXERY_PKGS_REPO`: URL of a git repository containing a package set (uses
   locally configured SSH/git credentials)
 * `NIXERY_PKGS_PATH`: A local filesystem path containing a Nix package set to use
   for building
 
+If `NIXERY_STORAGE_BACKEND` is set to `filesystem`, then `STORAGE_PATH`
+must be set to the directory that will hold the registry blobs.
+That directory must be located on a filesystem that supports extended
+attributes (which means that on most systems, `/tmp` won't work).
+
+If `NIXERY_STORAGE_BACKEND` is set to `gcs`, then `GCS_BUCKET`
+must be set to the [Google Cloud Storage][gcs] bucket that will be
+used to store & serve image layers.
+
 You may set *all* of these:
 
 * `NIX_TIMEOUT`: Number of seconds that any Nix builder is allowed to run
@@ -94,13 +129,11 @@ If the `GOOGLE_APPLICATION_CREDENTIALS` environment is configured, the service
 account's private key will be used to create [signed URLs for
 layers][signed-urls].
 
-## 4. Deploy Nixery
-
-With the above environment variables configured, you can run the image that was
-built in step 2.
+## 4. Start Nixery
 
-How this works depends on the environment you are using and is, for now, outside
-of the scope of this tutorial.
+Run the image that was built in step 2.1 with all the environment variables
+mentioned above. Alternatively, set all the environment variables and run
+the Nixery server that was built in step 2.2.
 
 Once Nixery is running you can immediately start requesting images from it.
 
@@ -125,6 +158,19 @@ following:
 * Configure request timeouts for Nixery if you have your own web server in front
   of it. This will be natively supported by Nixery in the future.
 
+## 6. `WEB_DIR`
+
+All the URLs accessed by Docker registry clients start with `/v2/`.
+This means that it is possible to serve a static website from Nixery
+itself (as long as you don't want to serve anything starting with `/v2`).
+This is how, for instance, https://nixery.dev shows the website for Nixery,
+while it is also possible to e.g. `docker pull nixery.dev/shell`.
+
+When running Nixery, you must set the `WEB_DIR` environment variable.
+When Nixery receives requests that don't look like registry requests,
+it tries to serve them using files in the directory indicated by `WEB_DIR`.
+If the directory doesn't exist, Nixery will run fine but serve 404.
+
 -------
 
 [^1]: Nixery will not work with Nix channels older than `nixos-19.03`.
@@ -141,3 +187,5 @@ following:
 [repo]: https://github.com/google/nixery
 [signed-urls]: under-the-hood.html#5-image-layers-are-requested
 [ADC]: https://cloud.google.com/docs/authentication/production#finding_credentials_automatically
+[nixinstall]: https://nixos.org/manual/nix/stable/installation/installing-binary.html
+[nixchannel]: https://nixos.wiki/wiki/Nix_channels