Update README with comprehensive Apache deployment guide

- Added detailed Apache deployment instructions (not just MAMP) - Step-by-step production deployment guide - Apache virtual host configuration - Systemd service setup for Python API - PHP configuration for large file uploads - Firewall configuration (UFW and Firewalld) - SSL/HTTPS setup with Let's Encrypt - File permissions and ownership setup - Comprehensive troubleshooting section covering: - API issues - Upload issues - Transcription failures - Translation problems - Permission errors - Performance issues - Monitoring and maintenance section - Cron job for cleaning old files - Updated file structure listing - Added new features to feature list 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-10-21 13:44:37 -04:00 · 2025-10-21 13:44:37 -04:00 · ee857e0358
commit ee857e0358
parent d78207b64c
1 changed files with 330 additions and 29 deletions
--- a/README.md
+++ b/README.md
@ -11,6 +11,10 @@ A web application that converts audio files to text using OpenAI's Whisper model
 - 💻 PHP frontend (MAMP/Apache compatible)
 - 📦 350MB file size limit
 - 📄 Generates both original and translated files
+- 🎨 Modern black/gold UI with dark theme
+- 📊 Real-time progress bar during processing
+- 👀 In-page preview of transcriptions
+- ⬇️ One-click download for all formats

 ## Requirements

@ -139,69 +143,366 @@ model = whisper.load_model("base")  # Change to desired model

 ```
 .
-├── api.py              # Python Flask API
+├── api.py              # Python Flask API with Whisper & DeepL
 ├── index.php           # Frontend interface
 ├── process.php         # PHP request handler
 ├── download.php        # File download handler
-├── config.php          # Configuration
-├── style.css           # Styles
+├── check_api.php       # API status checker
+├── test_download.php   # Download functionality tester
+├── config.php          # Configuration (API URLs, keys)
+├── style.css           # Black/gold theme styles
+├── .htaccess           # PHP upload limits
+├── .gitignore          # Git ignore rules
 ├── requirements.txt    # Python dependencies
-├── setup.sh           # Setup script
-├── start_api.sh       # API start script
-├── outputs/           # Transcribed files directory
-└── venv/              # Python virtual environment
+├── setup.sh            # Setup script
+├── start_api.sh        # API start script
+├── README.md           # This file
+├── outputs/            # Transcribed files directory
+└── venv/               # Python virtual environment
 ```

-## Production Deployment
+## Production Deployment (Apache)

-For Apache deployment:
+### Prerequisites

-1. Ensure mod_php is enabled
-2. Point document root to this directory
-3. Run the API as a systemd service (see below)
+- Apache 2.4+
+- PHP 7.4+ with mod_php or PHP-FPM
+- Python 3.8+
+- FFmpeg
+- Root/sudo access for system configuration

-### Systemd Service (Linux)
+### Step 1: Install Required Apache Modules

