OpenZFS NAS (BSD, Illumos, Linux, OSX, Solaris, Windows + Storage Spaces) with napp-it web-gui

================================================================================
  napp-it cs -- Claude Desktop Setup (English)
  AI-assisted development with direct filesystem access,
  SSH tools and ZFS snapshot backup
  File: csweb-gui/_my/howto.ai/setup_claude_en.info
================================================================================

================================================================================
  Preword
================================================================================
napp-it is a copy and run user extendable web management suite to manage single
servers or whole servergroups. It consists of the frontend webserver (pure Perl)
and backend services for remote control via encrypted socket connections. There
are no requirements/ modifications outside the napp-it cs folder /opt/csweb-gui

Frontend and backend run on Free-BSD, Illumos, Linux, OSX, Solaris and Windows.


================================================================================
  OVERVIEW
================================================================================

This setup gives Claude full access to the napp-it cs project (C:\opt\csweb-gui)
without any ZIP upload/download cycle. Claude reads and edits files directly on
disk. Version control is handled via robocopy mirroring to ZFS snapshots on an
OmniOS/Illumos NAS.

Components:
  1. Claude Desktop for Windows       -- AI client with MCP extensions
  2. MCP Filesystem Extension         -- direct read/write access to C:\opt
  3. MCP Desktop Commander            -- Windows terminal, shell, processes
  4. SSH tools (PuTTY suite)          -- remote access to member servers
  5. Robocopy + ZFS snapshots         -- backup and versioning


================================================================================
  1. PREREQUISITES
================================================================================

  - Windows 10/11 (64-bit)
  - napp-it cs installed at C:\opt\csweb-gui
  - Strawberry Perl at C:\opt\perl (included in the napp-it cs package)
  - NAS / OmniOS host with ZFS reachable on LAN (here: 192.168.2.203)
  - SMB share "opt" on the NAS (\\192.168.2.203\opt) as sync target
  - Internet access for Claude Desktop download


================================================================================
  2. INSTALL CLAUDE DESKTOP
================================================================================

  1. Download: https://claude.ai/download  -> "Download for Windows"
  2. Run the installer (claude-setup.exe) -- no admin rights required
  3. Start Claude Desktop, sign in with your claude.ai account
     (Recommended: Claude Pro, approx. $17/month -- larger context window,
      no throttling during intensive development sessions)
  4. On first start the chat opens directly -- no further setup needed


================================================================================
  3. SET UP MCP FILESYSTEM EXTENSION
================================================================================

  The Filesystem extension gives Claude direct read/write access to selected
  directories -- no file upload needed.

  3.1  Install the extension

    Claude Desktop -> Menu (☰ top left) -> Settings -> Extensions
    -> Search "Filesystem" -> Install / Add

    Alternatively: Claude Desktop -> Settings -> Developer -> Edit Config
    Open: %APPDATA%\Claude\claude_desktop_config.json

  3.2  Configure allowed directories

    Edit the filesystem entry in claude_desktop_config.json:

    {
      "mcpServers": {
        "filesystem": {
          "command": "npx",
          "args": [
            "-y",
            "@modelcontextprotocol/server-filesystem",
            "C:\\opt"
          ]
        }
      }
    }

    This grants Claude access to C:\opt\ and all subdirectories.
    NOTE: C:\opt\ssh\ contains the private SSH key -- Claude only reads it
    for command construction and never writes to it.

  3.3  Restart Claude Desktop

    After changing claude_desktop_config.json: fully quit Claude Desktop
    (tray icon -> Quit) and restart.

  3.4  Test access

    In chat: "List the files in C:\opt" -- Claude should list the folders
    without any file having been uploaded.


================================================================================
  4. SET UP MCP DESKTOP COMMANDER (Windows Terminal / Shell)
