APSCHEDULER_SETUP.md

APScheduler Scheduling Setup Guide

This guide explains how to set up and use the APScheduler scheduling system with your Lin application.

Overview

The updated start_app.py now automatically starts the Flask application with APScheduler integrated. This ensures that your scheduled tasks will execute properly without requiring external dependencies like Redis.

Prerequisites

1. Python Dependencies

Install the required packages:

pip install -r backend/requirements.txt

Starting the Application

Using start_app.py (Recommended)

python start_app.py

This will:

1. Start the Flask application with APScheduler integrated
2. APScheduler will automatically load schedules from the database every 5 minutes
3. Schedules will be executed according to their defined times

Configuration

Environment Variables

Make sure these are set in your .env file:

# Supabase configuration
SUPABASE_URL="your_supabase_url"
SUPABASE_KEY="your_supabase_key"

# Scheduler configuration
SCHEDULER_ENABLED=True

APScheduler Configuration

The scheduler configuration is in backend/scheduler/apscheduler_service.py:

# APScheduler will run every 5 minutes as a backup
scheduler.add_job(
    func=self.load_schedules,
    trigger=CronTrigger(minute='*/5'),  # Every 5 minutes
    id='load_schedules',
    name='Load schedules from database',
    replace_existing=True
)

How Scheduling Works

1. Schedule Loading

• Immediate Updates: When you create or delete a schedule via the API, APScheduler is updated immediately
• Periodic Updates: APScheduler also runs every 5 minutes as a backup
• Fetches schedules from Supabase database
• Creates individual periodic tasks for each schedule

2. Task Execution

• Content Generation: Runs 5 minutes before scheduled time
• Post Publishing: Runs at the scheduled time

3. Database Integration

• Uses Supabase for schedule storage
• Automatically creates tasks based on schedule data
• Handles social network authentication

Monitoring and Debugging

Checking Scheduler Status

The scheduler runs in the same process as the Flask application, so you can check the console output for logs.

Viewing Logs

• Flask Application: Check console output
• Scheduler: Look for scheduler process logs in the same console

Common Issues

1. Tasks Not Executing

• Check if the Flask application is running
• Verify schedule data in the database
• Check the console logs for any errors

2. Schedule Not Loading

• Check Supabase database connection
• Verify schedule data in database
• Check task registration in APScheduler

Testing the Scheduling System

Manual Testing

# Test schedule loading
from backend.scheduler.apscheduler_service import APSchedulerService
scheduler = APSchedulerService()
result = scheduler.load_schedules()
print(result)

API Testing (Recommended)

1. Create a schedule via the API:

   curl -X POST http://localhost:5000/api/schedules/ \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer YOUR_JWT_TOKEN" \
     -d '{
       "social_network": "1",
       "schedule_time": "09:00",
       "days": ["Monday", "Wednesday", "Friday"]
     }'
   

2. Check the response: You should see a message indicating the scheduler was updated immediately

3. Verify in Logs: Check if the individual tasks were created in the console logs

Database Testing

1. Add a schedule directly in the Supabase database
2. Wait 5 minutes for the loader task to run (or trigger via API)
3. Check if individual tasks were created
4. Verify task execution times

Production Deployment

Using Docker (Recommended for Hugging Face Spaces)

# Build the Docker image
docker build -t lin-app .

# Run the container
docker run -p 7860:7860 lin-app

# For Hugging Face Spaces deployment:
# 1. Update your Dockerfile (already done above)
# 2. Push to Hugging Face Spaces
# 3. The container will automatically start your app with APScheduler

Using Docker Compose (Not Required)

Since APScheduler doesn't require external dependencies like Redis, you don't need Docker Compose for the scheduler.

Troubleshooting Checklist

1. ✅ All Python dependencies are installed
2. ✅ Environment variables are set correctly
3. ✅ Supabase database connection works
4. ✅ Schedule data exists in database
5. ✅ Flask application is running
6. ✅ Scheduler is properly initialized

Support

If you encounter issues:

1. Check this guide first
2. Review the logs for error messages
3. Verify all prerequisites are met
4. Test components individually

For additional help, refer to the APScheduler documentation at: https://apscheduler.readthedocs.io/