Add Nix build system for reproducible builds and NixOS support

daveseddon · March 25, 2026, 5:56pm

G’day Metabase team!

This PR adds a complete Nix build system for Metabase, enabling reproducible builds and first-class support for the growing Nix/NixOS community. We'd love for this to land so Nix users can easily build, develop, and deploy Metabase.

This change has zero impact on your existing build system, CI, or development workflow. All Nix configuration lives in nix/, flake.nix, and flake.lock. The only modification to an existing file is .gitignore (one line removed to commit flake.lock for reproducibility).

What's included

Reproducible builds — nix build produces identical output regardless of host system
Dev shell — nix develop gives you JDK 21, Clojure, Node 22, Bun, PostgreSQL 18, and all other tools, zero manual setup
Fast incremental builds — the build is split into 7 cached sub-derivations (frontend, static-viz, translations, 17 individual drivers, uberjar), so changing a backend file doesn't rebuild the frontend and vice versa
Multi-arch OCI images — nix build .#oci-x86_64 (also aarch64, riscv64) produces streamable layered container images (~1.24 GB)
Integration tests — health check, API smoke, DB migration, OCI lifecycle, and NixOS MicroVM full lifecycle tests
Comprehensive docs — nix/readme.md covers everything from installation to troubleshooting
Formatter & checks — nix fmt and nix flake check for code quality

Why this matters

Nix has a large and growing community (NixOS is in the top 10 Linux distributions on DistroWatch). Adding Nix support:

Makes onboarding trivial — one command (nix develop) sets up the entire dev environment
Enables reproducible CI builds (exact same deps everywhere)
Provides container images without Docker-in-Docker complexity
Lets NixOS users package Metabase natively

File summary

Path	Description
`flake.nix`	Flake entry point — all build targets, dev shell, checks, formatter
`flake.lock`	Pinned nixpkgs for reproducibility
`.gitignore`	Removed `/flake.lock` (one line)
`nix/derivation/`	Sub-derivation pipeline (deps, frontend, static-viz, translations, drivers, uberjar)
`nix/oci/`	Multi-arch OCI container images with layered caching
`nix/microvms/`	NixOS MicroVM lifecycle tests
`nix/tests/`	Integration tests (health, API, migration, OCI)
`nix/shell-functions/`	Dev shell helpers (build, clean, database, navigation, validation)
`nix/packages.nix`	Dependency declarations
`nix/devshell.nix`	Development shell configuration
`nix/readme.md`	Full documentation

github.com/metabase/metabase

Add Nix build system for reproducible builds and NixOS support

master ← randomizedcoder:nix

opened 02:51AM - 25 Mar 26 UTC

randomizedcoder

+3345 -0

## Summary Hey Metabase team! 👋 This PR adds a complete Nix build system for M…etabase, enabling reproducible builds and first-class support for the growing Nix/NixOS community. We'd love for this to land so Nix users can easily build, develop, and deploy Metabase. **This change has zero impact on your existing build system, CI, or development workflow.** All Nix configuration lives in `nix/`, `flake.nix`, and `flake.lock`. The only modification to an existing file is `.gitignore` (one line removed to commit `flake.lock` for reproducibility). ### What's included - **Reproducible builds** — `nix build` produces identical output regardless of host system - **Dev shell** — `nix develop` gives you JDK 21, Clojure, Node 22, Bun, PostgreSQL 18, and all other tools, zero manual setup - **Fast incremental builds** — the build is split into 7 cached sub-derivations (frontend, static-viz, translations, 17 individual drivers, uberjar), so changing a backend file doesn't rebuild the frontend and vice versa - **Multi-arch OCI images** — `nix build .#oci-x86_64` (also aarch64, riscv64) produces streamable layered container images (~1.24 GB) - **Integration tests** — health check, API smoke, DB migration, OCI lifecycle, and NixOS MicroVM full lifecycle tests - **Comprehensive docs** — `nix/readme.md` covers everything from installation to troubleshooting - **Formatter & checks** — `nix fmt` and `nix flake check` for code quality ### Why this matters Nix has a large and growing community (NixOS is in the top 10 Linux distributions on DistroWatch). Adding Nix support: - Makes onboarding trivial — one command (`nix develop`) sets up the entire dev environment - Enables reproducible CI builds (exact same deps everywhere) - Provides container images without Docker-in-Docker complexity - Lets NixOS users package Metabase natively ### File summary | Path | Description | |------|-------------| | `flake.nix` | Flake entry point — all build targets, dev shell, checks, formatter | | `flake.lock` | Pinned nixpkgs for reproducibility | | `.gitignore` | Removed `/flake.lock` (one line) | | `nix/derivation/` | Sub-derivation pipeline (deps, frontend, static-viz, translations, drivers, uberjar) | | `nix/oci/` | Multi-arch OCI container images with layered caching | | `nix/microvms/` | NixOS MicroVM lifecycle tests | | `nix/tests/` | Integration tests (health, API, migration, OCI) | | `nix/shell-functions/` | Dev shell helpers (build, clean, database, navigation, validation) | | `nix/packages.nix` | Dependency declarations | | `nix/devshell.nix` | Development shell configuration | | `nix/readme.md` | Full documentation | ## Test plan - [x] `nix flake show` — all outputs evaluate correctly - [x] `nix build .#oci-x86_64` — OCI image builds and loads into Docker (~1.24 GB) - [x] `nix fmt` — all Nix files pass formatting - [ ] `nix flake check` — formatting + build smoke + integration tests - [ ] `nix develop` — dev shell enters with all tools available 🤖 Generated with [Claude Code](https://claude.com/claude-code)

I have carefully separated out the drivers, so that once this is merged, I can start working on debugging and fixing the clickhouse driver. e.g. I want to address Metabase > x10 times slower than the SQL query?

Thanks,

Dave