================================================================================

  Desktop Commander gives Claude access to a persistent Windows shell
  (PowerShell/cmd), can start processes, search files, and more.

  4.1  Installation

    Claude Desktop -> Settings -> Extensions -> Search "Desktop Commander"
    -> Install

    Or manually in claude_desktop_config.json:

    {
      "mcpServers": {
        "desktop-commander": {
          "command": "npx",
          "args": ["-y", "@wonderwhy-er/desktop-commander"]
        }
      }
    }

  4.2  Restrict allowed directories (optional)

    Desktop Commander can execute commands system-wide. For tighter control:
    set allowedDirectories to ["C:\\opt"] in Desktop Commander settings.

  4.3  Typical use

    Claude can directly:
      - Run perl -c syntax checks
      - Start sync_version.bat
      - Call plink.exe / pscp.exe
      - Start/stop processes (server.pl, webserver.pl)
      - Tail logs (Get-Content ... -Wait)


================================================================================
  5. SET UP SSH TOOLS (PuTTY suite)
================================================================================

  SSH tools give Claude remote access to member servers and the NAS host
  for snapshot management and log analysis.

  5.1  Install PuTTY tools

    Place the following files under C:\opt\ssh\:
      plink.exe      SSH command-line client   -- from putty.org
      pscp.exe       SCP/SFTP file transfer    -- from putty.org
      puttygen.exe   Key conversion utility    -- from putty.org
      id_rsa.ppk     Private key (PuTTY format)

    Download: https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html
    -> download plink.exe, pscp.exe, puttygen.exe directly

  5.2  Create or convert an SSH key

    Option A -- Create a new key:
      Run puttygen.exe -> Generate -> move mouse -> Save private key
      -> save as C:\opt\ssh\id_rsa.ppk
      Copy the public key text from the text field

    Option B -- Convert an existing OpenSSH key:
      puttygen.exe -> Conversions -> Import Key -> id_rsa (OpenSSH format)
      -> Save private key -> C:\opt\ssh\id_rsa.ppk

  5.3  Deploy the public key to target hosts

    On each member server (root@HOST):
      mkdir -p ~/.ssh
      echo "ssh-rsa AAAA... your-key" >> ~/.ssh/authorized_keys
      chmod 600 ~/.ssh/authorized_keys

    Same on the NAS host (192.168.2.203).

  5.4  Test the connection

    In PowerShell / cmd:
      C:\opt\ssh\plink.exe -ssh -batch -i C:\opt\ssh\id_rsa.ppk root@192.168.2.203 hostname

    Expected: NAS hostname without any password prompt.
    On the very first connection: confirm the host key fingerprint once
    (stored in registry, -batch works afterwards without any prompts).

  5.5  Pre-accept host keys (required for -batch mode)

    Connect once WITHOUT -batch to store the host key:
      C:\opt\ssh\plink.exe -ssh -i C:\opt\ssh\id_rsa.ppk root@192.168.2.203 hostname
    -> Answer "Store key in cache? (y/n)" with y.
    All subsequent -batch calls work silently after that.


================================================================================
  6. ROBOCOPY SYNC + ZFS SNAPSHOT BACKUP
================================================================================

  6.1  Set up the SMB share on the NAS

    On the OmniOS/Illumos NAS:
      zfs create tank/daten1/opt           (or your pool name)
      zfs set sharesmb=name=opt tank/daten1/opt
      svcadm restart smb/server

    From Windows: \\192.168.2.203\opt should be accessible.
    Optionally map a drive letter:
      net use Z: \\192.168.2.203\opt /persistent:yes

  6.2  sync_version.bat

    File: C:\opt\sync_version.bat
    See the existing script (already present at C:\opt).

    The script:
      1. Creates ZFS snapshot daten1/opt@TIMESTAMP via plink.exe
      2. Runs robocopy C:\opt -> \\192.168.2.203\opt /MIR
      3. Excludes tmp\ and ssh\ from the sync
      4. Writes a log to C:\opt\sync_version.log

  6.3  Set up autosnap on the NAS (safety net)

    On the NAS -- ZFS autosnap every 15 minutes via cron:
      crontab -e
      */15 * * * * zfs snapshot daten1/opt@auto-$(date +\%Y\%m\%d_\%H\%M)

    Or configure via napp-it cs Jobs > Snap.
    Recommended retention: 8 days (approx. 768 snapshots).

  6.4  Snapshot recovery

    List available snapshots:
      C:\opt\ssh\plink.exe -ssh -batch -i C:\opt\ssh\id_rsa.ppk root@192.168.2.203 ^
        "ls /daten1/opt/.zfs/snapshot/ | tail -20"

    Restore a single file:
      C:\opt\ssh\pscp.exe -i C:\opt\ssh\id_rsa.ppk ^
        "root@192.168.2.203:/daten1/opt/.zfs/snapshot/TIMESTAMP/csweb-gui/PATH/TO/FILE" ^
        C:\opt\csweb-gui\PATH\TO\FILE

    After recovery: run perl -c on the restored file.


