From 6b665138708424d4454b3f6359317a9d1bf23e62 Mon Sep 17 00:00:00 2001 From: Alexander Tomokhov Date: Wed, 10 Jan 2024 06:47:37 +0400 Subject: [PATCH] readme: how to update inputs of this flake --- README.md | 125 ++++++++++++++++++++++++++++-------------------------- 1 file changed, 64 insertions(+), 61 deletions(-) diff --git a/README.md b/README.md index 32a4b44..6f05b7b 100644 --- a/README.md +++ b/README.md @@ -1,67 +1,70 @@ # SelfPrivacy NixOS configuration -This is a NixOS config which builds a SelfPrivacy server distribution -based on data provided in `userdata/userdata.json`. +This configuration is not self-contained, as it needs to be plugged as an input of a top-level NixOS configuration flake (i.e. https://git.selfprivacy.org/SelfPrivacy/selfprivacy-nixos-template/). This flake outputs the following function: +```nix +nixosConfigurations-fun = + { hardware-configuration # hardware-configuration.nix file + , deployment # deployment.nix file + , userdata # nix attrset, obtained by fromJSON from userdata.json + , top-level-flake # `self`-reference of the top-level flake + , sp-modules # flake inputs of sp-modules flake + }: +``` +which returns one or more attributes, containing NixOS configurations (created with `nixpkgs.lib.nixosSystem`). (As of 2024-01-10 there is only a single configuration named `default`.) -JSON schema is provided in `userdata/schema.json` for reference. +## updating flake inputs -**hardware-configuration.nix is not included.** +We have 2 flake inputs: +- nixpkgs +- selfprivacy-api -Example JSON config: +Both get updated the same ways. -```json -{ - "backblaze": { - "accountId": "BACKBLAZE_KEY_ID", - "accountKey": "BACKBLAZE_ACCOUNT_KEY", - "bucket": "BACKBLAZE_BUCKET_NAME" - }, - "api": { - "token": "API_TOKEN", - "enableSwagger": false - }, - "bitwarden": { - "enable": true - }, - "cloudflare": { - "apiKey": "CF_TOKEN" - }, - "databasePassword": "DB_PASSWORD", - "domain": "DOMAIN", - "hashedMasterPassword": "HASHED_PASSWORD", - "hostname": "DOMAIN", - "nextcloud": { - "enable": true, - "adminPassword": "PASSWORD", - "databasePassword": "PASSWORD" - }, - "gitea": { - "enable": true - }, - "jitsi": { - "enable": true - }, - "ocserv": { - "enable": true - }, - "pleroma": { - "enable": true - }, - "timezone": "Europe/Moscow", - "resticPassword": "PASSWORD", - "ssh": { - "enable": true, - "rootSshKeys": [ - "ssh-ed25519 KEY user@host" - ], - "passwordAuthentication": true - }, - "username": "LUSER", - "users": [ - { - "hashedPassword": "OTHER_USER_HASHED_PASSWORD", - "username": "OTHER_USER" - } - ] -} -``` \ No newline at end of file +There are 2 methods: +1. specify input name only in a command, relying on URL inside `flake.nix` +2. specify input name and URL in a command, **overriding** whatever URL is inside `flake.nix` for the input to update (override) + +In any case a Nix flake input is specified using some special _references_ syntax, including URLs, revisions, etc, described in manual: https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-flake.html#examples. Such reference can be used inside `flake.nix` or as an argument to `nix flake` commands. When a new reference is encountered Nix downloads and extracts it to /nix/store. + +Before and after running `nix flake lock` (or `nix flake update`) commands you would most likely want to list current inputs using `nix flake metadata`, which are read from `flake.lock` file. Although, Nix should also print a diff between changed referrences once changed. + +`--commit-lock-file` option tells Nix commands to do `git commit flake.lock` automatically, creating a new commit for you. + +### method 1: update specific input + +Example: +```console +$ nix flake lock --update-input nixpkgs +$ nix flake lock --update-input selfprivacy-api +``` + +Depending on how "precise" the URL was speficied in `flake.nix`, with _unmodified_ `flake.nix` the result might be: +* URL with `rev` (sha1) parameter => nothing will update (as we're already at exact commit) +* URL with `ref` (branch) parameter => input will update to the latest commit of the specified branch +* URL without `rev` nor `ref` => input will update to the latest commit of a default branch! + +--- + +Once Nix 2.19 stabilizes, a different command _must_ be used for updating a single input, like this: +```console +$ nix flake update nixpkgs +``` + + +### method 2: override specific input + +Overriding is more powerful as it allows to change flake input reference to anything just in one command (not only update in the bounds of a branch or a repository). + +Example: +```console +$ nix flake lock --override-input nixpkgs github:nixos/nixpkgs?ref=nixos-23.11 +$ nix flake lock --override-input selfprivacy-api git+https://git.selfprivacy.org/SelfPrivacy/selfprivacy-rest-api.git?ref=flakes +``` + +Similarly to update mechanism (described above), depending on the "precision" of an URL, its update scope varies. + +Note, that subsequent calls of `nix flake lock --update-input ` or `nix flake update` (or `nix flake update INPUT` by Nix 2.19+) will update the input regardless of the prior override. The information about override is stored only in `flake.lock` (`flake.nix` is not altered by Nix). + +--- + +Note, that override does not update flake inputs recursively (say, you have a flake inside your flake input). For recursive updates only `nix flake lock --update-input` and `nix flake update` mechanisms are suitable. However, as of 2024-01-10 none of the current inputs contain other flakes, hence override mechanism is fine.