Skip to content

Start Script Reference

The Heritage Data Processor Start Script (start_hdp.sh) performs pre-start validation and launches the application with proper environment configuration.

Overview

This script validates the installation, activates the Python environment, verifies dependencies, and starts the application through npm.

Usage

Basic Usage

./start_hdp.sh

Performs all checks in standard mode (warnings only for version mismatches).

Command-Line Options

./start_hdp.sh [OPTIONS]

Options:

  • --strict: Fail on any version mismatches or outdated packages. Default: warn only
  • --help: Display usage information and exit

Usage Examples

Example 1: Standard Start

./start_hdp.sh

Performs all checks, warns about issues but continues unless critical.

Example 2: Strict Mode

./start_hdp.sh --strict

Fails immediately if any version mismatches or outdated packages are detected.

Example 3: Help Information

./start_hdp.sh --help

Displays usage information:

Usage: ./start_hdp.sh [--strict]

Options:
  --strict    Fail on any version mismatches (default: warn only)
  --help      Show this help message

Requirements

Prerequisites

  • Installation: Complete installation must be finished first
  • Working Directory: Must be run from project root directory
  • Virtual Environment: .venv directory must exist with proper Python installation
  • Node Modules: node_modules directory must exist

Startup Steps

Step 1: Project Structure Validation

Verifies the script is running from the correct directory.

Validation Checks:

  • Presence of package.json
  • Presence of requirements.txt

Error Message:

🔴 Not in project root directory.
This script must be run from the Heritage Data Processor root directory.

Expected files:
 - package.json
 - requirements.txt

Current directory: /home/user/wrong-location

Step 2: Virtual Environment Activation

Activates the Python virtual environment located at .venv.

Process:

  1. Existence Check: Verifies .venv directory exists
  2. Activation Script: Sources .venv/bin/activate
  3. Verification: Confirms VIRTUAL_ENV environment variable is set
  4. Version Display: Shows activated Python version

Error Scenarios:

Virtual Environment Not Found:

🔴 Virtual environment not found: .venv
Run the installation script first:
 ./install_hdp.sh

Activation Script Missing:

🔴 Virtual environment activation script not found.
Virtual environment may be corrupted. Try:
 rm -rf .venv
 uv venv .venv --python=3.11

Activation Failed:

🔴 Failed to activate virtual environment

Step 3: Python Dependencies Verification

Validates that all required Python packages are installed with correct versions.

Verification Process:

  1. Parse Requirements: Reads requirements.txt line by line, skipping comments and empty lines
  2. List Installed: Uses uv pip list --format=freeze to get installed packages
  3. Match Packages: Performs case-insensitive comparison (PyPI is case-insensitive)
  4. Version Check: For packages with == version specifiers, verifies exact match

Package Extraction:

Uses regex to extract package name before operators:

pkg_name=$(echo "$pkg_spec" | sed -E 's/^([a-zA-Z0-9_-]+).*/\1/')

Missing Packages:

🔴 Missing Python packages (3):
 - flask==2.3.0
 - pandas==2.0.0
 - requests==2.28.0

Install missing packages:
 uv pip install -r requirements.txt

Version Mismatches:

In standard mode (default):

⚠️ Version mismatches detected (2):
 - numpy: required 1.24.0, installed 1.23.5
 - scipy: required 1.10.1, installed 1.10.0

⚠️ Continuing despite version mismatches (use --strict to fail)
[INFO] To fix mismatches, run: uv pip install -r requirements.txt

In strict mode (--strict):

🔴 Version mismatches found in strict mode.
Update dependencies:
 uv pip install -r requirements.txt --upgrade

Success Message:

✅ Python dependencies verified (47 packages)

Step 4: Node.js Dependencies Verification

Validates Node.js dependencies are installed and checks for outdated packages.

Checks Performed:

  1. npm Availability: Verifies npm command is accessible
  2. node_modules Existence: Confirms directory exists
  3. package.json Existence: Validates package file is present
  4. Start Script: Verifies start script is defined in package.json
  5. Outdated Check: Runs npm outdated to detect outdated packages

Module Count:

Reports number of installed modules:

[DEBUG] Installed Node modules: 523

Outdated Packages:

In standard mode:

⚠️ Found 12 outdated Node.js package(s)
⚠️ Run 'npm outdated' to see details
[INFO] Continuing despite outdated packages (use --strict to fail)

In strict mode:

🔴 Outdated packages found in strict mode.
Update dependencies:
 npm update

Missing Start Script:

🔴 No 'start' script defined in package.json.
Add a start script to package.json:
 "scripts": {
   "start": "your-start-command"
 }

Step 5: Application Startup

Launches the application using npm start.

Environment Export:

Before starting, exports virtual environment variables for child processes:

export VIRTUAL_ENV
export PATH="$VIRTUAL_ENV/bin:$PATH"

Execution:

npm start

Output Streaming:

All npm output is displayed in real-time and logged to the log file.

Process Control:

The script runs in the foreground and takes over the terminal until the application is stopped (Ctrl+C).

Failure Handling:

If npm start exits with non-zero code:

🔴 Application exited with error.
Check the log file: start_hdp_20251021_143500.log
Check application logs for more details

Logging

Log File

Format: start_hdp_YYYYMMDD_HHMMSS.log

Content: Captures all validation steps, checks, and application output

Location: Created in current working directory

Log Functions

Available Functions:

  • error_exit(): Logs error and exits with code 1
  • warning(): Logs warning with yellow color
  • info(): Logs informational message
  • success(): Logs success with green checkmark
  • debug(): Logs debug information in blue
  • step_header(): Displays cyan-colored section headers

Error Handling

Exit on Error

The script uses set -euo pipefail for strict error handling:

  • set -e: Exit on any command failure
  • set -u: Exit on undefined variable reference
  • set -o pipefail: Exit if any command in pipeline fails

Cleanup Trap

Registers cleanup function to deactivate virtual environment on exit:

trap cleanup EXIT INT TERM

cleanup() {
  local exit_code=$?
  if [ $exit_code -ne 0 ]; then
    echo ""
    warning "Application stopped with exit code: $exit_code"
  fi
  # Deactivate virtual environment
  if [ -n "${VIRTUAL_ENV:-}" ]; then
    deactivate 2>/dev/null || true
  fi
  exit $exit_code
}