diff options
Diffstat (limited to 'tools/nixery/docs/src/run-your-own.md')
| -rw-r--r-- | tools/nixery/docs/src/run-your-own.md | 72 |
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 |