hm_qc/DEV_SETUP.md

Development Environment Setup

This guide explains how to set up and use the development environment for local testing without affecting production code.

Environment Configuration

The HM QC system now supports two environments:

• Production (default): Uses paths at /opt/QC
• Development: Uses relative paths in your local repository

Setting Up Development Environment

1. Set Environment Variable

For current terminal session:

export HM_QC_ENV=dev

For permanent setup (add to your ~/.bashrc or ~/.zshrc):

echo 'export HM_QC_ENV=dev' >> ~/.bashrc  # or ~/.zshrc
source ~/.bashrc  # or source ~/.zshrc

2. Verify Configuration

You can verify your environment setup using the config module:

cd /Users/nickviljoen/Desktop/HM_QC_Bitbucket/hm_qc
python -c "import config; config.print_config()"

This will display:

============================================================
HM QC Environment Configuration
============================================================
environment         : dev
base_dir            : /Users/nickviljoen/Desktop/HM_QC_Bitbucket/hm_qc
profiles_dir        : /Users/nickviljoen/Desktop/HM_QC_Bitbucket/hm_qc/profiles
checks_dir          : /Users/nickviljoen/Desktop/HM_QC_Bitbucket/hm_qc/checks
working_dir         : /Users/nickviljoen/Desktop/HM_QC_Bitbucket/hm_qc/tmp/HM_working
reports_dir         : /Users/nickviljoen/Desktop/HM_QC_Bitbucket/hm_qc/tmp/reports
pdf_profile_path    : /Users/nickviljoen/Desktop/HM_QC_Bitbucket/hm_qc/profiles/HM.json
image_profile_path  : /Users/nickviljoen/Desktop/HM_QC_Bitbucket/hm_qc/profiles/HM_image.json
============================================================

Running Tests Locally

Test PDF Files

export HM_QC_ENV=dev
python launchers/HM_launcher_CLI.py /path/to/test.pdf ./tmp/reports/test_report.html

Test Image Files

export HM_QC_ENV=dev
python launchers/HM_launcher_CLI.py /path/to/test.jpg ./tmp/reports/test_report.html

Example with Your Test Files

export HM_QC_ENV=dev
python launchers/HM_launcher_CLI.py ~/Downloads/test_file.pdf ./tmp/reports/report.html

Directory Structure (Development)

When running in development mode, temporary files and reports are stored in:

hm_qc/
├── tmp/
│   ├── HM_working/      # Working directory for processing
│   └── reports/         # Generated HTML reports
├── profiles/            # QC profiles (HM.json, HM_image.json)
├── checks/              # Check modules
├── launchers/           # CLI launchers
└── config.py            # Environment configuration

These tmp/ directories are created automatically and should be added to .gitignore.

Running in Production

To run in production mode (uses /opt/QC paths):

unset HM_QC_ENV  # or export HM_QC_ENV=production
python launchers/HM_launcher_CLI.py /path/to/file.pdf /opt/QC/reports/report.html

Adding tmp/ to .gitignore

The development environment creates temporary directories that should not be committed:

echo 'tmp/' >> .gitignore

Troubleshooting

"ModuleNotFoundError: No module named 'qc_module'"

Make sure you're running from the repository root and that qc_module.py exists:

cd /Users/nickviljoen/Desktop/HM_QC_Bitbucket/hm_qc
ls qc_module.py  # Should exist

"Environment variable not set"

If the launcher runs in production mode unexpectedly, ensure the environment variable is set:

echo $HM_QC_ENV  # Should output: dev

"Permission denied" errors

In development mode, you shouldn't need root permissions. If you see permission errors, verify HM_QC_ENV=dev is set.

Benefits of This Setup

✅ No production code changes - Production paths remain at /opt/QC ✅ Easy switching - Toggle between dev/prod with environment variable ✅ Isolated testing - Dev files stored in tmp/ directory ✅ Version control safe - Add tmp/ to .gitignore ✅ Team friendly - Each developer can test independently

Next Steps

1. Set HM_QC_ENV=dev in your shell profile
2. Add tmp/ to .gitignore
3. Run tests with your local files
4. When deploying to production, the system automatically uses production paths