147 lines
4.2 KiB
Markdown
147 lines
4.2 KiB
Markdown
# 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:**
|
|
|
|
```bash
|
|
export HM_QC_ENV=dev
|
|
```
|
|
|
|
**For permanent setup (add to your `~/.bashrc` or `~/.zshrc`):**
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
export HM_QC_ENV=dev
|
|
python launchers/HM_launcher_CLI.py /path/to/test.pdf ./tmp/reports/test_report.html
|
|
```
|
|
|
|
### Test Image Files
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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):
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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
|