From 77e5925bed7b6eb28bc7ef510d07a87e0b4e66bf Mon Sep 17 00:00:00 2001
From: Ethan Girouard <ethan@girouard.com>
Date: Thu, 30 Jul 2026 18:32:07 -0400
Subject: [PATCH] Add documentation

---
 README.md | 56 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 56 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..c15924d
--- /dev/null
+++ b/README.md
@@ -0,0 +1,56 @@
+# zfs-containers
+Use ZFS datasets in NixOS containers
+
+`zfs zone` allows you to attach ZFS datasets to user namespaces. Specific datasets on the host can be used within a `systemd-nspawn` container, including mounting, creating sub-datasets, and changing properties (with some limitations).
+
+## Usage
+
+### Add to flake inputs
+```nix
+inputs.zfs-containers.url = "git+https://gitea.mregirouard.com/nix/zfs-containers.git";
+```
+
+### Add module
+```nix
+nixosConfigurations.my-system = nixpkgs.lib.nixosSystem {
+  modules = [
+    inputs.zfs-containers.nixosModules.default
+
+    # ...
+  ];
+
+  # ...
+};
+```
+
+### Create containers
+```nix
+containers.my-container = {
+  zfs_datasets = [
+    "tank/data"
+  ];
+
+  # ...
+};
+```
+
+### Use ZFS datasets
+```
+$ sudo machinectl shell my-container
+
+[root@my-container:~]# zfs list
+NAME      USED  AVAIL  REFER  MOUNTPOINT
+tank      180G   820G    96K  none
+tank/data  96K   820G    96K  none
+
+[root@my-container:~]# zfs create tank/data/files
+
+# ...
+```
+
+## Systemd Target
+ZFS datasets will not immediately become available on container startup. A systemd target `zfs` will be created in the container that will become active when all datasets have been attached to the container. For services that depend on dataset availability, set `Requires = zfs.target` in your unit file.
+
+## Relevant Documentation
+[NixOS Containers](https://wiki.nixos.org/wiki/NixOS_Containers)<br>
+[ZFS Zone](https://openzfs.github.io/openzfs-docs/man/v2.2/8/zfs-zone.8.html)