Unified email reports
This commit is contained in:
Frank John Begornia
417
DEPLOYMENT.md
Normal file
417
DEPLOYMENT.md
Normal file
@@ -0,0 +1,417 @@
|
||||
# Email Reports Deployment Checklist
|
||||
|
||||
## Pre-Deployment Setup
|
||||
|
||||
### 1. Configure Gitea Secrets
|
||||
|
||||
In your Gitea repository **Settings → Secrets**, add:
|
||||
|
||||
```
|
||||
DEPLOY_SSH_KEY = <your-ssh-private-key>
|
||||
DEPLOY_HOST = <server-ip-or-hostname>
|
||||
DEPLOY_USER = <ssh-username>
|
||||
REGISTRY_URL = <docker-registry-url> (optional, for version tags)
|
||||
REGISTRY_USER = <registry-username> (optional)
|
||||
REGISTRY_PASSWORD = <registry-password> (optional)
|
||||
```
|
||||
|
||||
### 2. Server Preparation
|
||||
|
||||
SSH into your production server:
|
||||
|
||||
```bash
|
||||
ssh user@your-server
|
||||
|
||||
# Create deployment directory
|
||||
sudo mkdir -p /var/www/apps/email_reports
|
||||
sudo chown $USER:$USER /var/www/apps/email_reports
|
||||
cd /var/www/apps/email_reports
|
||||
|
||||
# Create .env file with production values
|
||||
vim .env
|
||||
```
|
||||
|
||||
**Required .env variables:**
|
||||
```env
|
||||
DB_HOST=mysql # Your MySQL container name
|
||||
DB_PORT=3306
|
||||
DB_NAME=custom_design
|
||||
DB_USER=crew_user
|
||||
DB_PASS=your_secure_password # CHANGE THIS
|
||||
|
||||
SMTP_HOST=smtp.gmail.com
|
||||
SMTP_PORT=587
|
||||
SMTP_USER=mail@crewsportswear.com
|
||||
SMTP_PASS=your_gmail_app_password # Get from Gmail
|
||||
|
||||
EMAIL_TO=graphics@crewsportswear.com
|
||||
EMAIL_BCC=webmaster@crewsportswear.com,angelo@crewsportswear.com,production@crewsportswear.com
|
||||
|
||||
APP_URL=https://www.crewsportswear.com
|
||||
ADMIN_URL=https://admin.crewsportswear.app
|
||||
```
|
||||
|
||||
```bash
|
||||
# Secure .env
|
||||
chmod 600 .env
|
||||
|
||||
# Create data directories
|
||||
mkdir -p daily_order_reports
|
||||
touch email.log
|
||||
chmod 666 email.log
|
||||
|
||||
# Ensure Docker network exists
|
||||
docker network create crew-app-net || true
|
||||
```
|
||||
|
||||
### 3. Verify MySQL Access
|
||||
|
||||
Test database connectivity from server:
|
||||
|
||||
```bash
|
||||
# If MySQL is in a container:
|
||||
docker exec mysql_container_name mysql -u crew_user -p -e "SHOW DATABASES;"
|
||||
|
||||
# Verify network connectivity
|
||||
docker run --rm --network crew-app-net alpine ping -c 3 mysql
|
||||
```
|
||||
|
||||
### 4. Get Gmail App Password
|
||||
|
||||
1. Go to https://myaccount.google.com/apppasswords
|
||||
2. Create new app password for "Email Reports"
|
||||
3. Copy the 16-character password
|
||||
4. Add to `.env` as `SMTP_PASS`
|
||||
|
||||
---
|
||||
|
||||
## Deployment Workflow
|
||||
|
||||
### Option 1: Automated (Recommended)
|
||||
|
||||
```bash
|
||||
# From your local machine
|
||||
cd email_reports
|
||||
|
||||
git add .
|
||||
git commit -m "Deploy email reports container"
|
||||
git push origin main
|
||||
```
|
||||
|
||||
Gitea Actions will automatically:
|
||||
- ✅ Build Docker image
|
||||
- ✅ Transfer to server
|
||||
- ✅ Deploy to /var/www/apps/email_reports
|
||||
- ✅ Start container with cron
|
||||
- ✅ Verify deployment
|
||||
|
||||
Watch the workflow in Gitea: **Actions** tab
|
||||
|
||||
### Option 2: Manual Deployment
|
||||
|
||||
SSH to server and deploy manually:
|
||||
|
||||
```bash
|
||||
cd /var/www/apps/email_reports
|
||||
|
||||
# Pull latest code (if using git on server)
|
||||
git pull
|
||||
|
||||
# Or copy files manually via scp
|
||||
scp docker-compose.yml user@server:/var/www/apps/email_reports/
|
||||
|
||||
# Build and deploy
|
||||
docker-compose build
|
||||
docker-compose up -d
|
||||
|
||||
# Verify
|
||||
docker ps | grep email_reports
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Post-Deployment Verification
|
||||
|
||||
### 1. Check Container Status
|
||||
|
||||
```bash
|
||||
# Container is running
|
||||
docker ps --filter name=email_reports_crew
|
||||
|
||||
# Expected output:
|
||||
# CONTAINER ID IMAGE STATUS NAMES
|
||||
# abc123... email_reports_crew:latest Up 2 minutes email_reports_crew
|
||||
```
|
||||
|
||||
### 2. Verify Cron is Running
|
||||
|
||||
```bash
|
||||
docker exec email_reports_crew ps aux | grep crond
|
||||
|
||||
# Should show: crond -f -l 2
|
||||
```
|
||||
|
||||
### 3. Check Cron Schedule
|
||||
|
||||
```bash
|
||||
docker exec email_reports_crew crontab -l
|
||||
|
||||
# Expected output:
|
||||
# 55 23 * * * cd /app && php index.php >> /var/log/cron.log 2>&1
|
||||
```
|
||||
|
||||
### 4. Test Database Connection
|
||||
|
||||
```bash
|
||||
docker exec email_reports_crew php -r "
|
||||
\$host = getenv('DB_HOST');
|
||||
\$db = getenv('DB_NAME');
|
||||
\$user = getenv('DB_USER');
|
||||
\$pass = getenv('DB_PASS');
|
||||
new PDO(\"mysql:host=\$host;dbname=\$db\", \$user, \$pass);
|
||||
echo 'Database connection: OK\n';
|
||||
"
|
||||
```
|
||||
|
||||
### 5. Run Manual Test
|
||||
|
||||
```bash
|
||||
# Execute report immediately (don't wait for cron)
|
||||
docker exec email_reports_crew php /app/index.php
|
||||
|
||||
# Check output
|
||||
docker exec email_reports_crew cat /app/email.log | tail -5
|
||||
```
|
||||
|
||||
Expected log entry:
|
||||
```
|
||||
2026-01-02 15:30:00 successfully sent
|
||||
```
|
||||
OR
|
||||
```
|
||||
2026-01-02 15:30:00 No order for today
|
||||
```
|
||||
|
||||
### 6. Verify Email Sent
|
||||
|
||||
Check your inbox at `graphics@crewsportswear.com` for test email.
|
||||
|
||||
### 7. Check Logs
|
||||
|
||||
```bash
|
||||
# Container logs
|
||||
docker logs email_reports_crew
|
||||
|
||||
# Cron logs
|
||||
docker exec email_reports_crew tail -f /var/log/cron.log
|
||||
|
||||
# Email execution logs
|
||||
docker exec email_reports_crew tail -f /app/email.log
|
||||
|
||||
# CSV files generated
|
||||
docker exec email_reports_crew ls -lh /app/daily_order_reports/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Monitoring
|
||||
|
||||
### View Real-time Logs
|
||||
|
||||
```bash
|
||||
# Follow cron execution
|
||||
docker logs -f email_reports_crew
|
||||
|
||||
# Follow email log
|
||||
docker exec email_reports_crew tail -f /app/email.log
|
||||
```
|
||||
|
||||
### Check Next Scheduled Run
|
||||
|
||||
Cron runs at **23:55 Central Time daily**
|
||||
|
||||
```bash
|
||||
# Current time in container
|
||||
docker exec email_reports_crew date
|
||||
|
||||
# Should show: America/Chicago timezone
|
||||
docker exec email_reports_crew cat /etc/timezone
|
||||
```
|
||||
|
||||
### Health Check
|
||||
|
||||
```bash
|
||||
# Container health status
|
||||
docker inspect email_reports_crew | grep -A 5 Health
|
||||
|
||||
# Manual health check
|
||||
docker exec email_reports_crew ps aux | grep crond
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Container Won't Start
|
||||
|
||||
```bash
|
||||
# View startup logs
|
||||
docker logs email_reports_crew
|
||||
|
||||
# Check compose file
|
||||
cd /var/www/apps/email_reports
|
||||
cat docker-compose.yml
|
||||
|
||||
# Verify .env exists
|
||||
ls -la .env
|
||||
```
|
||||
|
||||
### Database Connection Failed
|
||||
|
||||
```bash
|
||||
# Test network connectivity
|
||||
docker exec email_reports_crew ping mysql
|
||||
|
||||
# Verify database credentials in .env
|
||||
docker exec email_reports_crew env | grep DB_
|
||||
```
|
||||
|
||||
### Email Not Sending
|
||||
|
||||
```bash
|
||||
# Enable debug mode
|
||||
docker exec email_reports_crew sed -i 's|// \$mail->SMTPDebug = 3;|\$mail->SMTPDebug = 3;|' /app/index.php
|
||||
|
||||
# Run manually with debug output
|
||||
docker exec email_reports_crew php /app/index.php
|
||||
|
||||
# Check SMTP credentials
|
||||
docker exec email_reports_crew env | grep SMTP_
|
||||
```
|
||||
|
||||
### Cron Not Running
|
||||
|
||||
```bash
|
||||
# Check cron daemon
|
||||
docker exec email_reports_crew ps aux | grep crond
|
||||
|
||||
# Restart container
|
||||
docker restart email_reports_crew
|
||||
|
||||
# Verify crontab
|
||||
docker exec email_reports_crew crontab -l
|
||||
```
|
||||
|
||||
### Wrong Timezone
|
||||
|
||||
```bash
|
||||
# Check timezone
|
||||
docker exec email_reports_crew date
|
||||
docker exec email_reports_crew cat /etc/timezone
|
||||
|
||||
# Should be: America/Chicago
|
||||
# If not, rebuild image
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Rollback
|
||||
|
||||
If deployment fails:
|
||||
|
||||
```bash
|
||||
cd /var/www/apps/email_reports
|
||||
|
||||
# Stop and remove container
|
||||
docker-compose down
|
||||
|
||||
# Load previous image (if kept)
|
||||
docker load < /tmp/email_reports_crew_backup.tar.gz
|
||||
|
||||
# Or pull from registry
|
||||
docker pull your-registry/email_reports_crew:previous-version
|
||||
|
||||
# Start with old image
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Deployment Checklist
|
||||
|
||||
- [ ] Gitea secrets configured
|
||||
- [ ] Server directory created: `/var/www/apps/email_reports`
|
||||
- [ ] `.env` file created with all variables
|
||||
- [ ] Database credentials tested
|
||||
- [ ] Gmail app password obtained and configured
|
||||
- [ ] Docker network `crew-app-net` exists
|
||||
- [ ] Code pushed to `main` branch (triggers workflow)
|
||||
- [ ] Workflow completed successfully (green checkmark)
|
||||
- [ ] Container is running: `docker ps | grep email_reports`
|
||||
- [ ] Cron is running: `ps aux | grep crond`
|
||||
- [ ] Manual test executed successfully
|
||||
- [ ] Email received by recipients
|
||||
- [ ] Logs showing successful execution
|
||||
- [ ] Scheduled for next automatic run at 23:55 CT
|
||||
|
||||
---
|
||||
|
||||
## For MerchBay Reports
|
||||
|
||||
Repeat the same process in a separate directory:
|
||||
|
||||
```bash
|
||||
# On server
|
||||
sudo mkdir -p /var/www/apps/email_reports_merchbay
|
||||
# ... follow same steps with merchbay database/credentials
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Maintenance
|
||||
|
||||
### Update Recipients
|
||||
|
||||
```bash
|
||||
# Edit .env on server
|
||||
cd /var/www/apps/email_reports
|
||||
vim .env
|
||||
|
||||
# Update EMAIL_TO or EMAIL_BCC
|
||||
# Then restart container
|
||||
docker-compose restart
|
||||
```
|
||||
|
||||
### Change Schedule
|
||||
|
||||
Edit Dockerfile, rebuild, and redeploy:
|
||||
|
||||
```dockerfile
|
||||
# Change from 23:55 to 22:00
|
||||
RUN echo "0 22 * * * cd /app && php index.php" > /etc/crontabs/root
|
||||
```
|
||||
|
||||
### View Historical Reports
|
||||
|
||||
```bash
|
||||
# List all generated CSVs
|
||||
docker exec email_reports_crew ls -lh /app/daily_order_reports/
|
||||
|
||||
# Download specific report
|
||||
docker cp email_reports_crew:/app/daily_order_reports/daily_order_report_2026-01-02.csv .
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Success Criteria
|
||||
|
||||
✅ Container running continuously
|
||||
✅ Cron daemon active
|
||||
✅ Database connectivity confirmed
|
||||
✅ Manual test sends email
|
||||
✅ Recipients receive reports
|
||||
✅ CSV files generated in `/app/daily_order_reports/`
|
||||
✅ Logs show execution history
|
||||
✅ Scheduled to run at 23:55 CT daily
|
||||
|
||||
**Deployment Complete! 🎉**
|
||||
Reference in New Issue
Block a user