selfhostblocks/docs/usage.md

Usage

Flake

Self Host Blocks is available as a flake. To use it in your project, add the following flake input:

inputs.selfhostblocks.url = "github:ibizaman/selfhostblocks";

Then, in your nixosConfigurations, import the module with:

imports = [
  inputs.selfhostblocks.nixosModules.x86_64-linux.default
];

Substituter

You can also use the public cache as a substituter with:

nix.settings.trusted-public-keys = [
  "selfhostblocks.cachix.org-1:H5h6Uj188DObUJDbEbSAwc377uvcjSFOfpxyCFP7cVs="
];

nix.settings.substituters = [
  "https://selfhostblocks.cachix.org"
];

Follow Nixpkgs

Self Host Blocks provides its own nixpkgs input so both can be updated in lock step, ensuring maximum compatibility. It is recommended to use the following nixpkgs as input for your deployments. Also, patches can be applied by Self Host Blocks. To handle all this, you need the following code instead wherever you import nixpkgs:

let
  system = "x86_64-linux";
  originPkgs = selfhostblocks.inputs.nixpkgs;

  nixpkgs' = originPkgs.legacyPackages.${system}.applyPatches {
    name = "nixpkgs-patched";
    src = originPkgs;
    patches = selfhostblocks.patches.${system};
  };

  shbNixpkgs = import nixpkgs' {
    inherit system;
  };
in
  # ... Use shbNixpkgs

Advanced users can if they wish use a version of nixpkgs of their choosing but then we cannot guarantee Self Host Block won't use a non-existing option from nixpkgs.

Tag Updates

To pin Self Host Blocks to a release/tag, run the following snippet:

nix flake lock --override-input selfhostblocks github:ibizaman/selfhostblocks/v0.2.2

Updating Self Host Blocks to a new version can be done the same way.

Auto Updates

To avoid burden on the maintainers to keep nixpkgs input updated with upstream, the GitHub repository for Self Host Blocks updates the nixpkgs input every couple days, and verifies all tests pass before automatically merging the new nixpkgs version. The setup is explained in this blog post.

Example Deployment with Nixos-Rebuild

The following snippets show how to deploy Self Host Blocks using the standard deployment system nixos-rebuild.

{
  inputs = {
    selfhostblocks.url = "github:ibizaman/selfhostblocks";
  };

  outputs = { self, selfhostblocks }: {
    let
      system = "x86_64-linux";
      originPkgs = selfhostblocks.inputs.nixpkgs;

      nixpkgs' = originPkgs.legacyPackages.${system}.applyPatches {
        name = "nixpkgs-patched";
        src = originPkgs;
        patches = selfhostblocks.patches.${system};
      };

      shbNixpkgs = import nixpkgs' {
        inherit system;
      };
    in
      nixosConfigurations = {
        machine = shbNixpkgs.lib.nixosSystem {
          inherit system;
          modules = [
            selfhostblocks.nixosModules.${system}.default
          ];
        };
      };
  };
}

The above snippet assumes one machine to deploy to, so nixpkgs is defined exclusively by the selfhostblocks input. It is more likely that you have multiple machines, some not using Self Host Blocks, then you can do the following:

{
  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";

    selfhostblocks.url = "github:ibizaman/selfhostblocks";
  };

  outputs = { self, selfhostblocks }: {
    let
      system = "x86_64-linux";
      originPkgs = selfhostblocks.inputs.nixpkgs;
    
      nixpkgs' = originPkgs.legacyPackages.${system}.applyPatches {
        name = "nixpkgs-patched";
        src = originPkgs;
        patches = selfhostblocks.patches.${system};
      };

      shbNixpkgs = import nixpkgs' {
        inherit system;
      };
    in
      nixosConfigurations = {
        machine1 = nixpkgs.lib.nixosSystem {
        };

        machine2 = shbNixpkgs.lib.nixosSystem {
          system = "x86_64-linux";
          modules = [
            selfhostblocks.nixosModules.${system}.default
          ];
        };
      };
  };
}

In the above snippet, machine1 will use the nixpkgs version from your inputs while machine2 will use the nixpkgs version from selfhostblocks.

Example Deployment With Colmena

The following snippets show how to deploy Self Host Blocks using the deployment system Colmena.

{
  inputs = {
    selfhostblocks.url = "github:ibizaman/selfhostblocks";
  };

  outputs = { self, selfhostblocks }: {
    let
      system = "x86_64-linux";
      originPkgs = selfhostblocks.inputs.nixpkgs;
    
      nixpkgs' = originPkgs.legacyPackages.${system}.applyPatches {
        name = "nixpkgs-patched";
        src = originPkgs;
        patches = selfhostblocks.patches.${system};
      };

      shbNixpkgs = import nixpkgs' {
        inherit system;
      };
    in
      colmena = {
        meta = {
          nixpkgs = shbNixpkgs;
        };

        machine = { selfhostblocks, ... }: {
          imports = [
            selfhostblocks.nixosModules.${system}.default
          ];
        };
      };
  };
}

