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>
92 lines
2.2 KiB
Markdown
92 lines
2.2 KiB
Markdown
# 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
|
|
```yaml
|
|
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
|
|
```yaml
|
|
# 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
|
|
```bash
|
|
# 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
|
|
```bash
|
|
# 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
|
|
``` |