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
• skeleton.md
• docs/05-build-plan.md

Default runtime model

                   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:

pnpm verify

Bootstrap clone-local runtime settings:

pnpm agent:bootstrap

Bring the self-hosted stack up, verify it, and tear it down:

pnpm stack:up
pnpm stack:verify
pnpm stack:down --volumes

Run the full loop:

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