The above snippet assumes one machine to deploy to, so nixpkgs is defined exclusively by the selfhostblocks input. It is more likely that you have multiple machines, some not using Self Host Blocks, in this case you can use the colmena.meta.nodeNixpkgs option:

{
  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";

    selfhostblocks.url = "github:ibizaman/selfhostblocks";
  };

  outputs = { self, selfhostblocks }: {
    let
      system = "x86_64-linux";
      originPkgs = selfhostblocks.inputs.nixpkgs;
    
      nixpkgs' = originPkgs.legacyPackages.${system}.applyPatches {
        name = "nixpkgs-patched";
        src = originPkgs;
        patches = selfhostblocks.patches.${system};
      };

      shbNixpkgs = import nixpkgs' {
        inherit system;
      };
    in
      colmena = {
        meta = {
          nixpkgs = import nixpkgs { inherit system; };

          nodeNixpkgs = {
            machine2 = shbNixpkgs;
          };
        };

        machine1 = ...;

        machine2 = { selfhostblocks, ... }: {
          imports = [
            selfhostblocks.nixosModules.${system}.default
          ];

          # Machine specific configuration goes here.
        };
      };
  };
}

In the above snippet, machine1 will use the nixpkgs version from your inputs while machine2 will use the nixpkgs version from selfhostblocks.

Example Deployment with deploy-rs

The following snippets show how to deploy Self Host Blocks using the deployment system deploy-rs.

{
  inputs = {
    selfhostblocks.url = "github:ibizaman/selfhostblocks";
  };

  outputs = { self, selfhostblocks }: {
    let
      system = "x86_64-linux";
      originPkgs = selfhostblocks.inputs.nixpkgs;
      
      shbNixpkgs = originPkgs.legacyPackages.${system}.applyPatches {
        name = "nixpkgs-patched";
        src = originPkgs;
        patches = selfhostblocks.patches.${system};
      };

      shbPkgs = import shbNixpkgs { inherit system; };

      deployPkgs = import originPkgs {
        inherit system;
        overlays = [
          deploy-rs.overlay
          (self: super: {
            deploy-rs = {
              inherit (shbPkgs) deploy-rs;
              lib = super.deploy-rs.lib;
            };
          })
        ];
      };
    in
      nixosModules.machine = {
        imports = [
          selfhostblocks.nixosModules.${system}.default
        ];
      };

      nixosConfigurations.machine = shbNixpkgs.lib.nixosSystem {
        inherit system;
        modules = [
          self.nixosModules.machine
        ];
      };

      deploy.nodes.machine = {
        hostname = ...;
        sshUser = ...;
        sshOpts = [ ... ];
        profiles = {
          system = {
            user = "root";
            path = deployPkgs.deploy-rs.lib.activate.nixos self.nixosConfigurations.machine;
          };
        };
      };

      # From https://github.com/serokell/deploy-rs?tab=readme-ov-file#overall-usage
      checks = builtins.mapAttrs (system: deployLib: deployLib.deployChecks self.deploy) deploy-rs.lib;
  };
}

The above snippet assumes one machine to deploy to, so nixpkgs is defined exclusively by the selfhostblocks input. It is more likely that you have multiple machines, some not using Self Host Blocks, in this case you can do:

{
  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";

    selfhostblocks.url = "github:ibizaman/selfhostblocks";
  };

  outputs = { self, selfhostblocks }: {
    let
      system = "x86_64-linux";
      originPkgs = selfhostblocks.inputs.nixpkgs;
      
      shbNixpkgs = originPkgs.legacyPackages.${system}.applyPatches {
        name = "nixpkgs-patched";
        src = originPkgs;
        patches = selfhostblocks.patches.${system};
      };

      shbPkgs = import shbNixpkgs { inherit system; };

      deployPkgs = import originPkgs {
        inherit system;
        overlays = [
          deploy-rs.overlay
          (self: super: {
            deploy-rs = {
              inherit (shbPkgs) deploy-rs;
              lib = super.deploy-rs.lib;
            };
          })
        ];
      };
    in
      nixosModules.machine1 = {
        # ...
      };

      nixosModules.machine2 = {
        imports = [
          selfhostblocks.nixosModules.${system}.default
        ];
      };

      nixosConfigurations.machine1 = nixpkgs.lib.nixosSystem {
        inherit system;
        modules = [
          self.nixosModules.machine1
        ];
      };

      nixosConfigurations.machine2 = shbNixpkgs.lib.nixosSystem {
        inherit system;
        modules = [
          self.nixosModules.machine2
        ];
      };

      deploy.nodes.machine1 = {
        hostname = ...;
        sshUser = ...;
        sshOpts = [ ... ];
        profiles = {
          system = {
            user = "root";
            path = deployPkgs.deploy-rs.lib.activate.nixos self.nixosConfigurations.machine1;
          };
        };
      };
  
      deploy.nodes.machine2 = # Similar here

      # From https://github.com/serokell/deploy-rs?tab=readme-ov-file#overall-usage
      checks = builtins.mapAttrs (system: deployLib: deployLib.deployChecks self.deploy) deploy-rs.lib;
  };
}

