final app for testing and deployment

2025-07-16 20:45:12 +03:00
parent 729f64f411
commit e9a8f5e622
26 changed files with 1561 additions and 168 deletions
--- a/README.md
+++ b/README.md
@@ -6,9 +6,11 @@ A modern Flask web application for generating and managing QR codes with authent

 - **Multiple QR Code Types**: Text, URL, WiFi, Email, SMS, vCard
 - **Dynamic Link Pages**: Create collections of links accessible via QR codes
+- **URL Shortener**: Generate shortened URLs with custom domains and QR codes
 - **Admin Authentication**: Secure login with bcrypt password hashing
 - **Customizable Styling**: Different QR code styles (square, rounded, circle)
 - **Logo Integration**: Add custom logos to QR codes
+- **Click Tracking**: Monitor short URL usage and statistics
 - **Docker Deployment**: Production-ready containerization
 - **Responsive Design**: Modern web interface that works on all devices

@@ -43,6 +45,7 @@ qr-code_manager/
 │       ├── auth.py         # Authentication utilities
 │       ├── qr_generator.py # QR code generation
 │       ├── link_manager.py # Dynamic link management
+│       ├── url_shortener.py # URL shortening utilities
 │       └── data_manager.py # Data storage utilities
 ```

@@ -89,7 +92,180 @@ qr-code_manager/
   python main.py
   ```

