QUICKSTART.md

🚀 Quick Start Guide

First Time Setup

1. Run the setup script:

   ./setup.sh
   

   This will:

   • Check Python version (3.11+ required)
   • Install uv package manager if needed
   • Install all dependencies
   • Set script permissions

Running the App

Option 1: Shell Script (Recommended)

./run_local.sh

Option 2: Simple Script (Alternative)

If you encounter build issues, use the simpler version:

./run_simple.sh

Option 3: Make Command

make run

Option 4: Direct Command

uv run --no-build-isolation streamlit run app.py

The app will open in your browser at http://localhost:8501

Deploying to GitHub & HuggingFace Spaces

The deploy script now pushes to both GitHub and HuggingFace Spaces automatically.

Option 1: Shell Script (Recommended)

./deploy.sh

Option 2: Make Command

make deploy

The script will:

• Check for uncommitted changes
• Prompt you to commit if needed
• Push to GitHub (origin remote)
• Push to HuggingFace Spaces (hf remote)
• Show links to both deployed versions

Note: If you don't have the HuggingFace remote configured, the script will show you how to add it:

git remote add hf https://huggingface.co/spaces/amithjkamath/template-matching

Troubleshooting

"Build backend error" or hatchling issues

The project is now configured to skip the build step. If you still see build errors:

./run_simple.sh
# or
uv pip install -r requirements.txt
uv run streamlit run app.py

"Module not found" error

uv sync --no-build-isolation
# or
uv pip install -r requirements.txt

Port 8501 already in use

uv run --no-build-isolation streamlit run app.py --server.port 8502

Script permission denied

chmod +x setup.sh run_local.sh run_simple.sh deploy.sh

Available Commands

Run make help to see all available commands:

make help        # Show all commands
make setup       # Initial setup
make install     # Install dependencies
make run         # Run locally
make deploy      # Deploy to GitHub & HuggingFace
make status      # Check repository sync status
make clean       # Clean cache files
make update      # Update dependencies
make info        # Show project info

Checking Sync Status

Before deploying, you can check if your local repository is in sync with GitHub and HuggingFace:

./check_status.sh
# or
make status

This will show:

• Current branch and uncommitted changes
• Sync status with GitHub (origin)
• Sync status with HuggingFace Spaces (hf)
• Recent commits
• Quick action commands

Need Help?

See CONTRIBUTING.md for detailed documentation.