215 lines
6.6 KiB
Markdown
215 lines
6.6 KiB
Markdown
# QR Code Manager
|
|
|
|
A modern Flask web application for generating and managing QR codes with authentication and dynamic link pages.
|
|
|
|
## 🚀 Features
|
|
|
|
- **Multiple QR Code Types**: Text, URL, WiFi, Email, SMS, vCard
|
|
- **Dynamic Link Pages**: Create collections of links accessible via 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
|
|
- **Docker Deployment**: Production-ready containerization
|
|
- **Responsive Design**: Modern web interface that works on all devices
|
|
|
|
## 📁 Project Structure
|
|
|
|
```
|
|
qr-code_manager/
|
|
├── README.md # Project documentation
|
|
├── main.py # Application entry point
|
|
├── Dockerfile # Docker container definition
|
|
├── docker-compose.yml # Docker orchestration
|
|
├── requirements.txt # Python dependencies
|
|
├── .env.example # Environment variables template
|
|
├── deploy.sh # Deployment script
|
|
├── app/ # Main application package
|
|
│ ├── __init__.py # Flask app factory
|
|
│ ├── templates/ # Jinja2 templates
|
|
│ │ ├── index.html # Main dashboard
|
|
│ │ ├── login.html # Authentication page
|
|
│ │ ├── link_page.html # Public link display
|
|
│ │ └── edit_links.html # Link management interface
|
|
│ ├── static/ # Static files
|
|
│ │ ├── qr_codes/ # Generated QR code images
|
|
│ │ └── logos/ # Uploaded logo files
|
|
│ ├── routes/ # Route handlers
|
|
│ │ ├── __init__.py # Route package
|
|
│ │ ├── main.py # Main page routes
|
|
│ │ ├── auth.py # Authentication routes
|
|
│ │ └── api.py # API endpoints
|
|
│ └── utils/ # Utility modules
|
|
│ ├── __init__.py # Utils package
|
|
│ ├── auth.py # Authentication utilities
|
|
│ ├── qr_generator.py # QR code generation
|
|
│ ├── link_manager.py # Dynamic link management
|
|
│ └── data_manager.py # Data storage utilities
|
|
```
|
|
|
|
## 🛠️ Quick Start
|
|
|
|
### Method 1: Docker (Recommended)
|
|
|
|
1. **Clone and navigate to the project:**
|
|
```bash
|
|
git clone <your-repo-url>
|
|
cd qr-code_manager
|
|
```
|
|
|
|
2. **Create environment file:**
|
|
```bash
|
|
cp .env.example .env
|
|
# Edit .env with your preferred settings
|
|
```
|
|
|
|
3. **Deploy with Docker:**
|
|
```bash
|
|
./deploy.sh
|
|
```
|
|
|
|
4. **Access the application:**
|
|
- Open http://localhost:5000
|
|
- Login with: admin / admin123 (change in production!)
|
|
|
|
### Method 2: Local Development
|
|
|
|
1. **Set up Python environment:**
|
|
```bash
|
|
python -m venv .venv
|
|
source .venv/bin/activate # On Windows: .venv\Scripts\activate
|
|
```
|
|
|
|
2. **Install dependencies:**
|
|
```bash
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
3. **Run the application:**
|
|
```bash
|
|
python main.py
|
|
```
|
|
|
|
## 🔐 Authentication
|
|
|
|
- **Default Credentials**: admin / admin123
|
|
- **Environment Variables**:
|
|
- `ADMIN_USERNAME`: Set custom admin username
|
|
- `ADMIN_PASSWORD`: Set custom admin password
|
|
- `SECRET_KEY`: Set Flask secret key for sessions
|
|
|
|
## 🐳 Docker Deployment
|
|
|
|
The application is fully containerized with Docker:
|
|
|
|
- **Build and run**: `docker-compose up -d`
|
|
- **View logs**: `docker-compose logs -f`
|
|
- **Stop**: `docker-compose down`
|
|
- **Full rebuild**: `docker-compose up --build -d`
|
|
|
|
### Production Configuration
|
|
|
|
1. **Set environment variables in .env:**
|
|
```bash
|
|
FLASK_ENV=production
|
|
SECRET_KEY=your-super-secret-key-here
|
|
ADMIN_USERNAME=your-admin-username
|
|
ADMIN_PASSWORD=your-secure-password
|
|
```
|
|
|
|
2. **Deploy:**
|
|
```bash
|
|
docker-compose up -d
|
|
```
|
|
|
|
## 📱 Usage
|
|
|
|
### Generating QR Codes
|
|
|
|
1. **Login** to the admin interface
|
|
2. **Select QR type**: Text, URL, WiFi, Email, SMS, or vCard
|
|
3. **Fill in the details** for your chosen type
|
|
4. **Customize appearance**: Size, colors, style, border
|
|
5. **Add logo** (optional): Upload custom logo for branding
|
|
6. **Generate and download** your QR code
|
|
|
|
### Dynamic Link Pages
|
|
|
|
1. **Create a link page** from the main interface
|
|
2. **Add links** to your collection via the edit interface
|
|
3. **Share the QR code** that points to your link page
|
|
4. **Update links anytime** without changing the QR code
|
|
|
|
## 🛡️ Security Features
|
|
|
|
- **Password Hashing**: Uses bcrypt for secure password storage
|
|
- **Session Management**: Secure Flask sessions with signing
|
|
- **Authentication Required**: All admin functions require login
|
|
- **Docker Security**: Non-root user in container
|
|
- **Environment Variables**: Sensitive data via environment configuration
|
|
|
|
## 🔧 Development
|
|
|
|
### Project Architecture
|
|
|
|
The application follows a modular Flask structure:
|
|
|
|
- **App Factory Pattern**: Clean application initialization
|
|
- **Blueprint Organization**: Separate route modules for different features
|
|
- **Utility Modules**: Reusable components for QR generation, auth, etc.
|
|
- **Template Organization**: Structured Jinja2 templates
|
|
- **Static File Management**: Organized asset storage
|
|
|
|
### Adding New Features
|
|
|
|
1. **New Routes**: Add to appropriate blueprint in `app/routes/`
|
|
2. **New Utilities**: Create modules in `app/utils/`
|
|
3. **New Templates**: Add to `app/templates/`
|
|
4. **New Dependencies**: Update `requirements.txt`
|
|
|
|
## 📊 API Endpoints
|
|
|
|
- `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
|
|
- `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
|
|
|
|
## 🚨 Troubleshooting
|
|
|
|
### Common Issues
|
|
|
|
1. **Permission Denied**: Ensure Docker has proper permissions
|
|
2. **Port 5000 in use**: Change port in docker-compose.yml
|
|
3. **Authentication Failed**: Check admin credentials in .env
|
|
4. **Image Generation Failed**: Verify PIL/Pillow installation
|
|
|
|
### Health Check
|
|
|
|
Visit `/health` to check application status:
|
|
```bash
|
|
curl http://localhost:5000/health
|
|
```
|
|
|
|
## 📝 License
|
|
|
|
This project is licensed under the MIT License - see the LICENSE file for details.
|
|
|
|
## 🤝 Contributing
|
|
|
|
1. Fork the repository
|
|
2. Create a feature branch
|
|
3. Make your changes
|
|
4. Add tests if applicable
|
|
5. Submit a pull request
|
|
|
|
## 📞 Support
|
|
|
|
For support, please open an issue on GitHub or contact the development team.
|
|
|
|
---
|
|
|
|
**Made with ❤️ for easy QR code management**
|