survey_custom_certificate_template/docs/ADMIN_GUIDE.md

# Survey Custom Certificate Template - Administrator Guide

## Table of Contents

1. [Installation](#installation)
2. [System Requirements](#system-requirements)
3. [Configuration](#configuration)
4. [Security](#security)
5. [Monitoring](#monitoring)
6. [Troubleshooting](#troubleshooting)
7. [Maintenance](#maintenance)

---

## Installation

### Prerequisites

Before installing this module, ensure the following are in place:

1. **Odoo 19** installed and running
2. **Survey module** installed and activated
3. **Python dependencies**:
   - `python-docx` (for DOCX parsing)
4. **System dependencies**:
   - LibreOffice (for PDF conversion)

### Installing Python Dependencies

```bash
# Activate your Odoo virtual environment
source /path/to/odoo/venv/bin/activate

# Install python-docx
pip install python-docx
```

### Installing LibreOffice

LibreOffice is required for converting DOCX files to PDF format.

#### Ubuntu/Debian
```bash
sudo apt-get update
sudo apt-get install libreoffice
```

#### CentOS/RHEL
```bash
sudo yum install libreoffice
```

#### macOS
```bash
brew install --cask libreoffice
```

#### Verify Installation
```bash
libreoffice --version
```

You should see output like: `LibreOffice 7.x.x.x`

### Installing the Module

1. Copy the module to your Odoo addons directory:
   ```bash
   cp -r survey_custom_certificate_template /path/to/odoo/addons/
   ```

2. Update the addons list:
   - Navigate to **Apps** in Odoo
   - Click **Update Apps List**
   - Search for "Survey Custom Certificate Template"

3. Install the module:
   - Click **Install** on the module card

4. Verify installation:
   - Open a survey
   - Check that "Custom Template" appears in the Certification Template dropdown

---

## System Requirements

### Minimum Requirements

- **Odoo**: Version 19.0 or later
- **Python**: 3.8 or later
- **RAM**: 2 GB minimum (4 GB recommended)
- **Disk Space**: 500 MB for LibreOffice + space for certificate storage
- **CPU**: 2 cores minimum (for PDF conversion)

### Software Dependencies

| Component | Version | Purpose |
|-----------|---------|---------|
| python-docx | >= 0.8.11 | DOCX parsing and manipulation |
| LibreOffice | >= 6.0 | PDF conversion |
| Odoo Survey | 19.0 | Base survey functionality |

### Server Configuration

#### File Upload Limits

Ensure your server allows file uploads up to 10 MB:

**Nginx Configuration** (`/etc/nginx/nginx.conf`):
```nginx
http {
    client_max_body_size 10M;
}
```

**Odoo Configuration** (`odoo.conf`):
```ini
[options]
limit_memory_hard = 2684354560
limit_memory_soft = 2147483648
limit_request = 8192
limit_time_cpu = 600
limit_time_real = 1200
```

#### LibreOffice Configuration

For production environments, consider:

1. **Headless Mode**: LibreOffice runs in headless mode (no GUI)
2. **Process Limits**: Limit concurrent LibreOffice processes to prevent resource exhaustion
3. **Timeout Settings**: Configure appropriate timeouts for PDF conversion

---

## Configuration

### Module Configuration

No additional configuration is required after installation. The module extends the existing Survey module automatically.

### Access Rights

The module uses Odoo's standard Survey access groups:

| Group | Access Level | Permissions |
|-------|--------------|-------------|
| Survey User | Read | View certificates |
| Survey Manager | Full | Upload, configure, delete templates |

To grant access:
1. Navigate to **Settings** → **Users & Companies** → **Users**
2. Select a user
3. In the **Access Rights** tab, assign **Survey / Manager** role

### File Storage

Certificate templates are stored in the database as binary fields. Generated certificates can be stored as:

1. **Attachments**: Linked to survey.user_input records
2. **Temporary Files**: For preview generation (automatically cleaned up)

**Storage Location**: Odoo filestore (`~/.local/share/Odoo/filestore/[database_name]/`)

### Performance Tuning

#### PDF Conversion Optimization

For high-volume certificate generation:

1. **Queue-Based Processing**: Consider implementing a job queue for certificate generation
2. **Caching**: Cache parsed templates to avoid repeated parsing
3. **Batch Processing**: Generate certificates in batches during off-peak hours

#### Resource Limits

Monitor and adjust these limits based on your usage:

```python
# In certificate_generator.py
LIBREOFFICE_TIMEOUT = 60  # seconds
MAX_CONCURRENT_CONVERSIONS = 3
TEMP_FILE_CLEANUP_INTERVAL = 3600  # seconds
```

---

## Security

### Access Control

The module implements several security measures:

1. **Group-Based Access**: Only Survey Managers can upload and configure templates
2. **Field-Level Security**: Sensitive fields restricted to appropriate groups
3. **Validation**: All user inputs are validated and sanitized

### Data Sanitization

The module automatically sanitizes:

- **Placeholder values**: HTML escaping, control character removal
- **Custom text**: Length limits, special character filtering
- **Field names**: Alphanumeric validation, injection prevention

### File Validation

Uploaded files are validated for:

- **File type**: Must be valid DOCX format
- **File size**: Maximum 10 MB
- **Structure**: Valid DOCX structure using python-docx
- **Content**: No executable content or macros

### Security Best Practices

✓ **Limit upload access**: Only trusted users should have Survey Manager role  
✓ **Monitor logs**: Regularly review certificate generation logs  
✓ **Update dependencies**: Keep python-docx and LibreOffice updated  
✓ **Backup templates**: Maintain backups of certificate templates  
✓ **Audit trail**: Monitor who uploads and modifies templates  

---

## Monitoring

### Logging

The module logs all significant events:

#### Log Levels

- **INFO**: Successful operations (template upload, certificate generation)
- **WARNING**: Non-critical issues (missing data, sanitization applied)
- **ERROR**: Failed operations (LibreOffice errors, validation failures)

#### Log Locations

**Odoo Log File**: `/var/log/odoo/odoo-server.log`

#### Key Log Messages

```
# Successful template upload
INFO: Saved custom certificate template for survey 123 with 5 placeholder mappings

# Certificate generation
INFO: Successfully generated certificate for user_input 456 (size: 245678 bytes)

# LibreOffice error
ERROR: Certificate generation runtime error for user_input 789: LibreOffice not found

# Data retrieval
DEBUG: Retrieved certificate data for user_input 101: 8 fields populated
```

### Monitoring Commands

#### Check LibreOffice Availability
```bash
which libreoffice
libreoffice --version
```

#### Monitor Certificate Generation
```bash
# View recent certificate generation logs
tail -f /var/log/odoo/odoo-server.log | grep "certificate"

# Count successful generations today
grep "Successfully generated certificate" /var/log/odoo/odoo-server.log | grep "$(date +%Y-%m-%d)" | wc -l

# Find failed generations
grep "Certificate generation.*error" /var/log/odoo/odoo-server.log
```

#### Check Disk Space
```bash
# Check filestore disk usage
du -sh ~/.local/share/Odoo/filestore/[database_name]/

# Check temp directory
du -sh /tmp/
```

### Performance Metrics

Monitor these metrics:

1. **Certificate Generation Time**: Should be < 10 seconds per certificate
2. **PDF Conversion Success Rate**: Should be > 99%
3. **Template Upload Success Rate**: Should be > 95%
4. **Disk Space Usage**: Monitor filestore growth

### Alerts

Set up alerts for:

- **LibreOffice Failures**: More than 5 failures per hour
- **Disk Space**: Filestore > 80% capacity
- **Generation Errors**: More than 10% failure rate
- **Long Processing Times**: Certificate generation > 30 seconds

---

## Troubleshooting

### Common Administrator Issues

#### Issue: LibreOffice Not Found

**Symptoms:**
- Error: "LibreOffice not found or not accessible"
- Certificate generation fails
- Preview generation fails

**Diagnosis:**
```bash
# Check if LibreOffice is installed
which libreoffice

# Check if it's executable
libreoffice --version

# Check PATH
echo $PATH
```

**Solutions:**
1. Install LibreOffice (see Installation section)
2. Ensure LibreOffice is in system PATH
3. Restart Odoo service after installation:
   ```bash
   sudo systemctl restart odoo
   ```

---

#### Issue: PDF Conversion Timeout

**Symptoms:**
- Error: "PDF conversion timed out"
- Long processing times
- Certificates not generated

**Diagnosis:**
```bash
# Check system load
top

# Check LibreOffice processes
ps aux | grep soffice

# Check for zombie processes
ps aux | grep defunct
```

**Solutions:**
1. Increase timeout in configuration
2. Kill stuck LibreOffice processes:
   ```bash
   pkill -9 soffice
   ```
3. Restart Odoo service
4. Consider increasing server resources

---

#### Issue: High Memory Usage

**Symptoms:**
- Server slowdown during certificate generation
- Out of memory errors
- Odoo crashes

**Diagnosis:**
```bash
# Monitor memory usage
free -h
watch -n 1 free -h

# Check Odoo memory usage
ps aux | grep odoo

# Check LibreOffice memory usage
ps aux | grep soffice
```

**Solutions:**
1. Limit concurrent certificate generations
2. Increase server RAM
3. Implement queue-based processing
4. Clean up temporary files:
   ```bash
   find /tmp -name "cert_*" -mtime +1 -delete
   ```

---

#### Issue: Permission Denied Errors

**Symptoms:**
- Error: "Permission denied" when generating certificates
- Cannot write to temp directory
- Cannot execute LibreOffice

**Diagnosis:**
```bash
# Check temp directory permissions
ls -la /tmp

# Check Odoo user
ps aux | grep odoo

# Check LibreOffice permissions
ls -la $(which libreoffice)
```

**Solutions:**
1. Ensure Odoo user has write access to /tmp:
   ```bash
   sudo chmod 1777 /tmp
   ```
2. Ensure Odoo user can execute LibreOffice:
   ```bash
   sudo chmod +x /usr/bin/libreoffice
   ```
3. Check SELinux/AppArmor policies (if applicable)

---

#### Issue: Database Errors

**Symptoms:**
- Error: "Unable to save template configuration"
- Database constraint violations
- Rollback errors

**Diagnosis:**
```bash
# Check database logs
sudo tail -f /var/log/postgresql/postgresql-*.log

# Check database connections
sudo -u postgres psql -c "SELECT * FROM pg_stat_activity WHERE datname='your_database';"
```

**Solutions:**
1. Check database disk space
2. Verify database user permissions
3. Check for database locks:
   ```sql
   SELECT * FROM pg_locks WHERE NOT granted;
   ```
4. Restart database if necessary

---

### Diagnostic Commands

#### Generate Diagnostic Report
```bash
#!/bin/bash
# Save as: check_certificate_module.sh

echo "=== Certificate Module Diagnostic Report ==="
echo "Date: $(date)"
echo ""

echo "=== LibreOffice Status ==="
which libreoffice
libreoffice --version
echo ""

echo "=== Python Dependencies ==="
pip list | grep python-docx
echo ""

echo "=== Disk Space ==="
df -h | grep -E "Filesystem|/tmp|filestore"
echo ""

echo "=== Memory Usage ==="
free -h
echo ""

echo "=== Recent Certificate Logs ==="
tail -20 /var/log/odoo/odoo-server.log | grep -i certificate
echo ""

echo "=== LibreOffice Processes ==="
ps aux | grep soffice | grep -v grep
echo ""

echo "=== Temp Files ==="
ls -lh /tmp/cert_* 2>/dev/null | wc -l
echo " certificate temp files found"
```

Run with:
```bash
chmod +x check_certificate_module.sh
./check_certificate_module.sh
```

---

## Maintenance

### Regular Maintenance Tasks

#### Daily
- Monitor certificate generation logs
- Check for failed generations
- Verify LibreOffice is running

#### Weekly
- Review disk space usage
- Clean up old temporary files
- Check for stuck LibreOffice processes

#### Monthly
- Update python-docx if new version available
- Review and archive old certificates
- Audit template configurations
- Review access logs

### Backup Procedures

#### Backup Certificate Templates

Templates are stored in the database, so they're included in regular database backups. For additional safety:

```bash
# Export templates from database
psql your_database -c "COPY (SELECT id, title, custom_cert_template_filename FROM survey_survey WHERE has_custom_certificate = true) TO '/backup/certificate_templates.csv' CSV HEADER;"
```

#### Backup Generated Certificates

```bash
# Backup filestore
tar -czf certificate_backup_$(date +%Y%m%d).tar.gz ~/.local/share/Odoo/filestore/[database_name]/
```

### Update Procedures

#### Updating the Module

1. **Backup**: Create database backup before updating
2. **Update code**: Replace module files with new version
3. **Update module**: In Odoo, go to Apps → Update
4. **Test**: Verify certificate generation still works
5. **Monitor**: Watch logs for any errors

#### Updating Dependencies

```bash
# Update python-docx
pip install --upgrade python-docx

# Update LibreOffice (Ubuntu/Debian)
sudo apt-get update
sudo apt-get upgrade libreoffice

# Restart Odoo
sudo systemctl restart odoo
```

### Cleanup Procedures

#### Clean Temporary Files

```bash
# Remove old certificate temp files (older than 1 day)
find /tmp -name "cert_*" -mtime +1 -delete

# Remove old LibreOffice temp files
find /tmp -name "OSL_PIPE_*" -mtime +1 -delete
```

#### Clean Old Certificates

If storing certificates as attachments, periodically archive or delete old ones:

```sql
-- Find old certificate attachments (older than 1 year)
SELECT id, name, create_date 
FROM ir_attachment 
WHERE name LIKE '%certificate%' 
AND create_date < NOW() - INTERVAL '1 year';

-- Archive to external storage before deleting
```

### Performance Optimization

#### Database Optimization

```sql
-- Vacuum and analyze certificate-related tables
VACUUM ANALYZE survey_survey;
VACUUM ANALYZE survey_user_input;
VACUUM ANALYZE ir_attachment;
```

#### Index Optimization

```sql
-- Add index for faster certificate lookups
CREATE INDEX IF NOT EXISTS idx_survey_has_custom_cert 
ON survey_survey(has_custom_certificate) 
WHERE has_custom_certificate = true;
```

---

## Support and Resources

### Log Analysis

For detailed troubleshooting, enable debug logging:

```ini
# In odoo.conf
[options]
log_level = debug
log_handler = :DEBUG,werkzeug:WARNING,odoo.addons.survey_custom_certificate_template:DEBUG
```

### Getting Help

1. **Check logs**: Always review logs first
2. **Run diagnostics**: Use the diagnostic script provided
3. **Community forums**: Search Odoo community for similar issues
4. **Module documentation**: Refer to USER_GUIDE.md for user-facing issues

### Useful Commands Reference

```bash
# Restart Odoo
sudo systemctl restart odoo

# View Odoo logs in real-time
tail -f /var/log/odoo/odoo-server.log

# Check Odoo status
sudo systemctl status odoo

# Kill stuck LibreOffice processes
pkill -9 soffice

# Check disk space
df -h

# Check memory usage
free -h

# Check running processes
ps aux | grep -E "odoo|soffice"
```

---

**Version**: 1.0  
**Last Updated**: 2024  
**Module**: survey_custom_certificate_template  
**Odoo Version**: 19.0