df3d22b218
- Add comprehensive Tdarr troubleshooting and GPU transcoding documentation - Create /scripts directory for active operational scripts - Archive mapped node example in /examples for reference - Update CLAUDE.md with scripts directory context triggers - Add distributed transcoding patterns and NVIDIA troubleshooting guides - Enhance documentation structure with clear directory usage guidelines 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
2.2 KiB
2.2 KiB
Network Filesystem Limitations
SQLite on Network Filesystems
The Problem
SQLite's WAL (Write-Ahead Logging) mode requires proper file locking that many network filesystems don't support:
[ERROR] Tdarr_Server - Error: SQLITE_BUSY: database is locked
[ERROR] Tdarr_Server - {
"func": "run",
"query": "PRAGMA journal_mode = WAL"
}
Affected Filesystems
- ❌ NFS - Inconsistent locking behavior
- ❌ SMB/CIFS - Limited locking support
- ❌ sshfs - No proper locking
- ✅ Local ext4/xfs/btrfs - Full locking support
Solutions
Hybrid Storage Pattern
volumes:
# Database: Local storage
- ./tdarr/server:/app/server
# Backups: Network storage
- /mnt/nas/tdarr/backups:/app/server/Tdarr/Backups
# Media: Network storage (read-mostly)
- /mnt/nas/media:/media
Application-Specific Fixes
# Force SQLite to use different journal mode
environment:
- SQLITE_JOURNAL_MODE=DELETE # Less efficient but compatible
Performance Considerations
Local vs Network Storage
| Operation | Local SSD | Gigabit NFS | 10Gb NFS |
|---|---|---|---|
| Database writes | <1ms | 10-50ms | 2-10ms |
| Config reads | <1ms | 5-15ms | 1-5ms |
| Large file reads | 500MB/s | 100MB/s | 800MB/s |
When to Use Network Storage
- ✅ Large static files (media, backups)
- ✅ Shared access between multiple services
- ✅ Centralized backups
- ❌ Frequent small writes (databases, logs)
- ❌ Applications requiring file locking
Troubleshooting
Symptoms of Network FS Issues
- Database locked errors
- Slow application startup
- Intermittent connection failures
- File corruption on network interruption
Diagnostic Commands
# Test file locking
flock /mnt/nas/test.lock -c "sleep 5" &
flock /mnt/nas/test.lock -c "echo success"
# Monitor network filesystem performance
iotop -ao
iostat -x 1
# Check mount options
mount | grep nfs
cat /proc/mounts | grep cifs
Mount Optimization
# NFS optimizations
mount -t nfs -o rw,hard,intr,rsize=8192,wsize=8192,timeo=14 \
server:/path /mnt/point
# CIFS optimizations
mount -t cifs //server/share /mnt/point \
-o username=user,cache=loose,file_mode=0644,dir_mode=0755