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

Single-profile build (staging was removed in June 2026):

  1. Local Preview - quarto preview - Test locally at localhost:4848
  2. Production - quarto render
    • Output: docs/
    • URL: https://amanbagrecha.com
    • Umami tracking included via include-in-header

Prefer single-file renders for content edits: quarto render events/index.qmd re-renders only that page and reuses the existing CSS bundle. A full quarto render is only needed for site-wide changes (_quarto.yml, custom.scss, navbar, listings that aggregate other pages).

Key Files: - _quarto.yml - The only Quarto configuration - custom.scss - Theme (changing it requires a FULL render: the CSS bundle is content-hashed and every page references the hash) - _umami-tracking.html - Umami analytics script

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

This is an OUTPUT directory generated by Quarto. Always edit source files (.qmd, .md) instead.

✓ Build Commands

  • quarto render <file>.qmd - Single page (default for content edits)
  • quarto render - Full site (only for theme/config changes)

✓ 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. When ready: Change draft: false and run quarto render (full render so listing pages pick it up)

Update Analytics Setup

See UMAMI.md for complete Umami reference

Important Notes

  • Content workflow: Preview locally with quarto preview, then render to production
  • 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. Render: quarto render <changed-file>.qmd for content-only edits, or full quarto render for theme/config/listing changes. Nginx serves docs/ directly.
  4. If docs/ changes after render (tracked in this repo), commit and push those generated files.
  5. Never manually edit files under docs/; 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 - quarto render <file>.qmd - Render one page (fast path) - quarto render - Full production build

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