diff --git a/combinators.nix b/combinators.nix index 5b00ed5..71b0a4d 100644 --- a/combinators.nix +++ b/combinators.nix @@ -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"; } diff --git a/website/flake.nix b/website/flake.nix index 7a37da7..7397a7e 100644 --- a/website/flake.nix +++ b/website/flake.nix @@ -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
tag. + # Concatenating with
here is super janky, but good enough for + # now. + copyright = lib.concatStringsSep "
" [
+ ''
+ Copyright © 2025 Alex David ///
+ CC BY-NC-SA 4.0.
+ ''
+ ''
+ This documentation was generated from the jail.nix repo,
+ commit ${repo.shortRev}.
+ ''
+ ];
};
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
diff --git a/website/static-docs/index.md b/website/static-docs/index.md
new file mode 100644
index 0000000..1e12c7d
--- /dev/null
+++ b/website/static-docs/index.md
@@ -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: []);
+ };
+ };
+}
+```