mirror of
https://github.com/harivansh-afk/betterNAS.git
synced 2026-04-15 21:03:22 +00:00
Harivansh Rathi
b5f8ea9c52
Split node enrollment from export sync and issue Finder-compatible DAV credentials so the stack proves the real backend seam before any web UI consumes it.
114 lines
3.1 KiB
Markdown
114 lines
3.1 KiB
Markdown
# betterNAS
|
|
|
|
betterNAS is a self-hostable WebDAV stack for mounting NAS exports in Finder.
|
|
|
|
The default product shape is:
|
|
|
|
- `node-service` serves the real files from the NAS over WebDAV
|
|
- `control-server` owns auth, nodes, exports, grants, and mount profile issuance
|
|
- `web control plane` lets the user manage the NAS and get mount instructions
|
|
- `macOS client` starts as native Finder WebDAV mounting, with a thin helper later
|
|
|
|
For now, the whole stack should be able to run on the user's NAS device.
|
|
|
|
## Current repo shape
|
|
|
|
- `apps/node-agent`
|
|
- NAS-side Go runtime and WebDAV server
|
|
- `apps/control-plane`
|
|
- Go backend for auth, registry, and mount profile issuance
|
|
- `apps/web`
|
|
- Next.js web control plane
|
|
- `apps/nextcloud-app`
|
|
- optional Nextcloud adapter, not the product center
|
|
- `packages/contracts`
|
|
- canonical shared contracts
|
|
- `infra/docker`
|
|
- self-hosted local stack
|
|
|
|
The main planning docs are:
|
|
|
|
- [docs/architecture.md](./docs/architecture.md)
|
|
- [skeleton.md](./skeleton.md)
|
|
- [docs/05-build-plan.md](./docs/05-build-plan.md)
|
|
|
|
## Default runtime model
|
|
|
|
```text
|
|
self-hosted betterNAS on the user's NAS
|
|
|
|
+------------------------------+
|
|
| web control plane |
|
|
| Next.js UI |
|
|
+--------------+---------------+
|
|
|
|
|
v
|
|
+------------------------------+
|
|
| control-server |
|
|
| auth / nodes / exports |
|
|
| grants / mount profiles |
|
|
+--------------+---------------+
|
|
|
|
|
v
|
|
+------------------------------+
|
|
| node-service |
|
|
| WebDAV + export runtime |
|
|
| real NAS bytes |
|
|
+------------------------------+
|
|
|
|
user Mac
|
|
|
|
|
+--> browser -> web control plane
|
|
|
|
|
+--> Finder -> WebDAV mount URL from control-server
|
|
```
|
|
|
|
## Verify
|
|
|
|
Static verification:
|
|
|
|
```bash
|
|
pnpm verify
|
|
```
|
|
|
|
Bootstrap clone-local runtime settings:
|
|
|
|
```bash
|
|
pnpm agent:bootstrap
|
|
```
|
|
|
|
Bring the self-hosted stack up, verify it, and tear it down:
|
|
|
|
```bash
|
|
pnpm stack:up
|
|
pnpm stack:verify
|
|
pnpm stack:down --volumes
|
|
```
|
|
|
|
Run the full loop:
|
|
|
|
```bash
|
|
pnpm agent:verify
|
|
```
|
|
|
|
## Current end-to-end slice
|
|
|
|
The first proven slice is:
|
|
|
|
1. boot the stack with `pnpm stack:up`
|
|
2. verify it with `pnpm stack:verify`
|
|
3. get the WebDAV mount profile from the control plane
|
|
4. mount it in Finder with the issued credentials
|
|
|
|
If the stack is running on a remote machine, tunnel the WebDAV port first, then
|
|
use Finder `Connect to Server` with the tunneled URL.
|
|
|
|
## Product boundary
|
|
|
|
The default betterNAS product is self-hosted and WebDAV-first.
|
|
|
|
Nextcloud remains optional and secondary:
|
|
|
|
- useful later for browser/mobile/share surfaces
|
|
- not required for the core mount flow
|
|
- not the system of record
|