Skip to main content

​
Toolchain

The Brewfile pins the toolchain (go, just, golangci-lint, buf, sqlc, node@22, and pnpm). You also need Docker with Compose. Integration tests use Testcontainers.

​
Container engine

Docker is Filament’s default container engine for local infrastructure, image builds, and container-backed tests. For Podman users, select your existing installation before running Filament’s development commands:
This selects Podman for just infra, just images, and container-backed tests. Use the same selection for just infra down. Docker and Podman keep separate data. Podman uses the docker-compose provider. On macOS, tests require a rootful machine. Filament discovers its socket and configures privileged Ryuk automatically. On Linux, the Podman API socket must be available. Keep Ryuk enabled for test cleanup.

​
Workspace layout

The repository contains several Go modules joined by go.work, including the root module, cmd/, selected connectors and secret providers, and tests/. The justfile checks each module with GOWORK=off, so it is verified against its own go.mod rather than dependencies supplied only by the workspace.

​
The justfile is the dev CLI

Every routine task is a just recipe. These are the ones that matter day to day. Start just infra before just dev. The dev recipe runs migrations immediately, so the database must already be healthy. Formatting and linting take a mode argument, not a hyphenated name:
just format and just lint (no argument) fix in place. CI runs the granular equivalents (just go-lint check, just go-format check, just ui-lint check, and just ui-format check). See style and testing for the full lint and test story.
The justfile falls back to a hardcoded ENCRYPTION_KEY so just server works out of the box. It is a published dev credential — never reuse it outside local development.

​
Building the UI in

just binaries builds the server, standalone, and cli binaries with -tags embedui so the compiled UI ships inside them. A plain go build ./cmd/server without the tag serves a placeholder page at /, not the UI. just ui-dist produces the embeddable bundle on its own.