Document some previous github issues and their workarounds

Author: elonen

FEATURES.md

@@ -2,6 +2,20 @@
 
 Clapshot is a self-hosted video/media review and annotation platform designed for collaborative content review workflows. This feature listing provides end-users and system administrators with an overview of Clapshot's capabilities.
 
+## Platform Support
+
+**Recommended Environment:**
+- **Desktop browsers:** Chrome/Chromium recommended for full compatibility
+- **Operating systems:** Works on Windows, macOS, Linux
+
+**Mobile Browser Limitations:**
+- ⚠️ **Limited mobile support:** Clapshot is a desktop-first application
+- **iOS/iPad issues:** Double-tap doesn't open videos/folders, video player controls may not function properly
+- **Touch interface:** Drawing annotation submission fails on mobile browsers
+- **Recommendation:** Use desktop browsers for production work; mobile browsers for viewing only
+
+For details, see [GitHub issue #68](https://github.com/elonen/clapshot/issues/68).
+
 ## Web Client UX
 
 ### **Video Player**

README.md

@@ -25,12 +25,12 @@ Clapshot is an open-source, self-hosted tool for collaborative video/media revie
 
 *For a comprehensive feature list, see [FEATURES.md](FEATURES.md).*
 
+![Video listing screenshot](doc/video-list.webp)
+
 ### When not to use Clapshot
 
 If you don't require local hosting, or are not adept in networking and Linux, consider commercial cloud services which may offer more user-friendly interfaces and additional features out of the box.
 
-![Video listing screenshot](doc/video-list.webp)
-
 ## Demo
 
 **Quick Start with Docker:**
@@ -56,6 +56,22 @@ The multi-user demo uses [PHP htadmin](https://github.com/soster/htadmin) for us
 > **Note:** Chrome/Chromium works best. If accessing from a different machine, configure the `CLAPSHOT_SERVER__URL_BASE` environment variable (or legacy `CLAPSHOT_URL_BASE`). See the [Quick Start Reference](doc/quick-start-reference.md) for common deployment scenarios.
 
 
+### Known Limitations
+
+**Browser Compatibility:**
+- **Desktop-first design:** Chrome/Chromium recommended for best compatibility
+- **Mobile browsers:** Limited support - double-tap to open doesn't work on iOS/iPad, video player controls may not function properly, drawing annotations fail. Use desktop browsers for full functionality.
+
+**Reverse Proxy Considerations:**
+- **IIS:** Hard 2GB file upload limit (use monitored folder ingestion for larger files)
+- **Cloudflare free tier:** ~100 second upload timeout can interrupt large file uploads
+
+For large file uploads with these proxies, use the [monitored folder ingestion](doc/sysadmin-guide.md#monitored-folder-ingestion) feature with SFTP/SMB instead of HTTP uploads.
+
+**Authentication:**
+- **PHP htadmin:** The included htadmin example is simplistic and limited for user management and security. For production deployments, consider integrating with a modern identity provider (OAuth, LDAP, Kerberos, SAML, etc.) via reverse proxy. See [Advanced Authentication](doc/sysadmin-guide.md#advanced-authentication).
+
+
 ## Simple Small-business Production Deployments
 
 Here are two alternative ways to deploy Clapshot + PHP Htadmin into a light production use:

doc/connection-troubleshooting.md

@@ -182,6 +182,79 @@ CAUTION: Using '*' in production could expose your users' data to malicious acto
 docker run ... -e CLAPSHOT_CORS="https://yourdomain.com" ...
 ```
 
+### 5. Large File Upload Failures
+
+**Symptoms:**
+- Uploads fail at ~1.5-2GB or after ~100 seconds
+- Error in logs: `Upload failed: error reading a body from connection: end of file before message length reached`
+- Upload progress stops and times out
+
+#### A. IIS Reverse Proxy Limitations
+
+**Problem:** Microsoft IIS has a hard-coded 2GB upload limit that cannot be easily bypassed.
+
+**Solutions:**
+
+1. **Switch to a different reverse proxy** (Recommended)
+   - Use Nginx, Apache, or Caddy instead of IIS
+   - These proxies support larger file uploads with proper configuration
+
+2. **Use monitored folder ingestion** (Workaround)
+
+   Edit `/etc/clapshot-server.conf`:
+   ```ini
+   [general]
+   ingest-username-from = folder-name
+   ```
+
+   If using Docker instead:
+   ```bash
+   docker run ... -e CLAPSHOT_SERVER__INGEST_USERNAME_FROM=folder-name ...
+   ```
+
+   - Set up SFTP/SMB access to the `incoming/` directory
+   - Create subdirectories named after usernames: `incoming/alice/`, `incoming/bob/`
+   - Users upload files to their directories (via SFTP/FTP/SMB)
+   - Clapshot automatically detects and processes files based on folder name
+   - See [Monitored Folder Ingestion](sysadmin-guide.md#monitored-folder-ingestion) for details
+
+**Important:** File permissions must allow `www-data` (or Clapshot server user) to move files during processing.
+
+#### B. Cloudflare Limitations
+
+**Problem:** Cloudflare free tier enforces a ~100 second upload timeout that can interrupt large file uploads.
+
+**Warning from README:**
+> Cloudflare – at least in the free plan – apparently limits HTTP upload times and/or sizes, so double check their offerings if you are planning to use this option for a production deployment.
+
+**Solutions:**
+
+1. **Use Cloudflare paid plans** with higher limits
+2. **Use monitored folder ingestion** (same configuration as above)
+3. **Use a different tunnel/proxy solution** for large file uploads
+4. **Split your setup:**
+   - Cloudflare for web UI access
+   - Direct connection or VPN for file uploads
+
+#### C. Other Reverse Proxy Considerations
+
+Ensure your reverse proxy is configured for large uploads:
+
+**Nginx:**
+```nginx
+client_max_body_size 50G;
+client_body_buffer_size 256K;
+proxy_request_buffering off;
+proxy_read_timeout 3600s;
+proxy_send_timeout 3600s;
+```
+
+**Apache:**
+```apache
+LimitRequestBody 53687091200  # 50GB in bytes
+ProxyTimeout 3600
+```
+
 ## Step-by-Step Troubleshooting
 
 ### Step 1: Check Server Status

llms.txt

@@ -23,10 +23,14 @@ When helping Clapshot users:
 5. **Environment variables vs config files** - Docker uses `CLAPSHOT_SERVER__*` environment variables; Debian uses `/etc/clapshot-server.conf`. Both achieve the same result. Legacy variable names like `CLAPSHOT_URL_BASE` still work but `CLAPSHOT_SERVER__URL_BASE` is preferred.
 
 6. **Known limitations** - Currently optimized for desktop browsers (Chrome/Chromium recommended). Mobile browser support is incomplete (touch events, video playback). This is a known limitation documented in issue #68.
+   - **Mobile browsers:** Double-tap doesn't open videos/folders on iOS/iPad, video player controls may not work properly, drawing submit fails. This is a desktop-first application.
+   - **Cloudflare free tier:** ~100 second upload timeout can cause large file uploads to fail
+   - **IIS reverse proxy:** 2GB upload limit cannot be easily bypassed; use monitored folder ingestion instead
 
 7. **Customization options** - While Clapshot doesn't support extensive CSS theming (Tailwind-based UI), you CAN customize:
    - **Branding:** Application title and logo via `CLAPSHOT_APP_TITLE` and `CLAPSHOT_LOGO_URL` environment variables
-   - **Media processing:** Transcoding and thumbnailing are handled by bash scripts that can be customized or replaced. Edit `/etc/clapshot-transcode.conf` to override ffmpeg settings (hardware acceleration, codecs, bitrates) or provide custom scripts via `--transcode-script` and `--thumbnail-script` arguments. See doc/transcoding.md for details.
+   - **Media processing:** Transcoding and thumbnailing are handled by bash scripts that can be customized or replaced. Edit `/etc/clapshot-transcode.conf` to override ffmpeg settings (hardware acceleration via Intel QSV, NVIDIA NVENC, VA-API, Apple VideoToolbox, or custom codecs/bitrates) or provide custom scripts via `--transcode-script` and `--thumbnail-script` arguments. See doc/transcoding.md for details.
+   - **Upload permissions:** Control per-user upload permissions via `X-Remote-User-Can-Upload` HTTP header from reverse proxy. See doc/sysadmin-guide.md#upload-permission-control
 
 ## What is Clapshot?
 
@@ -48,6 +52,17 @@ Clapshot provides professional video review capabilities similar to cloud servic
 
 ## Getting Started and User Support
 
+### Default Demo Credentials
+
+**For htadmin-based demo images** (`latest-demo-htadmin`):
+- `admin:admin` - Admin user (can edit all videos, manage users)
+- `demo:demo` - Standard user with full permissions
+- `alice:alice123` - Standard user with full permissions
+- `bob:bob123` - User with **no upload permissions** (demonstrates upload restrictions)
+- `htadmin:admin` - User management interface at `/htadmin/`
+
+⚠️ **Security Warning:** Change all default passwords before production use!
+
 ### Essential Troubleshooting Documentation
 
 **READ THESE FIRST when users report problems:**
@@ -86,6 +101,13 @@ Clapshot provides professional video review capabilities similar to cloud servic
 - Docker bindings: `0.0.0.0:8080:80` not `127.0.0.1:8080:80`
 - Check firewall allows ports 8080 and 8095
 
+**Large file uploads (>2GB) fail:**
+- IIS reverse proxy has a hard 2GB upload limit
+- Cloudflare free tier has ~100 second timeout that can interrupt large uploads
+- Workaround: Use monitored folder ingestion with `--ingest-username-from=folder-name` mode
+- Drop files into `incoming/username/` directories (via SFTP/SMB) for automatic processing
+- See doc/sysadmin-guide.md#monitored-folder-ingestion
+
 ### Features and Capabilities
 
 [FEATURES.md](FEATURES.md): Comprehensive feature listing organized by category - Web Client UX, Media Processing, Organizer Plugin System, Administration/Security, and Development tools