-Create `/etc/systemd/system/whisper-api.service`:
+**Ubuntu/Debian:**
+```bash
+sudo apt update
+sudo apt install apache2 libapache2-mod-php php-curl php-xml php-mbstring
+sudo a2enmod rewrite
+sudo systemctl restart apache2
+```
+
+**CentOS/RHEL:**
+```bash
+sudo yum install httpd php php-curl php-xml php-mbstring
+sudo systemctl enable httpd
+sudo systemctl start httpd
+```
+
+### Step 2: Deploy Application Files
+
+```bash
+# Clone or copy your application
+cd /var/www
+sudo git clone https://bitbucket.org/zlalani/voice2text.git voice2text
+cd voice2text
+
+# Set up Python environment
+sudo chmod +x setup.sh
+sudo ./setup.sh
+
+# Set proper ownership and permissions
+sudo chown -R www-data:www-data /var/www/voice2text
+sudo chmod -R 755 /var/www/voice2text
+sudo chmod 777 /var/www/voice2text/outputs
+```
+
+### Step 3: Configure Apache Virtual Host
+
+Create `/etc/apache2/sites-available/voice2text.conf`:
+
+```apache
+<VirtualHost *:80>
+    ServerName voice2text.yourdomain.com
+    ServerAdmin admin@yourdomain.com
+
+    DocumentRoot /var/www/voice2text
+
+    <Directory /var/www/voice2text>
+        Options -Indexes +FollowSymLinks
+        AllowOverride All
+        Require all granted
+
+        # PHP settings for large uploads
+        php_value upload_max_filesize 350M
+        php_value post_max_size 350M
+        php_value max_execution_time 1200
+        php_value max_input_time 1200
+        php_value memory_limit 512M
+    </Directory>
+
+    # Protect sensitive files
+    <FilesMatch "^(config\.php|\.git|\.htaccess)">
+        Require all denied
+    </FilesMatch>
+
+    # Logging
+    ErrorLog ${APACHE_LOG_DIR}/voice2text-error.log
+    CustomLog ${APACHE_LOG_DIR}/voice2text-access.log combined
+</VirtualHost>
+```
+
+Enable the site:
+```bash
+sudo a2ensite voice2text.conf
+sudo systemctl reload apache2
+```
+
+### Step 4: Configure PHP for Large Uploads
+
+Edit `/etc/php/7.4/apache2/php.ini` (adjust version as needed):
+
+```ini
+upload_max_filesize = 350M
+post_max_size = 350M
+max_execution_time = 1200
+max_input_time = 1200
+memory_limit = 512M
+```
+
+Restart Apache:
+```bash
+sudo systemctl restart apache2
+```
+
+### Step 5: Setup Python API as Systemd Service
+
+Create `/etc/systemd/system/voice2text-api.service`:

 ```ini
 [Unit]
-Description=Whisper API Service
+Description=Voice to Text Whisper API
 After=network.target

 [Service]
 Type=simple
 User=www-data
-WorkingDirectory=/path/to/your/app
-ExecStart=/path/to/your/app/venv/bin/python /path/to/your/app/api.py
+Group=www-data
+WorkingDirectory=/var/www/voice2text
+Environment="PATH=/var/www/voice2text/venv/bin"
+ExecStart=/var/www/voice2text/venv/bin/python /var/www/voice2text/api.py
 Restart=always
+RestartSec=10
+
+# Security settings
+NoNewPrivileges=true
+PrivateTmp=true
+
+# Logging
+StandardOutput=append:/var/log/voice2text-api.log
+StandardError=append:/var/log/voice2text-api-error.log

 [Install]
 WantedBy=multi-user.target
 ```

-Enable and start:
+Enable and start the service:
 ```bash
-sudo systemctl enable whisper-api
-sudo systemctl start whisper-api
+sudo systemctl daemon-reload
+sudo systemctl enable voice2text-api
+sudo systemctl start voice2text-api
+
+# Check status
+sudo systemctl status voice2text-api
+
+# View logs
+sudo journalctl -u voice2text-api -f
+```
+
+### Step 6: Configure Firewall
+
+**UFW (Ubuntu):**
+```bash
+sudo ufw allow 'Apache Full'
+sudo ufw allow 5010/tcp  # Python API
+sudo ufw enable
+```
+
+**Firewalld (CentOS):**
+```bash
+sudo firewall-cmd --permanent --add-service=http
+sudo firewall-cmd --permanent --add-service=https
+sudo firewall-cmd --permanent --add-port=5010/tcp
+sudo firewall-cmd --reload
+```
+
+### Step 7: SSL Configuration (Optional but Recommended)
+
+Using Let's Encrypt with Certbot:
+
+```bash
+# Install Certbot
+sudo apt install certbot python3-certbot-apache
+
+# Get SSL certificate
+sudo certbot --apache -d voice2text.yourdomain.com
+
+# Auto-renewal is configured automatically
+# Test renewal with:
+sudo certbot renew --dry-run
+```
+
+### Step 8: Verify Deployment
+
+1. Check Apache status: `sudo systemctl status apache2`
+2. Check API status: `sudo systemctl status voice2text-api`
+3. Visit: `http://voice2text.yourdomain.com/check_api.php`
+4. Test file upload with a small audio file
+
+## Monitoring and Maintenance
+
+### Check API Status
+```bash
+# View API logs
+sudo journalctl -u voice2text-api -n 100
+
+# Check if API is responding
+curl http://localhost:5010/health
+```
+
+### Check Apache Logs
+```bash
+# Error log
+sudo tail -f /var/log/apache2/voice2text-error.log
+
+# Access log
+sudo tail -f /var/log/apache2/voice2text-access.log
+```
+
+### Restart Services
+```bash
+# Restart Apache
+sudo systemctl restart apache2
+
+# Restart Python API
+sudo systemctl restart voice2text-api
+
+# Restart both
+sudo systemctl restart apache2 voice2text-api
+```
+
+### Clean Old Files
+The `outputs/` directory can grow large. Set up a cron job to clean old files:
+
+```bash
+# Edit crontab
+sudo crontab -e
+
+# Add this line to delete files older than 24 hours daily at 2 AM
+0 2 * * * find /var/www/voice2text/outputs -type f -mtime +1 -delete
 ```

 ## Troubleshooting

