email_reports/DEPLOYMENT.md

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:

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:

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

# 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:

# 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)

# 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:

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

# 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

docker exec email_reports_crew ps aux | grep crond

# Should show: crond -f -l 2

3. Check Cron Schedule

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

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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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:

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:

# On server
sudo mkdir -p /var/www/apps/email_reports_merchbay
# ... follow same steps with merchbay database/credentials

---

Maintenance

Update Recipients

# 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:

# Change from 23:55 to 22:00
RUN echo "0 22 * * * cd /app && php index.php" > /etc/crontabs/root

View Historical Reports

# 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! 🎉