Quick Start

Get up and running with HealthArchive in 5 minutes.

What is HealthArchive?

HealthArchive is a web archiving service that preserves Canadian health government sources (Health Canada, PHAC). It crawls, indexes, and makes searchable snapshots of public health information for research and accountability.

Choose Your Path

Pick the guide that matches your role:

👤 I'm an Operator

Goal: Deploy, monitor, and maintain the production system.

Read the Production Runbook for deployment setup
Review Operator Responsibilities for your must-do checklist
Bookmark Incident Response for emergencies

Quick Deploy:

# On the VPS
cd /opt/healtharchive
./scripts/vps-deploy.sh --apply --baseline-mode live

💻 I'm a Developer

Goal: Contribute code, fix bugs, add features.

Clone and setup:

git clone https://github.com/jerdaw/healtharchive.git
cd healtharchive
make venv

Configure environment:
```
cp .env.example .env
source .env
```
Run database migrations:
```
alembic upgrade head
```

Start the API:

uvicorn ha_backend.api:app --reload --port 8001

Run tests:
```
make ci
```

Next: Follow the Architecture Walkthrough tutorial to understand how everything fits together.

🔧 I'm an API Consumer / Researcher

Goal: Search the archive and retrieve historical snapshots.

API Base URL: https://api.healtharchive.ca

Quick Examples:

# Search for content about vaccines
curl "https://api.healtharchive.ca/api/search?q=vaccines&sort=relevance"

# Get archive stats
curl "https://api.healtharchive.ca/api/stats"

# List all sources
curl "https://api.healtharchive.ca/api/sources"

# Get a specific snapshot
curl "https://api.healtharchive.ca/api/snapshot/42"

Interactive API Docs: api.healtharchive.ca (OpenAPI/Swagger UI)

Next: Read the API Consumer Guide for detailed examples and use cases.

Project Repositories

HealthArchive now uses a single app monorepo plus a separate datasets repo:

App monorepo (this repo): backend API, crawler, docs hub, and the in-tree frontend under frontend/
GitHub: jerdaw/healtharchive
Docs: docs.healtharchive.ca
Live Site: healtharchive.ca
Datasets: Versioned data releases
GitHub: jerdaw/healtharchive-datasets

See the Project Overview for detailed navigation.

Common Tasks

Task	Command
Run all checks	`make ci`
Run frontend checks	`make frontend-ci`
Sync generated API contract	`make contract-sync`
Start API server	`uvicorn ha_backend.api:app --reload --port 8001`
Start worker	`healtharchive start-worker --poll-interval 30`
Create a crawl job	`healtharchive create-job --source hc`
Run a job	`healtharchive run-db-job --id 42`
Index WARCs	`healtharchive index-job --id 42`
List jobs	`healtharchive list-jobs`
Serve docs locally	`make docs-serve`

Need Help?

Architecture Deep Dive: Architecture Guide
Local Development: Live Testing
API Reference: API Documentation
Troubleshooting: Check the How-To Guides
Report Issues: GitHub Issues

What's Next?

For Operators

Complete production deployment
Set up monitoring and alerts
Review the Ops Cadence Checklist

For Developers

Complete Your First Contribution tutorial
Read the Architecture Walkthrough
Review Testing Guidelines

For Researchers

Explore the API Documentation
Download datasets from healtharchive-datasets
Read about Data Handling