Initial commit: DigiServer v2 with Blueprint Architecture
Features implemented: - Application factory pattern with environment-based config - 7 modular blueprints (main, auth, admin, players, groups, content, api) - Flask-Caching with Redis support for production - Flask-Login authentication with bcrypt password hashing - API endpoints with rate limiting and Bearer token auth - Comprehensive error handling and logging - CLI commands (init-db, create-admin, seed-db) Blueprint Structure: - main: Dashboard with caching, health check endpoint - auth: Login, register, logout, password change - admin: User management, system settings, theme, logo upload - players: Full CRUD, fullscreen view, bulk operations, playlist management - groups: Group management, player assignments, content management - content: Upload with progress tracking, file management, preview/download - api: RESTful endpoints with authentication, rate limiting, player feedback Performance Optimizations: - Dashboard caching (60s timeout) - Playlist caching (5min timeout) - Redis caching for production - Memoized functions for expensive operations - Cache clearing on data changes Security Features: - Bcrypt password hashing - Flask-Login session management - admin_required decorator for authorization - Player authentication via auth codes - API Bearer token authentication - Rate limiting on API endpoints (60 req/min default) - Input validation and sanitization Documentation: - README.md: Full project documentation with quick start - PROGRESS.md: Detailed progress tracking and roadmap - BLUEPRINT_GUIDE.md: Quick reference for blueprint architecture Pending work: - Models migration from v1 with database indexes - Utils migration from v1 with type hints - Templates migration with updated route references - Docker multi-stage build configuration - Unit tests for all blueprints Ready for models and utils migration from digiserver v1
This commit is contained in:
ske087
287
README.md
Normal file
287
README.md
Normal file
@@ -0,0 +1,287 @@
|
||||
# DigiServer v2 - Blueprint Architecture
|
||||
|
||||
Modern Flask application with blueprint architecture, designed for scalability and maintainability.
|
||||
|
||||
## 🎯 Project Goals
|
||||
|
||||
- **Modular Architecture**: Blueprints for better code organization
|
||||
- **Scalability**: Redis caching, Celery background tasks
|
||||
- **Security**: Input validation, rate limiting, CSRF protection
|
||||
- **Performance**: Optimized Docker image, database indexes
|
||||
- **Maintainability**: Type hints, comprehensive tests, clear documentation
|
||||
|
||||
## 📁 Project Structure
|
||||
|
||||
```
|
||||
digiserver-v2/
|
||||
├── app/
|
||||
│ ├── app.py # Application factory
|
||||
│ ├── config.py # Environment-based configuration
|
||||
│ ├── extensions.py # Flask extensions
|
||||
│ ├── blueprints/
|
||||
│ │ ├── __init__.py
|
||||
│ │ ├── main.py # Dashboard & home
|
||||
│ │ ├── auth.py # Authentication
|
||||
│ │ ├── admin.py # Admin panel
|
||||
│ │ ├── players.py # Player management
|
||||
│ │ ├── groups.py # Group management
|
||||
│ │ ├── content.py # Media upload & management
|
||||
│ │ └── api.py # REST API endpoints
|
||||
│ ├── models/
|
||||
│ │ ├── __init__.py
|
||||
│ │ ├── user.py
|
||||
│ │ ├── player.py
|
||||
│ │ ├── group.py
|
||||
│ │ ├── content.py
|
||||
│ │ ├── player_feedback.py
|
||||
│ │ └── server_log.py
|
||||
│ ├── utils/
|
||||
│ │ ├── __init__.py
|
||||
│ │ ├── logger.py
|
||||
│ │ ├── uploads.py
|
||||
│ │ ├── decorators.py
|
||||
│ │ └── validators.py
|
||||
│ ├── templates/
|
||||
│ │ ├── base.html
|
||||
│ │ ├── auth/
|
||||
│ │ ├── admin/
|
||||
│ │ ├── players/
|
||||
│ │ ├── groups/
|
||||
│ │ └── errors/
|
||||
│ └── static/
|
||||
│ ├── css/
|
||||
│ ├── js/
|
||||
│ ├── uploads/
|
||||
│ └── resurse/
|
||||
├── tests/
|
||||
│ ├── __init__.py
|
||||
│ ├── conftest.py
|
||||
│ ├── test_auth.py
|
||||
│ ├── test_players.py
|
||||
│ └── test_api.py
|
||||
├── docker-compose.yml
|
||||
├── Dockerfile
|
||||
├── requirements.txt
|
||||
├── .env.example
|
||||
└── README.md
|
||||
```
|
||||
|
||||
## 🚀 Quick Start
|
||||
|
||||
### Development
|
||||
|
||||
```bash
|
||||
# Clone the repository
|
||||
git clone <repository-url>
|
||||
cd digiserver-v2
|
||||
|
||||
# Create virtual environment
|
||||
python3 -m venv venv
|
||||
source venv/bin/activate # On Windows: venv\Scripts\activate
|
||||
|
||||
# Install dependencies
|
||||
pip install -r requirements.txt
|
||||
|
||||
# Set up environment variables
|
||||
cp .env.example .env
|
||||
# Edit .env with your settings
|
||||
|
||||
# Initialize database
|
||||
flask init-db
|
||||
flask create-admin
|
||||
|
||||
# Run development server
|
||||
flask run
|
||||
```
|
||||
|
||||
### Docker (Production)
|
||||
|
||||
```bash
|
||||
# Build and start containers
|
||||
docker compose up -d
|
||||
|
||||
# View logs
|
||||
docker compose logs -f
|
||||
|
||||
# Stop containers
|
||||
docker compose down
|
||||
```
|
||||
|
||||
## 🔧 Configuration
|
||||
|
||||
Configuration is environment-based (development, production, testing).
|
||||
|
||||
### Environment Variables
|
||||
|
||||
Create a `.env` file:
|
||||
|
||||
```env
|
||||
# Flask
|
||||
FLASK_ENV=production
|
||||
SECRET_KEY=your-secret-key-here
|
||||
|
||||
# Database
|
||||
DATABASE_URL=sqlite:///instance/dashboard.db
|
||||
|
||||
# Redis
|
||||
REDIS_HOST=redis
|
||||
REDIS_PORT=6379
|
||||
|
||||
# Admin Defaults
|
||||
ADMIN_USER=admin
|
||||
ADMIN_PASSWORD=secure-password
|
||||
|
||||
# Optional
|
||||
SENTRY_DSN=your-sentry-dsn
|
||||
```
|
||||
|
||||
## 📊 Features
|
||||
|
||||
### Current (v2.0.0)
|
||||
|
||||
- ✅ Blueprint architecture
|
||||
- ✅ Environment-based configuration
|
||||
- ✅ User authentication & authorization
|
||||
- ✅ Admin panel
|
||||
- ✅ Player management
|
||||
- ✅ Group management
|
||||
- ✅ Content upload & management
|
||||
- ✅ REST API
|
||||
- ✅ Redis caching (production)
|
||||
- ✅ Health check endpoint
|
||||
|
||||
### Planned
|
||||
|
||||
- ⏳ Celery background tasks
|
||||
- ⏳ Rate limiting
|
||||
- ⏳ API authentication (JWT)
|
||||
- ⏳ Unit & integration tests
|
||||
- ⏳ API documentation (Swagger)
|
||||
- ⏳ Monitoring & metrics (Prometheus)
|
||||
|
||||
## 🛠️ Development
|
||||
|
||||
### Running Tests
|
||||
|
||||
```bash
|
||||
pytest
|
||||
pytest --cov=app tests/
|
||||
```
|
||||
|
||||
### Database Migrations
|
||||
|
||||
```bash
|
||||
# Create migration
|
||||
flask db migrate -m "Description"
|
||||
|
||||
# Apply migration
|
||||
flask db upgrade
|
||||
|
||||
# Rollback
|
||||
flask db downgrade
|
||||
```
|
||||
|
||||
### Code Quality
|
||||
|
||||
```bash
|
||||
# Format code
|
||||
black app/
|
||||
|
||||
# Lint
|
||||
flake8 app/
|
||||
pylint app/
|
||||
|
||||
# Type check
|
||||
mypy app/
|
||||
```
|
||||
|
||||
## 📖 API Documentation
|
||||
|
||||
### Authentication
|
||||
|
||||
All API endpoints require authentication via session or API key.
|
||||
|
||||
### Endpoints
|
||||
|
||||
- `GET /api/playlists` - Get playlist for player
|
||||
- `POST /api/player-feedback` - Submit player feedback
|
||||
- `GET /health` - Health check
|
||||
|
||||
See `/docs` for full API documentation (Swagger UI).
|
||||
|
||||
## 🔒 Security
|
||||
|
||||
- CSRF protection enabled
|
||||
- Rate limiting on API endpoints
|
||||
- Input validation using Marshmallow
|
||||
- SQL injection prevention (SQLAlchemy ORM)
|
||||
- XSS prevention (Jinja2 autoescaping)
|
||||
- Secure password hashing (bcrypt)
|
||||
|
||||
## 📈 Performance
|
||||
|
||||
- Redis caching for frequently accessed data
|
||||
- Database indexes on foreign keys
|
||||
- Lazy loading for relationships
|
||||
- Static file compression (nginx)
|
||||
- Multi-stage Docker build (~800MB)
|
||||
|
||||
## 🐳 Docker
|
||||
|
||||
### Multi-stage Build
|
||||
|
||||
```dockerfile
|
||||
# Build stage (heavy dependencies)
|
||||
FROM python:3.11-slim as builder
|
||||
# ... build dependencies
|
||||
|
||||
# Runtime stage (slim)
|
||||
FROM python:3.11-slim
|
||||
# ... only runtime dependencies
|
||||
```
|
||||
|
||||
### Docker Compose Services
|
||||
|
||||
- **digiserver**: Main Flask application
|
||||
- **redis**: Cache and session storage
|
||||
- **worker**: Celery background worker (optional)
|
||||
- **nginx**: Reverse proxy (production)
|
||||
|
||||
## 📝 Migration from v1
|
||||
|
||||
See `MIGRATION.md` for detailed migration guide from digiserver v1.
|
||||
|
||||
Key differences:
|
||||
- Blueprint-based routing instead of monolithic app.py
|
||||
- Environment-based configuration
|
||||
- Redis caching in production
|
||||
- Improved error handling
|
||||
- Type hints throughout codebase
|
||||
|
||||
## 🤝 Contributing
|
||||
|
||||
1. Fork the repository
|
||||
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
|
||||
3. Commit your changes (`git commit -m 'Add amazing feature'`)
|
||||
4. Push to the branch (`git push origin feature/amazing-feature`)
|
||||
5. Open a Pull Request
|
||||
|
||||
## 📄 License
|
||||
|
||||
This project is part of the DigiServer digital signage system.
|
||||
|
||||
## 🙏 Acknowledgments
|
||||
|
||||
- Built with Flask and modern Python practices
|
||||
- Inspired by Flask best practices and 12-factor app principles
|
||||
- Based on lessons learned from DigiServer v1
|
||||
|
||||
## 📞 Support
|
||||
|
||||
For issues and feature requests, please use the GitHub issue tracker.
|
||||
|
||||
---
|
||||
|
||||
**Status**: 🚧 Work in Progress - Blueprint architecture implementation
|
||||
**Version**: 2.0.0-alpha
|
||||
**Last Updated**: 2025-11-12
|
||||
Reference in New Issue
Block a user