Files

T

darroyo ac07499e8d feat: bake version into binary and display in UI sidebar

- Inject VERSION via ldflags (-X main=web.Version=) and git short SHA
- Add /api/version endpoint returning {version, commit}
- Display version in Layout sidebar footer (v0.1.6 · 8cfd405)
- Add AGENTS.md section documenting SemVer policy and bump-before-push rule
- Bump VERSION 0.1.5 -> 0.1.6 in Makefile

2026-07-05 23:07:20 -04:00

2.8 KiB

Raw Blame History

nasctl — Agent Guidance

Build

make build      # frontend (Vite builds to internal/web/dist) + Go binary → bin/nasctl
make build-go   # Go only (requires internal/web/dist to exist)
make run        # dev run: uses .data/, NASCTL_EXEC_SYSTEM=false

The Vite config (web/vite.config.ts) outputs directly to internal/web/dist for Go embedding. Do not change outDir.

Testing

make test       # go test ./...

No separate frontend test command; no lint/typecheck Makefile targets.

Project Structure

cmd/nasctl/main.go — entrypoint, CLI flags
internal/web/ — HTTP server, handlers, embed.go (frontend assets)
internal/db/ — SQLite models and queries
internal/modules/samba/, nfs/, users/ — config generators and system executors
internal/engine/apply.go — dirty→apply orchestration
web/ — React frontend source (Vite + Tailwind + TypeScript)

Key Runtime Behaviors

Changes (shares, exports, users) are staged in SQLite and marked dirty; they require POST /api/apply to take effect.
NASCTL_EXEC_SYSTEM=false (default in dev via make run) prevents real system changes: no service reloads, no useradd, no smbpasswd.
In production, set NASCTL_EXEC_SYSTEM=true and ensure NASCTL_ALLOWED_ROOTS restricts share/export paths.

Environment Variables

Variable	Dev default	Production default
`NASCTL_ADDR`	`:8080`	`:8080`
`NASCTL_DB`	`./.data/nasctl.db`	`/var/lib/nasctl/nasctl.db`
`NASCTL_SMB_CONF`	`./.data/smb.conf`	`/etc/samba/smb.conf`
`NASCTL_EXPORTS`	`./.data/exports`	`/etc/exports`
`NASCTL_EXEC_SYSTEM`	`false`	`true`
`NASCTL_ALLOWED_ROOTS`	(empty)	(empty = any absolute path)
`NASCTL_IMPORT_ON_BOOT`	`false`	`true` to import existing `smb.conf` and `/etc/exports` on first boot

Frontend Dev

cd web && npm run dev   # Vite on :5173, proxies /api to :8080

Requires web/node_modules (run cd web && npm install first).

Releasing / Versioning

The project follows SemVer: MAJOR.MINOR.PATCH.

PATCH (0.1.5 → 0.1.6): bug fixes, no API changes.
MINOR (0.1.x → 0.2.0): new features, backward-compatible.
MAJOR (0.x → 1.0): breaking changes.

Bump before commit/push. Update VERSION?= in the Makefile before staging any release-worthy changes. The value is baked into the binary at build time via -ldflags -X github.com/darroyo/nasctl/internal/web.Version=$(VERSION) and surfaced in the UI sidebar footer and GET /api/version.

The short git SHA is also injected automatically via -X github.com/darroyo/nasctl/internal/web.Commit=$(shell git rev-parse --short HEAD).

Override at build time: make build VERSION=0.2.0-rc1.

When reviewing staged changes, always confirm the version bump matches the nature of the change (patch vs minor vs major).

2.8 KiB Raw Blame History