collabmd 0.1.18 → 0.1.20

package/README.md

@@ -1,26 +1,61 @@
 # CollabMD
 
-Browser collaboration for existing markdown folders, diagram files, and git-backed docs.
+Realtime collaboration for Markdown folders, diagrams, and git-backed docs, without migrating your files.
 
 <p align="center">
-  <img src="./docs/assets/collabmd-hero.png" alt="CollabMD showing a file tree, markdown editor, live preview, and collaborator presence." width="100%">
+  <img src="https://raw.githubusercontent.com/andes90/collabmd/master/docs/assets/collabmd-hero.webp" alt="CollabMD showing a file tree, markdown editor, live preview, and collaborator presence." width="100%">
 </p>
 
 <p align="center">
   <strong>Turn an existing markdown-and-diagram workspace into a realtime collaborative web app.</strong>
 </p>
 
-<p align="center">
-  No migration. Plain files stay on disk. Collaborators get live editing, source-anchored comments, chat, Markdown video embeds, Mermaid, PlantUML, Excalidraw, and vault-style navigation in the browser.
-</p>
+CollabMD turns a local Markdown folder, Obsidian-style vault, or docs repo into a collaborative workspace you can open in the browser.
+
+Throughout this guide, **vault** simply means a regular folder on your computer that contains Markdown files.
+
+- No migration: your files stay on disk
+- Your filesystem stays the source of truth: CollabMD does not move, rename, or delete files unless you explicitly do that in the app
+- Realtime editing with Yjs
+- Mermaid, PlantUML, and Excalidraw support
+- Source-anchored comments, chat, and presence
+- Works with plain folders, Obsidian-style vaults, and git-backed docs
+
+Requirements for the fastest first run:
+
+- Node.js 24 for `npx` and source installs
+- Homebrew only if you want the `brew install` path
+
+## Quick start
+
+```bash
+# Run locally first, no Cloudflare tunnel required
+npx collabmd@latest ~/my-vault --no-tunnel
+```
+
+Open `http://localhost:1234`.
+
+Expected startup output:
+
+```text
+CollabMD v0.x.y
+Vault:  /path/to/your-vault
+Local:  http://localhost:1234
+Tunnel: disabled
+Ready for collaboration. Press Ctrl+C to stop.
+```
+
+Prefer Homebrew or source install? Jump to [Installation options](#installation-options).
 
 ## See it in action
 
-![CollabMD live demo](./docs/assets/collabmd-demo.gif)
+See CollabMD editing the same workspace from two browsers in realtime:
 
-Prefer video? [Open the WebM demo](./docs/assets/collabmd-demo.webm).
+![Two browser windows editing the same markdown workspace in realtime](https://raw.githubusercontent.com/andes90/collabmd/master/docs/assets/collabmd-demo.gif)
 
-## Why teams use CollabMD
+Prefer video? [Open the WebM demo](https://raw.githubusercontent.com/andes90/collabmd/master/docs/assets/collabmd-demo.webm).
+
+## Features
 
 - **No migration** — point CollabMD at an existing markdown folder, diagram workspace, Obsidian-style vault, or git-backed docs repo
 - **Local-files-first** — your filesystem remains the source of truth
@@ -40,12 +75,22 @@ Prefer video? [Open the WebM demo](./docs/assets/collabmd-demo.webm).
 - Editing notes and diagrams together while keeping everything as plain files on disk
 - Giving browser access to collaborators who do not use your local markdown setup
 
-## Quick start
+## Installation options
 
 ### Requirements
 
-- macOS or Linux
-- Node.js 24 if installing from source
+- macOS, Linux, or Windows (via WSL2)
+- Node.js 24 for `npx` and source installs
+
+### Run via npx (Node.js)
+
+If you have Node.js installed, you can run CollabMD directly without installing it globally:
+
+```bash
+npx collabmd@latest ~/my-vault --no-tunnel
+```
+
+Open `http://localhost:1234`.
 
 ### Install with Homebrew
 
@@ -91,6 +136,16 @@ collabmd ~/my-vault --auth password
 
 If `cloudflared` is installed, CollabMD starts a quick tunnel by default unless you pass `--no-tunnel`.
 
+## Share with a collaborator
+
+If you want to share the workspace over the internet, start with password auth:
+
+```bash
+collabmd ~/my-vault --auth password
+```
+
+Then share the printed URL and password with your collaborator. If `cloudflared` is installed, CollabMD will start a quick tunnel automatically unless you pass `--no-tunnel`.
+
 ## Safety first
 
 - Treat the URL as write access to the vault unless you enable auth
@@ -98,6 +153,13 @@ If `cloudflared` is installed, CollabMD starts a quick tunnel by default unless
 - If `cloudflared` is installed, CollabMD may expose the app through a Cloudflare Quick Tunnel unless you pass `--no-tunnel`
 - `oidc` is reserved for a future implementation and is not usable yet
 
+## Current limitations
+
+- Single-instance deployment only: collaboration room state is kept in-process and is not shared across replicas
+- `oidc` auth is reserved for a future implementation and is not usable yet
+- Source-anchored comments currently support markdown, Mermaid, and PlantUML text files, but not `.excalidraw`
+- Windows use is supported via WSL2 rather than native Windows execution
+
 ## How it works
 
 ```bash
@@ -119,7 +181,7 @@ Comment threads are source-anchored and currently supported for markdown, Mermai
 
 Markdown video embeds are opt-in and use standard image syntax such as `![Video](https://www.youtube.com/watch?v=...)` or `![Video](https://cdn.example.com/demo.webm)`. The preview currently supports public YouTube URLs plus direct public `https` video files ending in `.mp4`, `.webm`, or `.ogg`. The editor toolbar also includes a `Video` action that inserts the same Markdown syntax for you.
 
-Your filesystem is the source of truth. CollabMD reads files from disk, uses Yjs for realtime collaboration, and writes plain text back to disk when the last editor disconnects.
+Your filesystem is the source of truth. CollabMD reads files from disk, uses Yjs for realtime collaboration, and continuously writes plain text back to disk as you type.
 
 ## Usage
 
@@ -139,7 +201,7 @@ collabmd [directory] [options]
 |--------|-------------|---------|
 | `-p, --port` | Port to listen on | `1234` |
 | `--host` | Host to bind to | `127.0.0.1` |
-| `--auth` | Auth strategy: `none`, `password`, `oidc` | `none` |
+| `--auth` | Auth strategy: `none`, `password`, `oidc` (`oidc` is reserved and not yet available) | `none` |
 | `--auth-password` | Password for `--auth password` | generated per run |
 | `--local-plantuml` | Start the bundled local docker-compose PlantUML service | off |
 | `--no-tunnel` | Don't start Cloudflare Tunnel | tunnel on |
@@ -171,11 +233,17 @@ collabmd --local-plantuml
 collabmd ~/Documents/Obsidian/MyVault
 ```
 
-## Cloudflare Tunnel
+## Public access
 
-When `cloudflared` is available, the CLI starts a [Cloudflare Quick Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/) by default so your vault is accessible from the internet. Since the editor uses same-origin WebSocket routing (`/ws/:file`), the tunnel works for both HTTP and collaboration traffic.
+CollabMD can optionally expose the session using a [Cloudflare Quick Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/). Since the editor uses same-origin WebSocket routing (`/ws/:file`), the tunnel works for both HTTP and collaboration traffic.
 
-If you are exposing the app through the tunnel, `collabmd --auth password` is the intended first-line protection. When you do not pass `--auth-password`, CollabMD generates a password for that host run and prints it in the terminal. Restarting the app rotates that password and the signed session secret.
+If you are exposing the session publicly, `collabmd --auth password` is the intended first-line protection. When you do not pass `--auth-password`, CollabMD generates a password for that host run and prints it in the terminal. Restarting the app rotates that password and the signed session secret.
+
+To share safely:
+
+```bash
+collabmd ~/my-vault --auth password
+```
 
 `cloudflared` is optional. Install it only if you want public tunnel access:
 
@@ -196,11 +264,14 @@ TUNNEL_TARGET_URL=http://127.0.0.1:4000 collabmd
 CLOUDFLARED_EXTRA_ARGS="--loglevel info" collabmd
 ```
 
+For the full runtime env var reference, see the `Environment variables` details block in the Development section below.
+
 ## Docker / Coolify deployment
 
+Published image: `ghcr.io/andes90/collabmd:latest`
+
 ```bash
-docker build -t collabmd .
-docker run -p 1234:1234 -v /path/to/vault:/data collabmd
+docker run -p 1234:1234 -v /path/to/vault:/data ghcr.io/andes90/collabmd:latest
 ```
 
 The container listens on `0.0.0.0:1234` and stores vault files at `/data`.
@@ -215,10 +286,10 @@ docker run \
   -e COLLABMD_GIT_SSH_PRIVATE_KEY_B64="$(base64 < ~/.ssh/id_ed25519 | tr -d '\n')" \
   -e COLLABMD_GIT_USER_NAME="CollabMD Bot" \
   -e COLLABMD_GIT_USER_EMAIL="bot@example.com" \
-  collabmd
+  ghcr.io/andes90/collabmd:latest
 ```
 
-For a full local and Docker test walkthrough, including key generation and deploy-key setup, see [docs/private-git-deployment.md](./docs/private-git-deployment.md).
+For a full local and Docker test walkthrough, including key generation and deploy-key setup, see [docs/private-git-deployment.md](https://github.com/andes90/collabmd/blob/master/docs/private-git-deployment.md).
 
 When `COLLABMD_GIT_REPO_URL` is set, CollabMD clones into `COLLABMD_VAULT_DIR` on first boot, then reuses that checkout on later starts. If the checkout already exists, startup validates that `origin` matches. Clean checkouts are fast-forwarded to the remote default branch; dirty checkouts are reused as-is and startup skips the sync.
 
@@ -237,7 +308,7 @@ docker run \
   -e COLLABMD_GIT_SSH_KNOWN_HOSTS_FILE=/run/secrets/collabmd_known_hosts \
   -e COLLABMD_GIT_USER_NAME="CollabMD Bot" \
   -e COLLABMD_GIT_USER_EMAIL="bot@example.com" \
-  collabmd
+  ghcr.io/andes90/collabmd:latest
 ```
 
 ### Local docker-compose with a private PlantUML server
@@ -246,16 +317,16 @@ The included `docker-compose.yml` runs a prebuilt CollabMD image together with a
 
 ```bash
 mkdir -p data/vault
-docker build -t collabmd:local .
 docker compose up
 ```
 
 Open `http://localhost:1234`.
 
-By default, compose uses `COLLABMD_IMAGE=collabmd:local`. To run the published GitHub Container Registry image instead:
+By default, compose uses `COLLABMD_IMAGE=ghcr.io/andes90/collabmd:latest`. If you want to test a local image while developing instead:
 
 ```bash
-COLLABMD_IMAGE=ghcr.io/<owner>/<repo>:latest docker compose up
+docker build -t collabmd:local .
+COLLABMD_IMAGE=collabmd:local docker compose up
 ```
 
 The PlantUML container is also published on loopback by default at `http://127.0.0.1:18080`, so the host-based CLI can reuse it with:
@@ -302,6 +373,16 @@ For a standard Coolify reverse-proxy setup, the default same-origin WebSocket ro
 
 Health check: `GET /health`
 
+## Troubleshooting
+
+- `npx collabmd@latest` fails immediately: confirm you are running Node.js 24, which is the supported runtime for source and npm usage
+- The app is reachable only from localhost: pass `--host 0.0.0.0` or set `HOST=0.0.0.0` when you intend to expose it on your network
+- Port `1234` is already in use: pass `--port 3000` or set `PORT` to another free port
+- Tunnel did not start: install `cloudflared`, or pass `--no-tunnel` to stay local-only
+- `--local-plantuml` fails: make sure Docker is installed and running, or point `PLANTUML_SERVER_URL` at another PlantUML server
+- Private git bootstrap fails on startup: verify `COLLABMD_GIT_REPO_URL` plus either `COLLABMD_GIT_SSH_PRIVATE_KEY_FILE` or `COLLABMD_GIT_SSH_PRIVATE_KEY_B64`
+- WSL2 path issues: run CollabMD against a directory inside your Linux filesystem when possible rather than a mounted Windows path
+
 ## Development
 
 Install dependencies:
@@ -420,6 +501,7 @@ scripts/
 | `HTTP_HEADERS_TIMEOUT_MS` | Header read timeout | `60000` |
 | `HTTP_REQUEST_TIMEOUT_MS` | Request timeout | `30000` |
 | `WS_HEARTBEAT_INTERVAL_MS` | Heartbeat interval for evicting dead clients | `30000` |
+| `WS_ROOM_IDLE_GRACE_MS` | Delay before closing empty collaboration rooms to disk | `15000` |
 | `WS_MAX_BUFFERED_AMOUNT_BYTES` | Max outbound buffer per WebSocket | `16777216` |
 | `WS_MAX_PAYLOAD_BYTES` | Max inbound WebSocket frame | `16777216` |
 | `CLOUDFLARED_BIN` | `cloudflared` binary path | `cloudflared` |
@@ -445,7 +527,7 @@ cp .env.example .env
 - `.obsidian`, `.git`, `.trash`, and `node_modules` directories are ignored.
 - Only `.md`, `.markdown`, and `.mdx` files are indexed.
 - PlantUML preview rendering is server-side and uses `PLANTUML_SERVER_URL`; point it at a self-hosted renderer if you do not want to use the public PlantUML service.
-- `docker compose up --build` uses the included local PlantUML service and avoids the public renderer by default. The initial git clone may also require a longer health-check grace period than a purely local vault.
+- `docker compose up` uses the included local PlantUML service and avoids the public renderer by default. The initial git clone may also require a longer health-check grace period than a purely local vault.
 - `collabmd --local-plantuml` and `npm run start:local-plantuml` will start the local PlantUML compose service first, then run CollabMD against `http://127.0.0.1:${PLANTUML_HOST_PORT:-18080}`.
 
 ## License

package/docker-compose.yml

@@ -1,6 +1,6 @@
 services:
   collabmd:
-    image: ${COLLABMD_IMAGE:-collabmd:local}
+    image: ${COLLABMD_IMAGE:-ghcr.io/andes90/collabmd:latest}
     depends_on:
       - plantuml
     environment:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "collabmd",
-  "version": "0.1.18",
+  "version": "0.1.20",
   "type": "module",
   "description": "Collaborative markdown vault — like Obsidian, but online. Serve any directory of markdown files for realtime collaborative editing.",
   "repository": {