selfhostblocks/docs/usage.md

# Usage {#usage}

## Flake {#usage-flake}

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

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

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:

```nix
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][1] 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][2].

[1]: https://github.com/ibizaman/selfhostblocks
[2]: https://blog.tiserbox.com/posts/2023-12-25-automated-flake-lock-update-pull-requests-and-merging.html

## Example Deployment With Colmena {#usage-example-colmena}

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

[3]: https://colmena.cli.rs

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

  outputs = { self, selfhostblocks }: {
    colmena = {
      meta =
        let
          system = "x86_64-linux";
        in {
          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:

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

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

  outputs = { self, selfhostblocks }: {
    colmena = {
      meta =
        let
          system = "x86_64-linux";
        in {
          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`.