Differences

This shows you the differences between two versions of the page.

--- manuals:distributions:nixos:impermanence [2024/10/21 07:13] – aither
+++ manuals:distributions:nixos:impermanence [2026/07/12 20:30] (current) – Annotate vpsAdmin navigation paths and update interface labels aither
@@ Line 1: / Line 1: @@
+<page>manuals:distributions:nixos:impermanence</page>
 ====== NixOS Impermanence ======
-<note warning>
-This is a work in progress, impermanence is available only on staging (node1.stg)
-</note>
 This page describes usage of [[https://github.com/nix-community/impermanence|NixOS Impermanence]] module
-at vpsFree.cz.
+at vpsFree.cz. We support impermanence with root filesystem in a temporary ZFS dataset that is
+provided by our platform. It is necessary to move the Nix store to a subdataset, which can be
+done automatically [[#using_os_template|using the OS template for impermanence]], or you can
+set it up [[#manual_configuration|manually]].
+Please note that when you enable impermanence, the root file system is indeed temporary
+and its data reset on each VPS start. The temporary dataset also isn't backed up. Be mindful
+of where you store your data. If it isn't in a persistent location, it will be lost.
 ===== Using OS template =====
-vpsAdmin contains OS templates where the impermanence module is preconfigured.
+vpsAdmin contains OS templates where impermanence is preconfigured. When creating a new VPS,
-When creating a new VPS, choose the appropriate template (impermanence is in its name).
+choose the appropriate template (impermanence is in its name). The new VPS will have ''/nix''
-The new VPS will have ''/nix'' separated in a subdataset. The root dataset will be mounted
+separated in a subdataset. The root dataset will be mounted to ''/persistent'' and initial
-to ''/persistent'' and initial impermanence configuration will be deployed.
+flake-based NixOS configuration will be deployed to ''/etc/nixos'', see ''/etc/nixos/flake.nix''
-See ''/etc/nixos/configuration.nix''. Copy of the impermanence module is stored at
+and ''/etc/nixos/configuration.nix''. The template also writes ''/etc/nixos/flake.lock'', so
-''/etc/nixos/impermanence'', you might want to update it to the latest version, e.g. by cloning
+versions of vpsAdminOS, ''nixpkgs'' and impermanence are pinned together.
-the git repository to the same path:
-<code>
+Impermanence is included as a flake input. To update it, update the flake lock and rebuild
+the system:
+<code bash>
 cd /etc/nixos
-rm -rf impermanence
+nix flake lock --update-input impermanence
-git clone https://github.com/nix-community/impermanence
+nixos-rebuild switch --flake /etc/nixos#vps
 </code>
-Note reinstalling the VPS will be ineffective, as reinstall changes only the root dataset.
+Note that reinstalling the VPS will be ineffective, as reinstall changes only the root dataset.
 It will not touch the Nix store when it is moved to a subdataset. For the same reason, you
 cannot convert an existing VPS to impermanence using reinstall. The OS template will
@@ Line 35: / Line 41: @@
 ==== 2. Start the VPS in rescue mode ====
-In VPS details, use form **Boot VPS from template (rescue mode)**. It's best
+In VPS details, use form <vpsadmin-nav id="vps.boot-rescue.open">**Boot VPS from template (rescue mode)**</vpsadmin-nav>. It's best
 to choose a different distribution than NixOS, so that there's no ''/nix'' directory.
 Use e.g. Alpine or Debian.
@@ Line 57: / Line 63: @@
 every start. We must mount our persistent storage to ''/persistent''. This can be either
 the root dataset, or you can create another subdataset for that purpose. We'll use the root
-dataset. In VPS details, click on **Mount** link of the first listed dataset
+dataset. In VPS details, click on <vpsadmin-nav id="datasets.mount.open">**Mount**</vpsadmin-nav> link of the first listed dataset
 (its name is the VPS ID) and mount it to ''/persistent''.
@@ Line 63: / Line 69: @@
 Now restart the VPS, you will leave the rescue mode.
-==== 7. Edit your configuration and add the impermanence module ====
+==== 7. Edit your flake configuration and add impermanence ====
-Clone the impermanence module repository into ''/etc/nixos''. This requires git, if you
+vpsAdminOS templates enable flakes by default. Create ''/etc/nixos/flake.nix'' and
-don't have it in your system, you can use e.g. ''nix-shell -p git''.
+keep your local settings in ''/etc/nixos/configuration.nix''. The example below follows the
+stable ''nixpkgs'' branch used by vpsAdminOS. If you're using another stable release, use the
+matching ''nixos-YY.MM'' branch. If you're using NixOS unstable, replace
+''github:NixOS/nixpkgs/nixos-25.11'' with ''github:NixOS/nixpkgs/nixos-unstable'' and
+replace the stable container module line in the example with
+''vpsadminos.nixosModules.containerUnstable''.
-<code bash>
+<file nix /etc/nixos/flake.nix>
-cd /etc/nixos
+{
-git clone https://github.com/nix-community/impermanence.git
+  inputs = {
-</code>
+    vpsadminos.url = "github:vpsfreecz/vpsadminos";
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-25.11";
+    impermanence.url = "github:nix-community/impermanence";
+  };
-Extend your configuration and add the impermanence module:
+  outputs = { nixpkgs, vpsadminos, impermanence, ... }:
+    let
+      containerModule = "container_${builtins.replaceStrings [ "." ] [ "_" ] nixpkgs.lib.trivial.release}";
+    in
+    {
+      nixosConfigurations.vps = nixpkgs.lib.nixosSystem {
+        system = "x86_64-linux";
+        modules = [
+          vpsadminos.nixosModules.${containerModule}
+          impermanence.nixosModules.impermanence
+          ./configuration.nix
+        ];
+      };
+    };
+}
+</file>
+Then extend your configuration and add the persistence settings:
 <file nix /etc/nixos/configuration.nix>
-{ config, ... }:
+{ ... }:
 {
-  imports = [
-    ./impermanence/nixos.nix
-  ];
   environment.persistence."/persistent" = {
     hideMounts = true;
@@ Line 90: / Line 117: @@
     files = [
       "/etc/machine-id"
-      "/etc/shadow"
     ];
   };
 }
 </file>
+Ensure flakes are enabled, for example:
+<code nix>
+nix.settings.experimental-features = [
+  "nix-command"
+  "flakes"
+];
+</code>
 Note that ''/persistent'' must match the dataset mountpoint, but you can choose an arbitrary name
@@ Line 103: / Line 138: @@
 <code bash>
-nixos-rebuild boot
+nixos-rebuild boot --flake /etc/nixos#vps
 </code>
@@ Line 123: / Line 158: @@
 ''/'' is based in a temporary dataset, ''11327'' is used for ''/persistent'' and ''11327/nix''
 contains the Nix store.

Knowledge base

User Tools

Site Tools

Differences

Page Tools