In the above snippet, machine1 will use the nixpkgs version from your inputs while machine2 will use the nixpkgs version from selfhostblocks.

Secrets with sops-nix

This section complements the official sops-nix guide.

Managing secrets is an important aspect of deploying. You cannot store your secrets in nix directly because they get stored unencrypted and you don't want that. We need to use another system that encrypts secrets when storing in the nix store and then decrypts them on the target host upon system activation. sops-nix is one of such system.

Sops-nix works by encrypting the secrets file with at least 2 keys. Your private key and a private key from the target host. This way, you can edit the secrets and the target host can decrypt the secrets. Separating the keys this way is good practice because it reduces the impact of having one being compromised.

One way to setup secrets management using sops-nix:

1. Create your own private key that will be located in keys.txt. The public key will be printed on stdout.

   $ nix shell nixpkgs#age --command age-keygen -o keys.txt
   Public key: age1algdv9xwjre3tm7969eyremfw2ftx4h8qehmmjzksrv7f2qve9dqg8pug7
   

2. Get the target host's public key. We will use the key derived from the ssh key of the host.

   $ nix shell nixpkgs#ssh-to-age --command \
       sh -c 'ssh-keyscan -t ed25519 -4 <target_host> | ssh-to-age'
   # localhost:2222 SSH-2.0-OpenSSH_9.6
   age13wgyyae8epyw894ugd0rjjljh0rm98aurvzmsapcv7d852g9r5lq0pqfx8
   

3. Create a sops.yaml file that explains how sops-nix should encrypt the - yet to be created - secrets.yaml file. You can be creative here, but a basic snippet is:

   keys:
     - &me age1algdv9xwjre3tm7969eyremfw2ftx4h8qehmmjzksrv7f2qve9dqg8pug7
     - &target age13wgyyae8epyw894ugd0rjjljh0rm98aurvzmsapcv7d852g9r5lq0pqfx8
   creation_rules:
     - path_regex: secrets.yaml$
       key_groups:
       - age:
         - *me
         - *target
   

4. Create a secrets.yaml file that will contain the encrypted secrets as a Yaml file:

   $ SOPS_AGE_KEY_FILE=keys.txt nix run --impure nixpkgs#sops -- \
     secrets.yaml
   

   This will open your preferred editor. An example of yaml file is the following (secrets are elided for brevity):

   nextcloud:
       adminpass: 43bb4b...
       onlyoffice:
           jwt_secret: 3a10fce3...
   

   The actual file on your filesystem will look like so, again with data elided:

   nextcloud:
       adminpass: ENC[AES256_GCM,data:Tt99...GY=,tag:XlAqRYidkOMRZAPBsoeEMw==,type:str]
       onlyoffice:
           jwt_secret: ENC[AES256_GCM,data:f87a...Yg=,tag:Y1Vg2WqDnJbl1Xg2B6W1Hg==,type:str]
   sops:
       kms: []
       gcp_kms: []
       azure_kv: []
       hc_vault: []
       age:
           - recipient: age1algdv9xwjre3tm7969eyremfw2ftx4h8qehmmjzksrv7f2qve9dqg8pug7
             enc: |
               -----BEGIN AGE ENCRYPTED FILE-----
               YWdl...6g==
               -----END AGE ENCRYPTED FILE-----            
           - recipient: age13wgyyae8epyw894ugd0rjjljh0rm98aurvzmsapcv7d852g9r5lq0pqfx8
             enc: |
               -----BEGIN AGE ENCRYPTED FILE-----
               YWdl...RA==
               -----END AGE ENCRYPTED FILE-----            
       lastmodified: "2024-01-28T06:07:02Z"
       mac: ENC[AES256_GCM,data:lDJh...To=,tag:Opon9lMZBv5S7rRhkGFuQQ==,type:str]
       pgp: []
       unencrypted_suffix: _unencrypted
       version: 3.8.1
   

   To actually create random secrets, you can use:

   $ nix run nixpkgs#openssl -- rand -hex 64
   

5. Use sops-nix module in nix:

   imports = [
       selfhostblocks.inputs.sops-nix.nixosModules.default
   ];
   

6. Set default sops file:

   sops.defaultSopsFile = ./secrets.yaml;
   

   Setting the default this way makes all sops instances use that same file.

7. Reference the secrets in nix:

   shb.sops.secrets."nextcloud/adminpass".request = config.shb.nextcloud.adminPass.request;
   shb.nextcloud.adminPass.result = config.shb.sops.secrets."nextcloud/adminpass".result;
   

   The above snippet uses the secrets contract and sops block to ease the configuration.