From c77b5fb64ee0d02299eee3268da2ce56b6575f6c Mon Sep 17 00:00:00 2001
From: Zhaofeng Li <hello@zhaofeng.li>
Date: Sun, 29 Jan 2023 17:23:59 -0700
Subject: [PATCH] book/admin-guide: Add some docs on the NixOS module

---
 book/src/SUMMARY.md                      |  1 +
 book/src/admin-guide/README.md           |  6 ++
 book/src/admin-guide/deployment/nixos.md | 83 ++++++++++++++++++++++++
 3 files changed, 90 insertions(+)
 create mode 100644 book/src/admin-guide/deployment/nixos.md

diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md
index 5c5688b..bef7afc 100644
--- a/book/src/SUMMARY.md
+++ b/book/src/SUMMARY.md
@@ -4,6 +4,7 @@
 - [Tutorial](./tutorial.md)
 - [User Guide](./user-guide/README.md)
 - [Admin Guide](./admin-guide/README.md)
+    - [Deploying to NixOS](./admin-guide/deployment/nixos.md)
     - [Chunking](./admin-guide/chunking.md)
 - [FAQs](./faqs.md)
 - [Reference](./reference/README.md)
diff --git a/book/src/admin-guide/README.md b/book/src/admin-guide/README.md
index 641c6ee..85cf559 100644
--- a/book/src/admin-guide/README.md
+++ b/book/src/admin-guide/README.md
@@ -1,3 +1,9 @@
 # Admin Guide
 
 > This section is under construction.
+
+This section describes how to set up and administer an Attic Server.
+For a quick start, read the [Tutorial](../tutorial.md).
+
+- **[Deploying to NixOS](./deployment/nixos.md)** - Deploying to a NixOS machine
+- **[Chunking](./chunking.md)** - Configuring Content-Defined Chunking data deduplication in Attic
diff --git a/book/src/admin-guide/deployment/nixos.md b/book/src/admin-guide/deployment/nixos.md
new file mode 100644
index 0000000..27615d2
--- /dev/null
+++ b/book/src/admin-guide/deployment/nixos.md
@@ -0,0 +1,83 @@
+# Deploying to NixOS
+
+Attic provides [a NixOS module](https://github.com/zhaofengli/attic/blob/main/nixos/atticd.nix) that allows you to deploy the Attic Server on a NixOS machine.
+
+## Prerequisites
+
+1. A machine running NixOS
+1. _(Optional)_ A dedicated bucket on S3 or a S3-compatible storage service
+    - You can either [set up Minio](https://search.nixos.org/options?query=services.minio) or use a hosted service like [Backblaze B2](https://www.backblaze.com/b2/docs) and [Cloudflare R2](https://developers.cloudflare.com/r2).
+1. _(Optional)_ A PostgreSQL database
+
+## Generating the Credentials File
+
+The HS256 JWT secret can be generated with the `openssl` utility:
+
+```bash
+openssl rand 64 | base64 -w0
+```
+
+Create a file on the server containing the following contents:
+
+```
+ATTIC_SERVER_TOKEN_HS256_SECRET_BASE64="output from openssl"
+```
+
+Ensure the file is only accessible by root.
+
+## Importing the Module
+
+You can import the module in one of two ways:
+
+- Ad-hoc: Import the `nixos/atticd.nix` from [the repository](https://github.com/zhaofengli/attic).
+- Flakes: Add `github:zhaofengli/attic` as an input, then import `attic.nixosModules.atticd`.
+
+## Configuration
+
+> Note: These options are subject to change.
+
+```nix
+{
+  services.atticd = {
+    enable = true;
+
+    # Replace with absolute path to your credentials file
+    credentialsFile = "/etc/atticd.env";
+
+    settings = {
+      listen = "[::]:8080";
+
+      # Data chunking
+      #
+      # Warning: If you change any of the values here, it will be
+      # difficult to reuse existing chunks for newly-uploaded NARs
+      # since the cutpoints will be different. As a result, the
+      # deduplication ratio will suffer for a while after the change.
+      chunking = {
+        # The minimum NAR size to trigger chunking
+        #
+        # If 0, chunking is disabled entirely for newly-uploaded NARs.
+        # If 1, all NARs are chunked.
+        nar-size-threshold = 64 * 1024; # 64 KiB
+
+        # The preferred minimum size of a chunk, in bytes
+        min-size = 16 * 1024; # 16 KiB
+
+        # The preferred average size of a chunk, in bytes
+        avg-size = 64 * 1024; # 64 KiB
+
+        # The preferred maximum size of a chunk, in bytes
+        max-size = 256 * 1024; # 256 KiB
+      };
+    };
+  };
+}
+```
+
+After the new configuration is deployed, the Attic Server will be accessible on port 8080.
+It's highly recommended to place it behind a reverse proxy like [NGINX](https://nixos.wiki/wiki/Nginx) to provide HTTPS.
+
+## Operations
+
+The NixOS module installs the `atticd-atticadm` wrapper which runs the `atticadm` command as the `atticd` user.
+Use this command to [generate new tokens](../../reference/atticadm-cli.md#atticadm-make-token) to be distributed to users.