The default module imports all modules except the SOPS module. That module is only needed if you want to use sops-nix to manage secrets.

You can also import each module individually. You might want to do this to only import SHB overlays if you actually intend to use them. Importing the nextcloud module for example will anyway transitively import needed support modules so you can’t go wrong:

         modules = [
-          selfhostblocks.nixosModules.default
+          selfhostblocks.nixosModules.nextcloud
           ./configuration.nix
         ];

To list all modules, run:

$ nix flake show github:ibizaman/selfhostblocks --allow-import-from-derivation

...

├───nixosModules
│   ├───arr: NixOS module
│   ├───audiobookshelf: NixOS module
│   ├───authelia: NixOS module
│   ├───borgbackup: NixOS module
│   ├───davfs: NixOS module
│   ├───default: NixOS module
│   ├───deluge: NixOS module
│   ├───forgejo: NixOS module
│   ├───grocy: NixOS module
│   ├───hardcodedsecret: NixOS module
│   ├───hledger: NixOS module
│   ├───home-assistant: NixOS module
│   ├───immich: NixOS module
│   ├───jellyfin: NixOS module
│   ├───karakeep: NixOS module
│   ├───lib: NixOS module
│   ├───lldap: NixOS module
│   ├───mitmdump: NixOS module
│   ├───monitoring: NixOS module
│   ├───nextcloud-server: NixOS module
│   ├───nginx: NixOS module
│   ├───open-webui: NixOS module
│   ├───paperless: NixOS module
│   ├───pinchflat: NixOS module
│   ├───postgresql: NixOS module
│   ├───restic: NixOS module
│   ├───sops: NixOS module
│   ├───ssl: NixOS module
│   ├───tinyproxy: NixOS module
│   ├───vaultwarden: NixOS module
│   ├───vpn: NixOS module
│   └───zfs: NixOS module

...

To add your own patches on top of the patches provided by SHB, you can remove the patchedNixpkgs line and instead apply the patches yourself:

-    nixpkgs' = selfhostblocks.lib.${system}.patchedNixpkgs;
+    pkgs = import selfhostblocks.inputs.nixpkgs {
+      inherit system;
+    };
+    nixpkgs' = pkgs.applyPatches {
+      name = "nixpkgs-patched";
+      src = selfhostblocks.inputs.nixpkgs;
+      patches = selfhostblocks.lib.${system}.patches;
+    };
+    nixosSystem' = import "${nixpkgs'}/nixos/lib/eval-config.nix";
   in
     nixosConfigurations = {
-      myserver = nixpkgs'.nixosSystem {
+      myserver = nixosSystem' {

SHB applies its own overlays using nixpkgs.overlays. Each module provided by SHB set that option if needed.

If you don’t want to have those overlays applied for modules you don’t intend to use SHB for, you will want to avoid importing the default module and instead import only the module for the services or blocks you intend to use, like shows in the Modules section.

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

SHB does not necessarily attempt to provide only free packages. Currently, the only module using unfree modules is the Open WebUI one.

To be able to use that module, you can follow the nixpkgs manual and set either:

{
  nixpkgs.config.allowUnfree = true;
}

or the option nixpkgs.config.allowUnfreePredicate.

To pin SHB to a release/tag, you can either use an implicit or explicit way.

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

nix flake update selfhostblocks \
  --override-input selfhostblocks github:ibizaman/selfhostblocks/0.7.1

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

To avoid burden on the maintainers to keep nixpkgs input updated with upstream, the GitHub repository for SHB 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.

The selfhostblocks.nixosModules.lib module adds a module argument called shb by setting the _module.args.shb option. It is imported by nearly all other SHB modules but you could still import it on its own if you want to access SHB’s functions and no other module.

The library of functions is also available under the traditional selfhostblocks.lib flake output.

The functions layout is, in pseudo-code:

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

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

  outputs = { self, selfhostblocks }: let
    system = "x86_64-linux";
    nixpkgs' = selfhostblocks.lib.${system}.patchedNixpkgs;
  in {
    nixosConfigurations = {
      machine = nixpkgs'.nixosSystem {
        inherit system;
        modules = [
          selfhostblocks.nixosModules.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 SHB, 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";
      nixpkgs' = selfhostblocks.lib.${system}.patchedNixpkgs;
    in
      nixosConfigurations = {
        machine1 = nixpkgs.lib.nixosSystem {
        };

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

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

The following snippets show how to deploy SHB using the deployment system Colmena.

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

  outputs = { self, selfhostblocks }: {
    let
      system = "x86_64-linux";
      nixpkgs' = selfhostblocks.lib.${system}.patchedNixpkgs;
      pkgs' = import nixpkgs' {
        inherit system;
      };
    in
      colmena = {
        meta = {
          nixpkgs = pkgs';
        };

        machine = { selfhostblocks, ... }: {
          imports = [
            selfhostblocks.nixosModules.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 SHB, 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";
      pkgs = import nixpkgs {
        inherit system;
      };

      nixpkgs' = selfhostblocks.lib.${system}.patchedNixpkgs;
      pkgs' = import nixpkgs' {
        inherit system;
      };
    in
      colmena = {
        meta = {
          nixpkgs = pkgs;

          nodeNixpkgs = {
            machine2 = pkgs';
          };
        };

        machine1 = ...;

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

The following snippets show how to deploy SHB using the deployment system deploy-rs.

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

  outputs = { self, selfhostblocks }: {
    let
      system = "x86_64-linux";
      nixpkgs' = selfhostblocks.lib.${system}.patchedNixpkgs;
      pkgs' = import nixpkgs' {
        inherit system;
      };

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

      nixosConfigurations.machine = nixpkgs'.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 SHB, 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";
      nixpkgs' = selfhostblocks.lib.${system}.patchedNixpkgs;
      pkgs' = import nixpkgs' {
        inherit system;
      };

      deployPkgs = import selfhostblocks.inputs.nixpkgs {
        inherit system;
        overlays = [
          deploy-rs.overlay
          (self: super: {
            deploy-rs = {
              inherit (pkgs') deploy-rs;
              lib = super.deploy-rs.lib;
            };
          })
        ];
      };
    in
      nixosModules.machine1 = {
        # ...
      };

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

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

      nixosConfigurations.machine2 = nixpkgs'.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.