-## 🔐 Authentication
+## <EFBFBD> Production vs Development Modes
+
+The QR Code Manager supports two distinct runtime modes with different behaviors and optimizations.
+
+### 🛠️ Development Mode (Default)
+
+**When it runs:**
+- When `FLASK_ENV` is not set to "production"
+- When running `python main.py` locally
+- Default mode for local development
+
+**Characteristics:**
+- Uses Flask's built-in development server
+- Debug mode enabled with auto-reload
+- Detailed error messages and stack traces
+- Console shows default login credentials
+- Not suitable for production use
+
+**How to run:**
+```bash
+# Method 1: Direct execution
+python main.py
+
+# Method 2: With explicit development environment
+FLASK_ENV=development python main.py
+
+# Method 3: Using environment file
+echo "FLASK_ENV=development" > .env
+python main.py
+```
+
+**Console output in development:**
+```
+🛠️  Starting QR Code Manager in DEVELOPMENT mode
+🔐 Admin user: admin
+🔑 Default password: admin123
+🌐 Domain configured: localhost:5000
+🔗 URL shortener available at: /s/
+ * Serving Flask app 'app'
+ * Debug mode: on
+ * Running on all addresses (0.0.0.0)
+ * Running on http://127.0.0.1:5000
+```
+
+### 🚀 Production Mode
+
+**When it runs:**
+- When `FLASK_ENV=production` is set
+- When deployed with Docker (automatic)
+- For live/production deployments
+
+**Characteristics:**
+- Uses Gunicorn WSGI server (4 workers)
+- Debug mode disabled
+- Optimized for performance and security
+- No default credentials shown
+- Production-grade error handling
+
+**How to run:**
+
+#### Option 1: Docker (Recommended)
+```bash
+# Copy and edit production environment
+cp .env.production .env
+# Edit .env with your production settings
+
+# Deploy with Docker
+docker-compose up -d
+```
+
+#### Option 2: Manual Gunicorn
+```bash
+# Set production environment
+export FLASK_ENV=production
+export SECRET_KEY=your-super-secret-key
+export ADMIN_USERNAME=your-admin-username
+export ADMIN_PASSWORD=your-secure-password
+export APP_DOMAIN=your-domain.com
+
+# Run with Gunicorn
+gunicorn -c gunicorn.conf.py main:app
+```
+
+#### Option 3: Environment File + Gunicorn
+```bash
+# Create production environment file
+cp .env.production .env
+
+# Edit .env with your settings:
+# FLASK_ENV=production
+# SECRET_KEY=your-super-secret-key
+# ADMIN_USERNAME=your-admin-username  
+# ADMIN_PASSWORD=your-secure-password
+# APP_DOMAIN=your-domain.com
+
+# Run with Gunicorn
+gunicorn -c gunicorn.conf.py main:app
+```
+
+**Console output in production:**
+```
+Admin user initialized: your-admin-username
+Default password: your-secure-password
+[2025-07-16 17:27:27 +0000] [1] [INFO] Starting gunicorn 21.2.0
+[2025-07-16 17:27:27 +0000] [1] [INFO] Listening at: http://0.0.0.0:5000 (1)
+[2025-07-16 17:27:27 +0000] [1] [INFO] Using worker: sync
+[2025-07-16 17:27:27 +0000] [7] [INFO] Booting worker with pid: 7
+[2025-07-16 17:27:27 +0000] [8] [INFO] Booting worker with pid: 8
+[2025-07-16 17:27:27 +0000] [9] [INFO] Booting worker with pid: 9
+[2025-07-16 17:27:27 +0000] [10] [INFO] Booting worker with pid: 10
+```
+
+### 🔧 Environment Configuration
+
+Create a `.env` file in the project root with your configuration:
+
+**For Development:**
+```bash
+# Development settings
+FLASK_ENV=development
+SECRET_KEY=dev-secret-key
+ADMIN_USERNAME=admin
+ADMIN_PASSWORD=admin123
+APP_DOMAIN=localhost:5000
+```
+
+**For Production:**
+```bash
+# Production settings (copy from .env.production and customize)
+FLASK_ENV=production
+SECRET_KEY=your-super-secret-key-change-this
+ADMIN_USERNAME=your-admin-username
+ADMIN_PASSWORD=your-secure-password
+APP_DOMAIN=your-domain.com
+
+# Security settings
+SESSION_COOKIE_SECURE=true  # Set to true for HTTPS
+SESSION_COOKIE_HTTPONLY=true
+SESSION_COOKIE_SAMESITE=Lax
+
+# Performance settings
+UPLOAD_MAX_SIZE=10485760  # 10MB
+CACHE_TIMEOUT=3600        # 1 hour
+```
+
+### 🛡️ Security Considerations
+
+**Development Mode:**
+- ⚠️ Never use in production
+- Default credentials are visible
+- Debug information exposed
+- Single-threaded server
+
+**Production Mode:**
+- ✅ Use Gunicorn WSGI server
+- ✅ Change default credentials
+- ✅ Use strong SECRET_KEY
+- ✅ Enable HTTPS when possible
+- ✅ Set secure cookie flags
+- ✅ Multiple worker processes
+
+### 📊 Performance Comparison
+
+| Feature | Development | Production |
+|---------|-------------|------------|
+| Server | Flask dev server | Gunicorn (4 workers) |
+| Performance | Basic | Optimized |
+| Concurrency | Single-threaded | Multi-worker |
+| Auto-reload | Yes | No |
+| Debug info | Full | Minimal |
+| Error handling | Verbose | Secure |
+| Session security | Basic | Enhanced |
+
+## <20>🔐 Authentication

 - **Default Credentials**: admin / admin123
 - **Environment Variables**:
@@ -114,6 +290,7 @@ The application is fully containerized with Docker:
   SECRET_KEY=your-super-secret-key-here
   ADMIN_USERNAME=your-admin-username
   ADMIN_PASSWORD=your-secure-password
+   APP_DOMAIN=qr.moto-adv.com  # Your custom domain for URL shortener
   ```

 2. **Deploy:**
@@ -121,6 +298,15 @@ The application is fully containerized with Docker:
   docker-compose up -d
   ```

+### URL Shortener Configuration
+
+The URL shortener feature uses the `APP_DOMAIN` environment variable to generate short URLs:
+
+- **Development**: `APP_DOMAIN=localhost:5000`
+- **Production**: `APP_DOMAIN=qr.moto-adv.com` or `APP_DOMAIN=https://qr.moto-adv.com`
+
+Short URLs will be available at: `https://[your-domain]/s/[short-code]`
+
 ## 📱 Usage

 ### Generating QR Codes
