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
];

For now, Self Host Blocks has a hard dependency on sops-nix. I am working on removing that so you can use any secrets manager you want. Until then, you also need to import the sops-nix module:

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

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:

inputs.selfhostblocks.inputs.nixpkgs

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.

To avoid manually updating the nixpkgs version, the GitHub repository for Self Host Blocks tries to update the nixpkgs input daily, verifying all tests pass before accepting this new nixpkgs version. The setup is explained in this blog post.

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 }: {
    colmena =
      let
        system = "x86_64-linux";
      in {
        meta = {
          nixpkgs = import selfhostblocks.inputs.nixpkgs { inherit system; };
        };

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

The above snippet is very minimal as it assumes you have only one machine to deploy to, so nixpkgs is defined exclusively by the selfhostblocks input. It is more likely that you have multiple machines, 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 }: {
    colmena = {
      let
        system = "x86_64-linux";
      in {
        meta =
          nixpkgs = import nixpkgs { inherit system; };
          nodeNixpkgs = {
            machine2 = import selfhostblocks.inputs.nixpkgs { inherit system; };
          };
        };

        machine1 = ...;

        machine2 = { selfhostblocks, ... }: {
          imports = [
            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.