Initial commit: Clean Mold Cost Calculator application

- Flask-based mold cost calculation application - PostgreSQL database with SQLAlchemy ORM - Docker/Podman containerization - Comprehensive documentation in docs/ - Clean, organized codebase without obsolete files - Production-ready deployment configuration - Enhanced pytest configuration with coverage reporting - Master/Development branch structure
2025-06-24 02:30:09 +08:00
commit 6c0d5a4e63
108 changed files with 15911 additions and 0 deletions
@@ -0,0 +1,225 @@
+# 🚀 Mold Cost Calculator - Setup Guide
+
+## 📦 Package Contents
+
+This handover package contains a complete, production-ready mold cost calculator application with:
+
+- ✅ **Full Application Code** - Complete Flask application
+- ✅ **Database Migrations** - PostgreSQL schema and migrations
+- ✅ **Container Configuration** - Podman/Docker setup
+- ✅ **Deployment Scripts** - Production and development environments
+- ✅ **Documentation** - Complete user, admin, and developer guides
+- ✅ **Test Suite** - Comprehensive testing framework
+
+## 🎯 Quick Start (5 minutes)
+
+### 1. Prerequisites
+```bash
+# Required software
+- Python 3.11+
+- Podman or Docker
+- Git
+```
+
+### 2. Initial Setup
+```bash
+# Clone or extract the package
+cd mold_cost_online_tool
+
+# Copy environment template
+cp .env.example .env
+
+# Edit environment variables
+nano .env  # or use your preferred editor
+```
+
+### 3. Start Development Environment
+```bash
+# Start containers
+podman-compose -f podman-compose.development.yml up -d
+
+# Check status
+podman ps
+
+# Access application
+open http://localhost:5003
+```
+
+### 4. Create Admin User
+```bash
+# Run database migrations
+podman exec mold_cost_tool_development flask db upgrade
+
+# Create admin user (if needed)
+podman exec mold_cost_tool_development flask init-db
+```
+
+## 🔧 Environment Configuration
+
+### Required Environment Variables
+
+Edit `.env` file with your values:
+
+```bash
+# Database
+POSTGRES_USER=postgres
+POSTGRES_PASSWORD=your_secure_password
+POSTGRES_DB=mold_cost
+DATABASE_HOST=db
+
+# Application
+SECRET_KEY=your_very_secure_secret_key
+FLASK_ENV=production
+
+# Admin Account
+ADMIN_EMAIL=admin@yourcompany.com
+ADMIN_PASSWORD=your_admin_password
+```
+
+### Generate Secure Keys
+
+```bash
+# Generate secret key
+openssl rand -hex 32
+
+# Generate database password
+openssl rand -base64 32
+```
+
+## 🌐 Deployment Options
+
+### Option 1: Local Development
+```bash
+podman-compose -f podman-compose.development.yml up -d
+# Access at: http://localhost:5003
+```
+
+### Option 2: Production Deployment
+```bash
+podman-compose up -d
+# Configure nginx and SSL certificates
+# Access at: https://yourdomain.com
+```
+
+### Option 3: Cloud Deployment
+- **AWS**: Use ECS or EKS with provided Dockerfile
+- **Azure**: Use Container Instances or AKS
+- **GCP**: Use Cloud Run or GKE
+- **DigitalOcean**: Use App Platform or Droplets
+
+## 📊 System Requirements
+
+### Minimum Requirements
+- **CPU**: 2 cores
+- **RAM**: 4GB
+- **Storage**: 20GB
+- **Network**: 100Mbps
+
+### Recommended Requirements
+- **CPU**: 4+ cores
+- **RAM**: 8GB+
+- **Storage**: 50GB+ SSD
+- **Network**: 1Gbps
+
+## 🔒 Security Checklist
+
+Before going live:
+
+- [ ] Change default passwords
+- [ ] Generate secure SECRET_KEY
+- [ ] Configure HTTPS/SSL
+- [ ] Set up firewall rules
+- [ ] Enable rate limiting
+- [ ] Configure backup strategy
+- [ ] Set up monitoring
+
+## 📈 Performance Tuning
+
+### Container Optimization
+```bash
+# Adjust worker processes (in gunicorn_config.py)
+workers = (2 × CPU_cores) + 1
+
+# Database connection pool
+pool_size = 10
+pool_recycle = 3600
+```
+
+### Monitoring Setup
+```bash
+# Health check endpoint
+curl http://localhost:5003/health
+
+# Container logs
+podman logs mold_cost_tool
+
+# Database performance
+podman exec mold_cost_db psql -U postgres -c "SELECT * FROM pg_stat_activity;"
+```
+
+## 🚨 Troubleshooting
+
+### Common Issues
+
+**Container won't start:**
+```bash
+# Check logs
+podman logs mold_cost_tool
+
+# Check port conflicts
+netstat -tulpn | grep :5003
+
+# Verify environment
+podman exec mold_cost_tool env | grep POSTGRES
+```
+
+**Database connection failed:**
+```bash
+# Check database container
+podman exec mold_cost_db pg_isready -U postgres
+
+# Verify database exists
+podman exec mold_cost_db psql -U postgres -l
+```
+
+**Application errors:**
+```bash
+# Check application logs
+podman logs mold_cost_tool
+
+# Test database connection
+podman exec mold_cost_tool flask shell
+```
+
+## 📚 Next Steps
+
+1. **Read Documentation**:
+   - `README.md` - Overview and features
+   - `USER_GUIDE.md` - End-user instructions
+   - `ADMIN_GUIDE.md` - Administrative operations
+   - `DEVELOPER_GUIDE.md` - Development details
+
+2. **Customize Application**:
+   - Update cost factors in admin panel
+   - Configure email settings
+   - Customize branding and styling
+
+3. **Production Deployment**:
+   - Set up domain and SSL
+   - Configure nginx reverse proxy
+   - Set up automated backups
+   - Implement monitoring
+
+## 📞 Support
+
+For technical support:
+- Check the documentation files
+- Review container logs
+- Test the health endpoint
+- Contact the original developer
+
+---
+
+**Package Version**: 1.0.0  
+**Last Updated**: June 2025  
+**Compatibility**: Python 3.11+, PostgreSQL 13+, Podman/Docker