@@ -139,6 +325,18 @@ The application is fully containerized with Docker:
 3. **Share the QR code** that points to your link page
 4. **Update links anytime** without changing the QR code

+### URL Shortener
+
+1. **Create shortened URLs** with optional custom codes
+2. **Generate QR codes** for shortened URLs
+3. **Track clicks** and monitor usage statistics
+4. **Redirect seamlessly** from short URLs to original destinations
+5. **Integrate with link pages** by enabling shortener for individual links
+
+**Examples:**
+- Original: `https://very-long-domain.com/extremely/long/path/to/resource`
+- Short: `https://qr.moto-adv.com/s/abc123`
+
 ## 🛡️ Security Features

 - **Password Hashing**: Uses bcrypt for secure password storage
@@ -168,15 +366,28 @@ The application follows a modular Flask structure:

 ## 📊 API Endpoints

+### QR Code Management
 - `POST /api/generate` - Generate QR code
 - `GET /api/qr_codes` - List all QR codes
 - `GET /api/qr_codes/{id}` - Get specific QR code
 - `DELETE /api/qr_codes/{id}` - Delete QR code
+
+### Dynamic Link Pages
 - `POST /api/create_link_page` - Create dynamic link page
 - `POST /api/link_pages/{id}/links` - Add link to page
 - `PUT /api/link_pages/{id}/links/{link_id}` - Update link
 - `DELETE /api/link_pages/{id}/links/{link_id}` - Delete link

+### URL Shortener
+- `POST /api/shorten` - Create standalone short URL
+- `POST /api/generate_shortened_qr` - Generate QR code with short URL
+- `GET /api/short_urls` - List all short URLs
+- `GET /api/short_urls/{code}/stats` - Get short URL statistics
+- `GET /s/{code}` - Redirect short URL to original
+- `POST /api/link_pages/{id}/links` - Add link to page
+- `PUT /api/link_pages/{id}/links/{link_id}` - Update link
+- `DELETE /api/link_pages/{id}/links/{link_id}` - Delete link
+
 ## 🚨 Troubleshooting

 ### Common Issues
@@ -205,6 +416,55 @@ This project is licensed under the MIT License - see the LICENSE file for detail
 4. Add tests if applicable
 5. Submit a pull request

+## 🧹 Data Cleanup for Deployment
+
+When preparing for a fresh deployment or when you need to clear all data, use the provided cleanup scripts:
+
+### Option 1: Python Script (Recommended)
+
+```bash
+python clean_data.py
+```
+
+### Option 2: Shell Script (Quick)
+
+```bash
+./clean_data.sh
+```
+
+### What Gets Cleaned
+
+Both scripts will remove:
+
+- **All QR codes and their data** - Clears the QR codes database and deletes all generated PNG images
+- **All dynamic link pages** - Removes all link collections and their settings  
+- **All short URLs** - Clears the URL shortener database
+- **All Flask sessions** - Removes user session files
+- **All log files** - Deletes any application log files
+- **Python cache files** - Removes `__pycache__` directories and `.pyc` files
+
+### Safety Features
+
+- **Confirmation prompt** - Both scripts require typing 'YES' to confirm the action
+- **Directory preservation** - Required directories are recreated after cleanup
+- **Error handling** - Scripts handle missing files/directories gracefully
+
+### Post-Cleanup Steps
+
+After running the cleanup script:
+
+1. Start the application: `python main.py`
+2. Login with default credentials: `admin` / `admin123`  
+3. **Important**: Change the default admin password immediately
+4. Begin creating your QR codes and link pages
+
+### Use Cases
+
+- **Fresh deployment** - Clean slate for production deployment
+- **Development reset** - Clear test data during development
+- **Data migration** - Prepare for moving to a new system
+- **Security cleanup** - Remove all data when decommissioning
+
 ## 📞 Support

 For support, please open an issue on GitHub or contact the development team.