Aman Bagrecha’s Personal Website - Repository Context

This is a self-hosted Quarto-based personal website/blog with integrated services.

What This Repository Does

Primary Purpose: Personal website and blog for Aman Bagrecha (geospatial/remote sensing engineer) built with Quarto and hosted at https://amanbagrecha.com

Tech Stack: - Frontend: Quarto (static site generator) - builds to HTML/CSS/JS - Backend Services: - FastAPI (port 8000) - Photo search API with face recognition - Flask (port 8001) - Image mask labeler tool - Umami (port 8002) - Self-hosted privacy-friendly analytics - Web Server: Nginx (reverse proxy + static file serving) - Database: PostgreSQL (for Umami analytics)

Architecture

User → Nginx (443/80)
         ├─→ Static files: /root/work/amanbagrecha.github.io/docs/ (production)
         ├─→ Static files: /root/work/amanbagrecha.github.io/docs-staging/ (staging)
         ├─→ /api/* → FastAPI (localhost:8000) - photo search
         ├─→ /tools/mask-labeler/* → Flask (localhost:8001) - image labeler
         └─→ /umami/* → Umami Analytics (localhost:8002)

Important Build System

CRITICAL: This site uses a three-tier deployment system:

  1. Local Preview - quarto preview - Test locally at localhost:4848
  2. Staging - ./build-staging.sh or quarto render --profile staging
    • Output: docs-staging/
    • URL: https://staging.amanbagrecha.com
    • Drafts visible, orange “STAGING” banner
  3. Production - ./build-production.sh or quarto render --profile production
    • Output: docs/
    • URL: https://amanbagrecha.com
    • Only published content, Umami tracking enabled

Key Files: - _quarto.yml - Base configuration - _quarto-staging.yml - Staging overrides (docs-staging output, drafts visible) - _quarto-production.yml - Production overrides (docs output, Umami tracking) - _umami-tracking.html - Umami analytics script (production only)

Content Types

  • Blog Posts - posts/*/index.qmd or posts/*/index.md
  • Projects - Defined in projects/gallery.yaml + optional detail pages
  • Presentations - presentations/*/index.md
  • Notebooks - Jupyter notebooks in notebooks/*/
  • Tools - Interactive tools (photo search, mask labeler)
  • TIL (Today I Learned) - til/*.md - Short tips

Critical Constraints

❌ NEVER Edit These Directories

  • docs/ - Auto-generated production build
  • docs-staging/ - Auto-generated staging build

These are OUTPUT directories generated by Quarto. Always edit source files (.qmd, .md) instead.

✓ Always Use Build Scripts

  • Use ./build-staging.sh for staging
  • Use ./build-production.sh for production
  • These handle backups and proper configuration

✓ Virtual Environments

  • FastAPI: /root/work/photos-index-search/.venv/
  • Flask: /root/work/amanbagrecha.github.io/tools/brush-segmentation/.venv/
  • Always activate venv before installing packages OR use uv run

Services Management

Check service status:

sudo systemctl status photo-search-api    # FastAPI photo search
sudo systemctl status image-mask-labeler  # Flask image labeler
sudo systemctl status umami               # Umami analytics
sudo systemctl status nginx               # Web server

Restart after code changes:

sudo systemctl restart photo-search-api   # After FastAPI changes
sudo systemctl restart image-mask-labeler # After Flask changes
sudo systemctl restart umami              # After Umami changes
sudo systemctl reload nginx               # After Nginx config changes

Key Directories

/root/work/amanbagrecha.github.io/
├── posts/              # Blog posts (.qmd, .md)
├── projects/           # Project pages + gallery.yaml
├── presentations/      # Presentation content
├── notebooks/          # Jupyter notebooks
├── tools/              # Interactive tools
│   ├── photo-search.qmd          # Photo search page
│   └── brush-segmentation/       # Flask app for mask labeler
├── _quarto*.yml        # Quarto configurations
├── docs/               # ❌ GENERATED - Production output
├── docs-staging/       # ❌ GENERATED - Staging output
├── build-*.sh          # Build helper scripts
└── .claude/            # Claude-specific files

Related repositories: - /root/work/photos-index-search/ - FastAPI photo search backend - /opt/umami/ - Umami analytics installation

Common Tasks

Add New Blog Post

  1. Create posts/my-post/index.qmd with draft: true
  2. Test locally: quarto preview
  3. Deploy to staging: ./build-staging.sh
  4. When ready: Change draft: false and run ./build-production.sh

Update Analytics Setup

See UMAMI.md for complete Umami reference

Environment-Specific Features

Feature Staging Production
Output dir docs-staging/ docs/
Drafts Visible in listings Hidden (unlinked)
Umami tracking Disabled Enabled
Visual indicator Orange banner None
URL staging.amanbagrecha.com amanbagrecha.com

Important Notes

  • Content workflow: Always test on staging before production
  • Backups: Production is auto-backed up before each build (kept last 3)
  • Umami: Tracks production only, daily DB backups at 2 AM
  • SSL: Auto-renewed by certbot for both staging and production
  • Drafts: Use draft: true in frontmatter to work on posts before publishing

Agent Deployment Instructions

When a user asks to “push and deploy to production”:

  1. Commit and push source changes to git first.
  2. Prefer pushing to upstream if that remote exists; otherwise push to origin.
  3. Run ./build-production.sh from repo root to deploy prod.
  4. If docs/ changes after render (tracked in this repo), commit and push those generated files.
  5. Never manually edit files under docs/ or docs-staging/; only update by Quarto render.

File Permissions

Nginx needs execute permission on directories to serve static files:

sudo chmod +x /root /root/work /root/work/amanbagrecha.github.io
sudo chmod -R +r /root/work/amanbagrecha.github.io/docs

Quick Reference

Build commands: - quarto preview - Local dev server - ./build-staging.sh - Build staging - ./build-production.sh - Build production (with backup)

Logs: - FastAPI: sudo journalctl -u photo-search-api -f - Flask: sudo journalctl -u image-mask-labeler -f - Umami: sudo journalctl -u umami -f - Nginx: sudo tail -f /var/log/nginx/error.log

Repository Type: Personal website/blog Primary Tech: Quarto, FastAPI, Flask, Umami, Nginx Deployment: Self-hosted VPS with staging/production environments Last Updated: January 2026