docs: Replace static page with mdBook site
Uses mdBook[1] to generate a documentation overview page instead of the previous HTML site. This makes it possible to add more elaborate documentation without having to deal with finicky markup. [1]: https://github.com/rust-lang-nursery/mdBook
This commit is contained in:
parent
099c99b7ad
commit
7c41a7a872
11 changed files with 97 additions and 108 deletions
2
tools/nixery/.gitattributes
vendored
Normal file
2
tools/nixery/.gitattributes
vendored
Normal file
|
@ -0,0 +1,2 @@
|
||||||
|
# Ignore stylesheet modifications for the book in Linguist stats
|
||||||
|
*.css linguist-detectable=false
|
1
tools/nixery/docs/.gitignore
vendored
Normal file
1
tools/nixery/docs/.gitignore
vendored
Normal file
|
@ -0,0 +1 @@
|
||||||
|
book
|
8
tools/nixery/docs/book.toml
Normal file
8
tools/nixery/docs/book.toml
Normal file
|
@ -0,0 +1,8 @@
|
||||||
|
[book]
|
||||||
|
authors = ["Vincent Ambo <tazjin@google.com>"]
|
||||||
|
language = "en"
|
||||||
|
multilingual = false
|
||||||
|
src = "src"
|
||||||
|
|
||||||
|
[output.html]
|
||||||
|
additional-css = ["theme/nixery.css"]
|
4
tools/nixery/docs/src/SUMMARY.md
Normal file
4
tools/nixery/docs/src/SUMMARY.md
Normal file
|
@ -0,0 +1,4 @@
|
||||||
|
# Summary
|
||||||
|
|
||||||
|
- [Nixery](./nixery.md)
|
||||||
|
- [Nix, the language](./nix-1p.md)
|
2
tools/nixery/docs/src/nix-1p.md
Normal file
2
tools/nixery/docs/src/nix-1p.md
Normal file
|
@ -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
|
Before Width: | Height: | Size: 190 KiB After Width: | Height: | Size: 190 KiB |
77
tools/nixery/docs/src/nixery.md
Normal file
77
tools/nixery/docs/src/nixery.md
Normal file
|
@ -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
|
BIN
tools/nixery/docs/theme/favicon.png
vendored
Normal file
BIN
tools/nixery/docs/theme/favicon.png
vendored
Normal file
Binary file not shown.
After Width: | Height: | Size: 16 KiB |
3
tools/nixery/docs/theme/nixery.css
vendored
Normal file
3
tools/nixery/docs/theme/nixery.css
vendored
Normal file
|
@ -0,0 +1,3 @@
|
||||||
|
h2, h3 {
|
||||||
|
margin-top: 1em;
|
||||||
|
}
|
Binary file not shown.
Before Width: | Height: | Size: 164 KiB |
|
@ -1,108 +0,0 @@
|
||||||
<!DOCTYPE html>
|
|
||||||
<html>
|
|
||||||
<head>
|
|
||||||
<meta charset="utf-8">
|
|
||||||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
|
||||||
<title>Nixery</title>
|
|
||||||
<style>
|
|
||||||
body {
|
|
||||||
margin: 40px auto;
|
|
||||||
max-width: 650px;
|
|
||||||
line-height: 1.6;
|
|
||||||
font-size: 18px;
|
|
||||||
color: #444;
|
|
||||||
padding: 010px
|
|
||||||
}
|
|
||||||
|
|
||||||
.logo {
|
|
||||||
max-width: 650px;
|
|
||||||
}
|
|
||||||
|
|
||||||
h1, h2, h3 {
|
|
||||||
line-height: 1.2
|
|
||||||
}
|
|
||||||
</style>
|
|
||||||
</head>
|
|
||||||
<body>
|
|
||||||
<header>
|
|
||||||
<div align="center">
|
|
||||||
<img class="logo" src="nixery-logo.png">
|
|
||||||
</div>
|
|
||||||
<aside>ad-hoc container images - powered by <a href="https://nixos.org/nix/">Nix</a></aside>
|
|
||||||
<hr>
|
|
||||||
</header>
|
|
||||||
|
|
||||||
<p>
|
|
||||||
This is an instance
|
|
||||||
of <a href="https://github.com/google/nixery">Nixery</a>, 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.
|
|
||||||
</p>
|
|
||||||
<p>
|
|
||||||
Nix is also responsible for the creation of the container images
|
|
||||||
themselves. To do this it uses an interesting layering strategy
|
|
||||||
described in
|
|
||||||
<a href="https://grahamc.com/blog/nix-and-layered-docker-images">this blog post</a>.
|
|
||||||
</p>
|
|
||||||
<h3>How does it work?</h3>
|
|
||||||
<p>
|
|
||||||
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 <code>emacs</code> you could pull it as such:
|
|
||||||
</p>
|
|
||||||
<p>
|
|
||||||
<code>nixery.dev/shell/emacs25-nox</code>
|
|
||||||
</p>
|
|
||||||
<p>
|
|
||||||
Image tags are currently ignored. Every package name needs to
|
|
||||||
correspond to a key in the
|
|
||||||
<a href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/top-level/all-packages.nix">nixpkgs package set</a>.
|
|
||||||
</p>
|
|
||||||
<p>
|
|
||||||
The special meta-package <i>shell </i> provides default packages
|
|
||||||
you would expect in an interactive environment (such as an
|
|
||||||
interactively configured bash). If you use this package
|
|
||||||
you <b>must</b> specify it as the first package in an image.
|
|
||||||
</p>
|
|
||||||
<h3>FAQ</h3>
|
|
||||||
<ul>
|
|
||||||
<li>
|
|
||||||
<strong>Where is the source code for this?</strong>
|
|
||||||
<br>
|
|
||||||
Over <a href="https://github.com/google/nixery">on Github</a>.
|
|
||||||
</li>
|
|
||||||
<li>
|
|
||||||
<strong>Which revision of <code>nixpkgs</code> is used?</strong>
|
|
||||||
<br>
|
|
||||||
Nixery imports a Nix channel
|
|
||||||
via <code>builtins.fetchTarball</code>. Currently the channel
|
|
||||||
to which this instance is pinned is NixOS 19.03.
|
|
||||||
</li>
|
|
||||||
<li>
|
|
||||||
<strong>Is this an official Google project?</strong>
|
|
||||||
<br>
|
|
||||||
<strong>No.</strong> Nixery is not officially supported by
|
|
||||||
Google.
|
|
||||||
</li>
|
|
||||||
<li>
|
|
||||||
<strong>Can I depend on the demo instance in production?</strong>
|
|
||||||
<br>
|
|
||||||
<strong>No.</strong> The demo instance is just a demo. It
|
|
||||||
might go down, move, or disappear entirely at any point.
|
|
||||||
<br>
|
|
||||||
To make use of Nixery in your project, please deploy a private
|
|
||||||
instance. Stay tuned for instructions for how to do this on
|
|
||||||
GKE.
|
|
||||||
</li>
|
|
||||||
<li>
|
|
||||||
<strong>Who made this?</strong>
|
|
||||||
<br>
|
|
||||||
<a href="https://github.com/tazjin">tazjin</a>
|
|
||||||
</li>
|
|
||||||
</ul>
|
|
||||||
</body>
|
|
||||||
</html>
|
|
Loading…
Reference in a new issue