+### API Issues
+
 **API not connecting:**
- Verify Python API is running on port 5010
- Check `config.php` has correct API URL
- Ensure firewall allows port 5010
+1. Check if API is running: `sudo systemctl status voice2text-api`
+2. Test health endpoint: `curl http://localhost:5010/health`
+3. Check API logs: `sudo journalctl -u voice2text-api -n 50`
+4. Verify firewall allows port 5010
+5. Visit `check_api.php` in browser for detailed status
+
+**API won't start:**
+1. Check Python version: `python3 --version` (must be 3.8+)
+2. Verify virtual environment: `ls -la venv/`
+3. Check dependencies: `source venv/bin/activate && pip list`
+4. Review error logs: `sudo journalctl -u voice2text-api -xe`
+5. Ensure FFmpeg is installed: `which ffmpeg`
+
+### Upload Issues
+
+**File upload fails:**
+1. Check file size limits in `php.ini`
+2. Verify `.htaccess` is being read (requires `AllowOverride All`)
+3. Check disk space: `df -h`
+4. Verify `outputs/` directory permissions: `ls -ld outputs/`
+5. Check Apache error log: `tail -f /var/log/apache2/error.log`
+
+**"413 Request Entity Too Large":**
+- If using Nginx as reverse proxy, add to nginx config:
+```nginx
+client_max_body_size 350M;
+```
+
+### Transcription Issues

 **Transcription fails:**
- Verify FFmpeg is installed: `ffmpeg -version`
- Check audio file format is supported
- Review API logs for errors
+1. Verify FFmpeg is installed: `ffmpeg -version`
+2. Check audio file format (supported: mp3, wav, m4a, etc.)
+3. Review API logs for specific errors
+4. Test with a small file first
+5. Ensure enough disk space in `/tmp`
+
+**Slow transcription:**
+1. Use a smaller Whisper model (`tiny` or `base`)
+2. Consider using GPU acceleration (requires CUDA setup)
+3. Upgrade server hardware (more CPU/RAM)
+4. Reduce audio file length/quality
+
+### Translation Issues
+
+**Translation fails:**
+1. Verify DeepL API key is valid in `config.php`
+2. Check DeepL API usage: https://www.deepl.com/pro-account
+3. Review API response for specific error messages
+4. Ensure internet connectivity for DeepL API
+
+### Permission Issues
+
+**403 Forbidden errors:**
+```bash
+sudo chown -R www-data:www-data /var/www/voice2text
+sudo chmod -R 755 /var/www/voice2text
+sudo chmod 777 /var/www/voice2text/outputs
+```
+
+**Can't write to outputs directory:**
+```bash
+sudo mkdir -p /var/www/voice2text/outputs
+sudo chown www-data:www-data /var/www/voice2text/outputs
+sudo chmod 777 /var/www/voice2text/outputs
+```
+
+### Performance Issues

 **Out of memory:**
- Use a smaller Whisper model (tiny or base)
- Reduce audio file size
- Increase system memory
+1. Use a smaller Whisper model (`tiny` or `base`)
+2. Increase PHP memory limit in `php.ini`
+3. Increase system swap space
+4. Add more RAM to server
+
+**Timeout errors:**
+1. Increase PHP `max_execution_time` in `php.ini`
+2. Increase Apache timeout in virtual host config
+3. Process smaller audio files
+4. Use faster Whisper model
+
+### Debugging Tips
+
+**Enable debug mode:**
+Add to `config.php`:
+```php
+error_reporting(E_ALL);
+ini_set('display_errors', 1);
+```
+
+**Check system resources:**
+```bash
+# CPU and memory usage
+htop
+
+# Disk space
+df -h
+
+# Check running processes
+ps aux | grep -E 'python|apache'
+```
+
+**Test components individually:**
+1. Test PHP: Create `test.php` with `<?php phpinfo(); ?>`
+2. Test Python API: `curl http://localhost:5010/health`
+3. Test file upload: Use small test file first
+4. Check browser console for JavaScript errors (F12)

 ## License