================================================================================
  7. CLAUDE DESKTOP -- GENERAL INSTRUCTIONS (System Prompt)
================================================================================

  Claude Desktop -> Menu -> Settings -> General Instructions for Claude:

  Recommended text:
  -----------------------------------------------------------------------
  napp-it cs project is at C:\opt\csweb-gui.
  At session start read the guideline: csweb-gui/data/howto.ai/guideline.info
  and all *.info files in that folder and in _my/howto.ai/.
  Before larger changes: run sync_version.bat and wait for success.
  For recovery: ZFS snapshots accessible via pscp.exe
  (see _my/howto.ai/extra.info).
  -----------------------------------------------------------------------

  These instructions apply automatically to every new chat.


================================================================================
  8. TYPICAL WORKFLOW (daily use)
================================================================================

  1. Start Claude Desktop
  2. Open a new chat
  3. Claude confirms automatically:
       - Project C:\opt\csweb-gui read
       - Guideline and all *.info files read
       - sync_version.log checked (backup current?)
       - admin.pl / server.pl version strings shown
  4. Describe the task (paste a screenshot if helpful)
  5. For larger changes: Claude runs sync_version.bat first
  6. Claude edits files directly (no ZIP upload needed)
  7. Reload the browser page -> changes visible immediately
  8. For server.pl changes: restart the backend via napp-it cs


================================================================================
  9. REMOTE ACCESS TO MEMBER SERVERS (logs, diagnostics)
================================================================================

  Read logs:
    plink.exe -ssh -batch -i C:\opt\ssh\id_rsa.ppk root@192.168.2.185 ^
      "tail -50 /opt/csweb-gui/tmp/error.log"

  ZFS status:
    plink.exe -ssh -batch -i C:\opt\ssh\id_rsa.ppk root@192.168.2.185 ^
      "zpool status"

  Fetch file from member:
    pscp.exe -i C:\opt\ssh\id_rsa.ppk ^
      root@192.168.2.185:/opt/csweb-gui/tmp/error.log ^
      C:\tmp\error_185.log

  Push file to member:
    pscp.exe -i C:\opt\ssh\id_rsa.ppk ^
      C:\opt\csweb-gui\data\cs_server\server.pl ^
      root@192.168.2.185:/opt/csweb-gui/data/cs_server/server.pl


================================================================================
  10. TROUBLESHOOTING
================================================================================

  Claude cannot see files in C:\opt
    -> Filesystem extension not installed or wrong path in config
    -> Check claude_desktop_config.json, restart Claude Desktop

  plink.exe asks for password
    -> Host key not yet accepted: connect once without -batch
    -> Wrong PPK key: puttygen.exe -> Load -> id_rsa.ppk -> Verify

  robocopy fails (access denied)
    -> Check SMB share: net use \\192.168.2.203\opt
    -> Store Windows credentials for the NAS:
       Control Panel -> Credential Manager -> Windows Credentials -> Add

  Claude edits the wrong files
    -> Always check: Claude reads _my/howto.ai/ last (overrides standard)
    -> Ask in chat: "Which file did you just edit?"

  modifier.js only 13 bytes ("# placeholder")
    -> Known issue: restore from last snapshot
    -> Use the pscp.exe command from extra.info

================================================================================