voiceCal-ai-v3 / scripts /SETUP_GUIDE.md
pgits's picture
FEAT: Add privacy policy and terms of service for Google OAuth verification
aca490b
|
Raw History Blame Contribute Delete
5.36 kB

OAuth Token Refresh Setup Guide

This guide will help you set up automated daily OAuth token refresh for VoiceCal.ai.

Quick Summary

Problem: Google OAuth tokens in testing mode expire after 24 hours.

Solution: Automatically refresh tokens daily using:

  1. Local Cron Job (runs on your machine)
  2. GitHub Actions (runs in the cloud)

Prerequisites

You've already completed this! βœ…

  • βœ… Manually authenticated via http://localhost:8080/auth/login
  • βœ… Fresh refresh token saved to .env
  • βœ… Tested refresh script successfully

Option 1: Cron Job (Local Machine)

Runs on your Mac daily at noon

Setup

# Run the automated setup script
./scripts/setup_cron.sh

This will:

  • Add a cron job that runs daily at 12:00 PM
  • Log output to logs/cron.log
  • Send email notification if refresh fails

Verify

# List current cron jobs
crontab -l

# Check logs
tail -f logs/cron.log

Manual Test

# Test the cron job command manually
cd /Users/petergits/dev/voiceCal-ai-v3 && python3 scripts/refresh_token_only.py --notify-email pgits.job@gmail.com

Remove

# Edit crontab
crontab -e

# Delete the line containing 'refresh_token_only.py'

Option 2: GitHub Actions (Cloud-based)

Runs in GitHub's cloud daily at noon UTC

Setup

  1. Push the workflow file (already created):

    git add .github/workflows/refresh-oauth-tokens.yml
    git commit -m "Add OAuth token refresh workflow"
    git push
    
  2. Add GitHub Secrets (go to your repository β†’ Settings β†’ Secrets and variables β†’ Actions):

    Required secrets:

    GOOGLE_CLIENT_ID          = (from your .env file)
    GOOGLE_CLIENT_SECRET      = (from your .env file)
    GOOGLE_REFRESH_TOKEN      = (from your .env file)
    HF_TOKEN                  = (your HuggingFace token)
    

    Optional (for email notifications):

    SMTP_HOST                 = smtp.gmail.com
    SMTP_PORT                 = 587
    SMTP_USERNAME             = pgits.job@gmail.com
    SMTP_PASSWORD             = (your Gmail app password)
    NOTIFY_EMAIL              = pgits.job@gmail.com
    
  3. Test the workflow:

    • Go to your repository β†’ Actions tab
    • Click "Refresh OAuth Tokens" workflow
    • Click "Run workflow" β†’ "Run workflow"
    • Watch it run and verify success βœ…

Verify

  • Go to repository β†’ Actions tab
  • Check workflow runs daily at noon UTC
  • View logs for each run
  • Failed runs will upload logs as artifacts

Which Option to Choose?

Use Cron Job if:

  • βœ… Your Mac is always running (or on at noon daily)
  • βœ… You want local control
  • βœ… You don't want to depend on GitHub

Use GitHub Actions if:

  • βœ… You want it to run even when your Mac is off
  • βœ… You prefer cloud-based automation
  • βœ… You want workflow run history in GitHub

Use Both if:

  • βœ… You want redundancy (if one fails, the other succeeds)
  • ⚠️ Tokens refresh every hour, so both running is fine

Troubleshooting

"Token has been expired or revoked"

Cause: Your refresh token is older than 7 days (testing mode limit)

Solution: Re-authenticate manually:

# Start local server
uvicorn app.api.main:app --reload --port 8080

# Visit in browser
http://localhost:8080/auth/login

# Complete OAuth flow
# New refresh token will be saved automatically

"Failed to refresh token: 400 Bad Request"

Cause: Invalid client ID, client secret, or refresh token

Solution: Check .env file has correct values:

grep -E "GOOGLE_CLIENT_ID|GOOGLE_CLIENT_SECRET|GOOGLE_REFRESH_TOKEN" .env

Cron job not running

Check if cron service is running:

# macOS
sudo launchctl list | grep cron

# View cron logs
log show --predicate 'process == "cron"' --last 1h

Verify cron job is installed:

crontab -l

GitHub Actions not running

Check workflow file:

# Validate YAML syntax
cat .github/workflows/refresh-oauth-tokens.yml

Check repository settings:

  • Settings β†’ Actions β†’ General
  • Ensure "Allow all actions" is enabled

Manual Refresh Anytime

# Local refresh
python3 scripts/refresh_token_only.py

# With email notification
python3 scripts/refresh_token_only.py --notify-email your@email.com

# Verbose output for debugging
python3 scripts/refresh_token_only.py --verbose

Monitoring

View Recent Logs

# Latest refresh log
ls -t logs/token_refresh_*.log | head -1 | xargs cat

# Cron job log
tail -f logs/cron.log

Check Token Expiry

grep GOOGLE_TOKEN_EXPIRY .env

Test Refresh Manually

# Run refresh script
python3 scripts/refresh_token_only.py

# Should see:
# βœ… SUCCESS
# Status: βœ… SUCCESS

Production Mode (Future)

When your OAuth app goes to production mode:

  • Refresh tokens don't expire every 7 days
  • You can reduce refresh frequency (weekly instead of daily)
  • Update cron schedule: 0 12 * * 0 (weekly on Sunday)
  • Update GitHub Actions cron: 0 12 * * 0

Questions?

  • Cron not working? Check logs/cron.log
  • GitHub Actions failing? Check Actions tab β†’ Workflow run β†’ Logs
  • Need help? Contact support or file an issue

You're all set! πŸŽ‰

Your OAuth tokens will now refresh automatically every day at noon.