bambuddy-nix/README.md

# bambuddy-nix

Nix packaging for [Bambuddy](https://github.com/maziggy/bambuddy) — a
self-hosted command center for Bambu Lab 3D printers (works offline via
Developer Mode, no cloud dependency).

This flake provides:

- **`packages.<system>.bambuddy`** — the app: FastAPI backend + prebuilt React
  frontend behind a single `bambuddy` launcher
- **`nixosModules.bambuddy`** — a `services.bambuddy` NixOS module
- **checks** — an import smoke test and NixOS VM integration tests

## Quick start (NixOS)

```nix
# flake.nix
{
  inputs.bambuddy-nix.url = "github:<you>/bambuddy-nix";

  outputs = { self, nixpkgs, bambuddy-nix, ... }: {
    nixosConfigurations.myhost = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [
        bambuddy-nix.nixosModules.default
        ./configuration.nix
      ];
    };
  };
}
```

```nix
# configuration.nix
services.bambuddy = {
  enable = true;
  port = 8000;          # web UI / API
  openFirewall = true;  # reachable from the LAN
};
```

The dashboard is then available at `http://<host>:8000`. Add your printer(s)
through the first-run wizard — the printer must be on the same LAN with
Developer Mode enabled.

### Module options

| Option | Default | Description |
| --- | --- | --- |
| `services.bambuddy.enable` | `false` | Enable the service |
| `services.bambuddy.package` | flake's `bambuddy` | Package to run |
| `services.bambuddy.host` | `"0.0.0.0"` | Bind address (use `127.0.0.1` behind a reverse proxy) |
| `services.bambuddy.port` | `8000` | Web UI / API port |
| `services.bambuddy.dataDir` | `/var/lib/bambuddy` | SQLite DB, print archive, plate calibration, logs |
| `services.bambuddy.openFirewall` | `false` | Open the web port for LAN access |
| `services.bambuddy.environment` | `{}` | Extra env vars (see upstream `.env.example`) |
| `services.bambuddy.environmentFile` | `null` | Env file for secrets (`MFA_ENCRYPTION_KEY`, OIDC, …) |
| `services.bambuddy.extraPackages` | `[]` | Extra tools on the service PATH (e.g. `tailscale`) |

The service runs as a `DynamicUser` with a `StateDirectory`, ships `ffmpeg`
on its PATH (timelapses/camera), grants `CAP_NET_BIND_SERVICE` (virtual
printer FTPS/RTSP ports), and starts after `network-online.target`.

### Reverse proxy

Bambuddy serves everything (UI, API, websockets, camera streams) on one port
with absolute `/assets` URLs — proxy `Location /` to `http://127.0.0.1:8000`
with websocket upgrade support.

## Running without NixOS

```sh
nix run .#bambuddy                 # binds 0.0.0.0:8000, state in ~/.local/share/bambuddy
PORT=9000 HOST=127.0.0.1 nix run .#bambuddy
```

## Tests

```sh
nix flake check                          # everything
nix build .#checks.x86_64-linux.bambuddy-import   # backend import smoke test
nix build .#checks.x86_64-linux.bambuddy-service  # NixOS VM integration test
```

The VM test boots two virtual machines: one with the default configuration
(checks `/health`, the React UI, static assets, manifest, SQLite/StateDirectory
init and cross-node firewall access) and one exercising the module options
(custom host/port, extra environment, loopback-only binding).

## Updating

The package pins an upstream release in `pkgs/bambuddy/default.nix`:

```nix
version = "1.2.5.7";
src = fetchFromGitHub {
  owner = "maziggy";
  repo = "bambuddy";
  rev = "<commit for v${version}>";
  hash = "sha256-...";
};
```

To bump: change `version` + `rev`, update `hash`, and refresh
`npmDepsHash` (a failed build prints the expected value).

## License

Bambuddy is AGPL-3.0; this packaging is provided under the same license.