darroyo
ac07499e8d
- 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
76 lines
2.8 KiB
Markdown
76 lines
2.8 KiB
Markdown
# nasctl — Agent Guidance
|
|
|
|
## Build
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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).
|