218 lines
6.7 KiB
Markdown
218 lines
6.7 KiB
Markdown
# Playlist Monitor Service - Complete Getting Started Guide
|
|
|
|
## 🎯 What You Have Now
|
|
|
|
### ✅ **Fully Implemented Backend**
|
|
- **Complete REST API** with 20+ endpoints
|
|
- **Database models** with SQLite/PostgreSQL support
|
|
- **MeTube integration** via HTTP API + WebSocket
|
|
- **Automated playlist monitoring** with configurable intervals
|
|
- **Video tracking** with status management
|
|
- **Docker support** with multi-stage builds
|
|
- **Comprehensive testing** with pytest
|
|
|
|
### ❌ **Missing: User Interface**
|
|
The service currently only provides a **REST API** with Swagger documentation at `http://localhost:8082/docs`. There is **no web UI** for visual management.
|
|
|
|
## 🚀 Quick Start (Choose Your Path)
|
|
|
|
### Path 1: API-Only (Immediate Use)
|
|
```bash
|
|
# Start the service
|
|
cd /root/workspace/tubewatch/playlist-monitor
|
|
uv run python -m app.main
|
|
|
|
# Access API documentation
|
|
open http://localhost:8082/docs
|
|
|
|
# Test with curl
|
|
curl -X POST http://localhost:8082/api/playlists \
|
|
-H "Content-Type: application/json" \
|
|
-d '{
|
|
"url": "https://www.youtube.com/playlist?list=PLrAXtmErZgOeiKm4sgNOknGvNjby9efdf",
|
|
"check_interval": 60,
|
|
"quality": "best",
|
|
"format": "mp4",
|
|
"folder": "kurzgesagt"
|
|
}'
|
|
```
|
|
|
|
### Path 2: Add Simple UI (30 minutes)
|
|
```bash
|
|
# Create basic HTML dashboard
|
|
cd /root/workspace/tubewatch/playlist-monitor
|
|
mkdir ui
|
|
cp templates/simple-dashboard.html ui/index.html
|
|
|
|
# Modify backend to serve UI
|
|
echo "app.mount('/ui', StaticFiles(directory='ui', html=True), name='ui')" >> app/main.py
|
|
|
|
# Restart and access UI
|
|
uv run python -m app.main
|
|
open http://localhost:8082/ui
|
|
```
|
|
|
|
### Path 3: Full React App (2-4 hours)
|
|
```bash
|
|
# Create React application
|
|
cd /root/workspace/tubewatch
|
|
npx create-react-app playlist-monitor-ui --template typescript
|
|
cd playlist-monitor-ui
|
|
|
|
# Install UI libraries
|
|
npm install @mui/material @emotion/react @emotion/styled axios react-query
|
|
|
|
# Follow UI_INTEGRATION.md for complete setup
|
|
```
|
|
|
|
## 📚 Documentation You Have
|
|
|
|
### Essential Guides
|
|
- **[QUICK_START_GUIDE.md](QUICK_START_GUIDE.md)** - Get started in 5 minutes
|
|
- **[BUILD_GUIDE.md](BUILD_GUIDE.md)** - Comprehensive build instructions
|
|
- **[TESTING_GUIDE.md](TESTING_GUIDE.md)** - Complete testing procedures
|
|
- **[UI_INTEGRATION.md](UI_INTEGRATION.md)** - UI implementation options
|
|
|
|
### Reference Documents
|
|
- **[IMPLEMENTATION_STATUS.md](IMPLEMENTATION_STATUS.md)** - What was built
|
|
- **[PLAYLIST_MONITOR_ARCHITECTURE.md](PLAYLIST_MONITOR_ARCHITECTURE.md)** - Original architecture
|
|
|
|
## 🎯 What You Can Do Right Now
|
|
|
|
### 1. Start Using the API (No UI Needed)
|
|
```bash
|
|
# Check system status
|
|
curl http://localhost:8082/api/status
|
|
|
|
# Add a playlist
|
|
curl -X POST http://localhost:8082/api/playlists \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"url": "https://www.youtube.com/playlist?list=TEST123"}'
|
|
|
|
# Monitor downloads
|
|
curl http://localhost:8082/api/playlists/{id}/videos
|
|
```
|
|
|
|
### 2. Test the Service
|
|
```bash
|
|
# Run all tests
|
|
uv run pytest tests/ -v
|
|
|
|
# Run specific test
|
|
uv run pytest tests/unit/test_models.py -v
|
|
|
|
# Check coverage
|
|
uv run pytest --cov=app --cov-report=html
|
|
```
|
|
|
|
### 3. Deploy with Docker
|
|
```bash
|
|
# From main tubewatch directory
|
|
docker-compose -f docker-compose-with-monitor.yml up -d
|
|
|
|
# Check status
|
|
docker-compose -f docker-compose-with-monitor.yml ps
|
|
```
|
|
|
|
## 🎨 UI Implementation Priority
|
|
|
|
Since you mentioned the UI is missing, here are your options ranked by effort:
|
|
|
|
### 🟢 **15 Minutes: Basic HTML Dashboard**
|
|
- Simple Bootstrap-based interface
|
|
- List playlists, show status
|
|
- Add/delete operations
|
|
- **Good for**: Quick setup, basic needs
|
|
|
|
### 🟡 **2-4 Hours: React App**
|
|
- Modern Material-UI interface
|
|
- Real-time updates, charts
|
|
- Full CRUD operations
|
|
- **Good for**: Production use, modern UX
|
|
|
|
### 🔴 **8+ Hours: Extend MeTube Angular**
|
|
- Integrate with existing MeTube UI
|
|
- Consistent styling and navigation
|
|
- Most complex but seamless
|
|
- **Good for**: Existing MeTube deployments
|
|
|
|
## 🚀 Recommended Next Steps
|
|
|
|
### Immediate (Next 30 minutes)
|
|
1. **Start the service**: `uv run python -m app.main`
|
|
2. **Test the API**: Visit http://localhost:8082/docs
|
|
3. **Add a playlist**: Use the interactive API docs
|
|
4. **Monitor progress**: Check logs and status endpoints
|
|
|
|
### Short Term (Next few hours)
|
|
1. **Choose UI option** based on your needs
|
|
2. **Implement basic interface** following UI_INTEGRATION.md
|
|
3. **Test end-to-end workflow** with real playlists
|
|
4. **Set up monitoring** and health checks
|
|
|
|
### Long Term (Next few days)
|
|
1. **Deploy to production** with Docker
|
|
2. **Set up automated monitoring** and alerts
|
|
3. **Add authentication** if needed
|
|
4. **Optimize performance** based on usage
|
|
|
|
## 🔧 Common First-Time Setup Issues
|
|
|
|
### "MeTube connection failed"
|
|
- Ensure MeTube is running on port 8081
|
|
- Check MeTube logs: `docker logs metube`
|
|
- Verify network connectivity
|
|
|
|
### "Port 8082 already in use"
|
|
- Find process: `lsof -i :8082`
|
|
- Kill process or change port in .env
|
|
|
|
### "Database locked"
|
|
- Remove lock file: `rm data/*.db-journal`
|
|
- Check for zombie processes
|
|
|
|
### "Python version too old"
|
|
- Install Python 3.13+ or use Docker
|
|
- Use pyenv for version management
|
|
|
|
## 📞 Getting Help
|
|
|
|
### Documentation
|
|
- **API Reference**: http://localhost:8082/docs (when running)
|
|
- **Architecture**: See PLAYLIST_MONITOR_ARCHITECTURE.md
|
|
- **Build Issues**: See BUILD_GUIDE.md troubleshooting section
|
|
|
|
### Debugging
|
|
- Check logs: `tail -f logs/playlist-monitor.log`
|
|
- Health check: `curl http://localhost:8082/health`
|
|
- System status: `curl http://localhost:8082/api/status`
|
|
|
|
### Community
|
|
- Check existing issues in the repository
|
|
- Create detailed bug reports with logs
|
|
- Include system information and reproduction steps
|
|
|
|
## 🎉 Success Metrics
|
|
|
|
You'll know everything is working when you can:
|
|
|
|
1. ✅ **Start the service** without errors
|
|
2. ✅ **Access API docs** at http://localhost:8082/docs
|
|
3. ✅ **Add a playlist** via API or UI
|
|
4. ✅ **See videos detected** from the playlist
|
|
5. ✅ **Monitor download progress** in real-time
|
|
6. ✅ **Manage video status** (skip, reset, etc.)
|
|
|
|
## 🎯 Final Recommendation
|
|
|
|
**Start with the API-only approach** to verify everything works, then add a UI based on your comfort level:
|
|
|
|
- **API-only**: Great for automation, scripts, or integration with other tools
|
|
- **Simple HTML**: Perfect for personal use or quick setup
|
|
- **React App**: Best for production deployments and user-friendly experience
|
|
|
|
The backend is **production-ready** and thoroughly tested. Focus your effort on the UI implementation based on your specific needs! 🚀
|
|
|
|
---
|
|
|
|
**Next Step**: Choose your UI path and follow the relevant guide in [UI_INTEGRATION.md](UI_INTEGRATION.md)! |