diff --git a/tools/nixery/.gitattributes b/tools/nixery/.gitattributes new file mode 100644 index 000000000..74464db94 --- /dev/null +++ b/tools/nixery/.gitattributes @@ -0,0 +1,2 @@ +# Ignore stylesheet modifications for the book in Linguist stats +*.css linguist-detectable=false diff --git a/tools/nixery/docs/.gitignore b/tools/nixery/docs/.gitignore new file mode 100644 index 000000000..7585238ef --- /dev/null +++ b/tools/nixery/docs/.gitignore @@ -0,0 +1 @@ +book diff --git a/tools/nixery/docs/book.toml b/tools/nixery/docs/book.toml new file mode 100644 index 000000000..bf6ccbb27 --- /dev/null +++ b/tools/nixery/docs/book.toml @@ -0,0 +1,8 @@ +[book] +authors = ["Vincent Ambo "] +language = "en" +multilingual = false +src = "src" + +[output.html] +additional-css = ["theme/nixery.css"] diff --git a/tools/nixery/docs/src/SUMMARY.md b/tools/nixery/docs/src/SUMMARY.md new file mode 100644 index 000000000..5d680b82e --- /dev/null +++ b/tools/nixery/docs/src/SUMMARY.md @@ -0,0 +1,4 @@ +# Summary + +- [Nixery](./nixery.md) +- [Nix, the language](./nix-1p.md) diff --git a/tools/nixery/docs/src/nix-1p.md b/tools/nixery/docs/src/nix-1p.md new file mode 100644 index 000000000..a21234150 --- /dev/null +++ b/tools/nixery/docs/src/nix-1p.md @@ -0,0 +1,2 @@ +This page is a placeholder. During the build process, it is replaced by the +actual `nix-1p` guide from https://github.com/tazjin/nix-1p diff --git a/tools/nixery/static/nixery-logo.png b/tools/nixery/docs/src/nixery-logo.png similarity index 100% rename from tools/nixery/static/nixery-logo.png rename to tools/nixery/docs/src/nixery-logo.png diff --git a/tools/nixery/docs/src/nixery.md b/tools/nixery/docs/src/nixery.md new file mode 100644 index 000000000..d3d1911d2 --- /dev/null +++ b/tools/nixery/docs/src/nixery.md @@ -0,0 +1,77 @@ +![Nixery](./nixery-logo.png) + +------------ + +Welcome to this instance of [Nixery][]. It provides ad-hoc container images that +contain packages from the [Nix][] package manager. Images with arbitrary +packages can be requested via the image name. + +Nix not only provides the packages to include in the images, but also builds the +images themselves by using an interesting layering strategy described in [this +blog post][layers]. + +## Quick start + +Simply pull an image from this registry, separating each package you want +included by a slash: + + docker pull nixery.dev/shell/git/htop + +This gives you an image with `git`, `htop` and an interactively configured +shell. You could run it like this: + + docker run -ti nixery.dev/shell/git/htop bash + +Each path segment corresponds either to a key in the Nix package set, or a +meta-package that automatically expands to several other packages. + +Meta-packages **must** be the first path component if they are used. Currently +the only meta-package is `shell`, which provides a `bash`-shell with interactive +configuration and standard tools like `coreutils`. + +**Tip:** When pulling from a private Nixery instance, replace `nixery.dev` in +the above examples with your registry address. + +## FAQ + +If you have a question that is not answered here, feel free to file an issue on +Github so that we can get it included in this section. The volume of questions +is quite low, thus by definition your question is already frequently asked. + +### Where is the source code for this? + +Over [on Github][Nixery]. It is licensed under the Apache 2.0 license. Consult +the documentation entries in the sidebar for information on how to set up your +own instance of Nixery. + +### Which revision of `nixpkgs` is used for the builds? + +The instance at `nixery.dev` tracks a recent NixOS channel, currently NixOS +19.03. The channel is updated several times a day. + +Private registries might be configured to track a different channel (such as +`nixos-unstable`) or even track a git repository with custom packages. + +### Is this an official Google project? + +**No.** Nixery is not officially supported by Google. + +### Should I depend on `nixery.dev` in production? + +While we appreciate the enthusiasm, if you would like to use Nixery in your +production project we recommend setting up a private instance. The public Nixery +at `nixery.dev` is run on a best-effort basis and we make no guarantees about +availability. + +### Who made this? + +Nixery was written mostly by [tazjin][]. + +[grahamc][] authored the image layering strategy. Many people have contributed +to Nix over time, maybe you could become one of them? + +[Nixery]: https://github.com/google/nixery +[Nix]: https://nixos.org/nix +[layers]: https://grahamc.com/blog/nix-and-layered-docker-images +[tazjin]: https://github.com/tazjin +[grahamc]: https://github.com/grahamc diff --git a/tools/nixery/docs/theme/favicon.png b/tools/nixery/docs/theme/favicon.png new file mode 100644 index 000000000..f510bde19 Binary files /dev/null and b/tools/nixery/docs/theme/favicon.png differ diff --git a/tools/nixery/docs/theme/nixery.css b/tools/nixery/docs/theme/nixery.css new file mode 100644 index 000000000..c240e693d --- /dev/null +++ b/tools/nixery/docs/theme/nixery.css @@ -0,0 +1,3 @@ +h2, h3 { + margin-top: 1em; +} diff --git a/tools/nixery/static/favicon.ico b/tools/nixery/static/favicon.ico deleted file mode 100644 index 7523e8513..000000000 Binary files a/tools/nixery/static/favicon.ico and /dev/null differ diff --git a/tools/nixery/static/index.html b/tools/nixery/static/index.html deleted file mode 100644 index 24aa879a5..000000000 --- a/tools/nixery/static/index.html +++ /dev/null @@ -1,108 +0,0 @@ - - - - - - Nixery - - - -
-
- -
- -
-
- -

- This is an instance - of Nixery, which - provides the ability to pull ad-hoc container images from a - Docker-compatible registry server. The image names specify the - contents the image should contain, which are then retrieved and - built by the Nix package manager. -

-

- Nix is also responsible for the creation of the container images - themselves. To do this it uses an interesting layering strategy - described in - this blog post. -

-

How does it work?

-

- Simply point your local Docker installation (or other compatible - registry client) at Nixery and ask for an image with the - contents you desire. Image contents are path separated in the - name, so for example if you needed an image that contains a - shell and emacs you could pull it as such: -

-

- nixery.dev/shell/emacs25-nox -

-

- Image tags are currently ignored. Every package name needs to - correspond to a key in the - nixpkgs package set. -

-

- The special meta-package shell provides default packages - you would expect in an interactive environment (such as an - interactively configured bash). If you use this package - you must specify it as the first package in an image. -

-

FAQ

- - -