Improve docs

This commit is contained in:
Alex David 2025-07-11 11:16:47 -07:00
commit 2f6e7c3078
3 changed files with 158 additions and 6 deletions

View file

@ -190,10 +190,10 @@
RUNTIME_ARGS+=(--bind /foo /foo)
fi
${"''"}
```
If you create any resources in add-runtime that you want to automatically
clean up when the jail exits use [add-cleanup](#add-cleanup).
```
'';
__functor = _:
runtime: state: state // { runtime = "${state.runtime}\n${runtime}\n"; }

View file

@ -7,6 +7,16 @@
pkgs = import nixpkgs { system = "x86_64-linux"; };
lib = pkgs.lib;
repo = rec {
rev = if self ? rev then self.rev else lib.warn "Repo is dirty, links will not work!" "???";
shortRev = lib.substring 0 8 rev;
urls = {
base = "https://git.sr.ht/~alexdavid/jail.nix";
commit = "https://git.sr.ht/~alexdavid/jail.nix/commit/${rev}";
file = file: lineNr: "https://git.sr.ht/~alexdavid/jail.nix/tree/${rev}${file}#L${toString lineNr}";
};
};
formatCombinatorDoc = name: combinatorObj: let
attrPos = builtins.unsafeGetAttrPos "__functor" combinatorObj;
file = lib.removePrefix (toString ./..) attrPos.file;
@ -14,7 +24,7 @@
## ${name}
**${name} :: ${combinatorObj.sig}**
${if self ? rev then "[Source](https://git.sr.ht/~alexdavid/jail.nix/tree/${self.rev}${file}#L${toString attrPos.line})" else ""}
[Source](${repo.urls.file file attrPos.line})
${combinatorObj.doc}
@ -32,21 +42,38 @@
(lib.filterAttrs (_: v: !(v ? deprecated && v.deprecated)))
(lib.mapAttrsToList formatCombinatorDoc)
(lib.concatStringsSep "\n\n")
(docs: "# Combinators\n\n${docs}")
(docs: ''
# Combinators
${docs}
'')
];
mkdocsSettings = {
site_name = "jail-nix";
repo_url = "https://git.sr.ht/~alexdavid/jail.nix";
repo_url = repo.urls.base;
theme = {
name = "readthedocs";
hljs_languages = [ "nix" ];
};
# Copyright is placed directly into the page within a <p> tag.
# Concatenating with </p><p> here is super janky, but good enough for
# now.
copyright = lib.concatStringsSep "</p><p>" [
''
Copyright © 2025 Alex David ///
<a rel="license" href="https://creativecommons.org/licenses/by-nc-sa/4.0/">CC BY-NC-SA 4.0</a>.
''
''
This documentation was generated from the <a href="${repo.urls.base}">jail.nix repo</a>,
commit <a href="${repo.urls.commit}"><code>${repo.shortRev}</code></a>.
''
];
};
in {
packages.x86_64-linux.default = pkgs.runCommand "website" { buildInputs = [ pkgs.mkdocs ]; } ''
mkdir -p docs
cp ${../README.md} docs/index.md
cp -r ${./static-docs} docs
chmod -R +w docs
echo ${lib.escapeShellArg combinatorDocs} > docs/combinators.md
echo ${lib.escapeShellArg (builtins.toJSON mkdocsSettings)} > mkdocs.yml
mkdocs build

View file

@ -0,0 +1,125 @@
# Getting Started
## Installation
It is currently recommended to install jail.nix as a flake input to your
configuration:
```nix
# flake.nix
{
inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixos-24.11";
inputs.jail-nix.url = "sourcehut:~alexdavid/jail.nix";
outputs = { nixpkgs, jail-nix, ... }: {
# ...
};
}
```
## Initializing
The core functionality of jail.nix is a `jail` function that wraps derivations
in a bubblewrap jail. To set it up, you need to initialize the library with a
version of nixpkgs.
This is done by either calling `jail-nix.lib.init` for a basic setup, or
`jail-nix.lib.extend` for advanced configuration.
### Basic configuration
For a simple working `jail` function, call `jail-nix.lib.init` with an instantiated nixpkgs:
```nix
pkgs = import nixpkgs { system = "x86_64-linux"; };
jail = jail-nix.lib.init pkgs;
```
### Advanced configuration
You can set more options in the initialization with `jail-nix.lib.extend`.
You must pass in an instantiated nixpkgs attribute `pkgs`.
For example, the below snippet creates a `jail` function where `my-combinator`
is passed to jail definitions.
```nix
pkgs = import nixpkgs { system = "x86_64-linux"; };
jail = jail-nix.lib.extend {
inherit pkgs;
additionalCombinators = baseCombinators: with baseCombinators; [
my-combinator = compose [
(readonly "/foo")
(readonly "/bar")
];
];
};
jailed-hello = jail "jailed-hello" pkgs.hello (c: with c; [
my-combinator
]);
```
## Usage
Once you have an [initialized](#initializing) `jail` function, it takes the
following positional arguments:
* **name**: (String) - the nix store name of wrapper script that is generated.
* **executable to wrap**: (String or Derivation) - An entrypoint to jail, this can
be a derivation like `pkgs.hello`, or a string like
`"${pkgs.hello}/bin/hello"`. If a derivation is passed it will call
`nixpkgs.lib.getExe` on it to get the entrypoint.
* **combinators**: (Function returning a list of **Combinators**) - The third
argument allows you to control the permissions of the jail. By default, the
wrapped program runs with very few permissions and to get it to even work you
will need to define what you want it to have access to here. For convenience,
this is a function that passes all the available combinators.
## Examples
### Provide jail.nix as a module arg in a Nixos configuration:
It may be more ergonomic to provide the jail function as a module argument in
your Nixos configurations:
```nix
# flake.nix
{
inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixos-24.11";
inputs.jail-nix.url = "sourcehut:~alexdavid/jail.nix";
outputs = { nixpkgs, jail-nix, ... }: {
nixosConfigurations.my-nixos-host = nixpkgs.lib.nixosSystem {
system = "x86_64-linux";
modules = [
({ pkgs, ... }: { _module.args.jail = jail-nix.lib.init pkgs; })
# Now all modules have `jail` passed into them:
({ jail, ... }: {
environment.systemPackages = [
(jail "jailed-hello" pkgs.hello (c: []))
];
})
];
};
};
}
```
### Using jail.nix to jail a flake package
```nix
# flake.nix
{
inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixos-24.11";
inputs.jail-nix.url = "sourcehut:~alexdavid/jail.nix";
outputs = { nixpkgs, jail-nix, ... }: {
packages.x86_64-linux =
let
pkgs = import nixpkgs { system = "x86_64-linux"; };
jail = jail-nix.lib.init pkgs;
in {
my-jailed-package = jail "jailed-hello" pkgs.hello (c: []);
};
};
}
```