Maintenance & Cron Jobs

Plugged.in includes automated maintenance tasks to keep your installation running smoothly. These tasks handle cleanup operations, scheduled emails, and database maintenance.

Overview

The platform uses a dual-approach for automated tasks:

In-Process Scheduler

Automatic - Runs within the application✅ No external configuration needed✅ Works in all environments⚠️ Stops when app restarts

External Cron Jobs

Recommended for Production✅ Runs independently of app✅ Better for serverless/cloud⚠️ Requires configuration

Automated Tasks

1. OAuth PKCE State Cleanup

Purpose: Removes expired OAuth PKCE states to prevent database bloat and ensure security. Frequency: Every 10 minutes Methods:

In-Process (Automatic)
External Cron (Recommended)

The cleanup runs automatically when the application starts and continues every 10 minutes.No configuration needed - it just works!

// Automatically initialized in lib/oauth/pkce-cleanup.ts
// Runs every 10 minutes
// Executes on startup

The in-process scheduler skips in test environments to avoid interference with tests.

For production deployments, configure an external cron job to call the API endpoint.Endpoint: POST /api/oauth/cleanup-pkceAuthentication: Requires CRON_SECRET environment variableSchedule: Every 10-15 minutes

curl -X POST https://your-domain.com/api/oauth/cleanup-pkce \
  -H "Authorization: Bearer YOUR_CRON_SECRET"

name: OAuth PKCE Cleanup
on:
  schedule:
    - cron: '*/10 * * * *'  # Every 10 minutes

jobs:
  cleanup:
    runs-on: ubuntu-latest
    steps:
      - name: Trigger cleanup
        run: |
          curl -X POST ${{ secrets.APP_URL }}/api/oauth/cleanup-pkce \
            -H "Authorization: Bearer ${{ secrets.CRON_SECRET }}"

{
  "crons": [{
    "path": "/api/oauth/cleanup-pkce",
    "schedule": "*/10 * * * *"
  }]
}

# Add to crontab (crontab -e)
*/10 * * * * curl -X POST https://your-domain.com/api/oauth/cleanup-pkce \
  -H "Authorization: Bearer YOUR_CRON_SECRET" >> /var/log/pluggedin-cron.log 2>&1

2. Scheduled Email Processing

Purpose: Sends scheduled welcome emails and follow-up messages to new users. Frequency: Every hour Endpoint: POST /api/emails/process-scheduled Requirements:

CLOUD_DEPLOY=true in production
CRON_SECRET for authentication

curl -X POST https://your-domain.com/api/emails/process-scheduled \
  -H "Authorization: Bearer YOUR_CRON_SECRET"

name: Process Scheduled Emails
on:
  schedule:
    - cron: '0 * * * *'  # Every hour

jobs:
  process-emails:
    runs-on: ubuntu-latest
    steps:
      - name: Process emails
        run: |
          curl -X POST ${{ secrets.APP_URL }}/api/emails/process-scheduled \
            -H "Authorization: Bearer ${{ secrets.CRON_SECRET }}"

{
  "crons": [{
    "path": "/api/emails/process-scheduled",
    "schedule": "0 * * * *"
  }]
}

3. OAuth Session Cleanup

Purpose: Removes expired OAuth sessions from legacy mcp-remote servers. Frequency: Every hour (built-in) Method: Automatic in-process only

// Automatically runs in lib/mcp/oauth/cleanup.ts
// No configuration needed

Environment Variables

Required for Cron Jobs

.env

# Production deployment flag
CLOUD_DEPLOY=true

# Secret for authenticating cron job requests
# Generate with: openssl rand -base64 32
CRON_SECRET=your_secure_random_string_here

Security: Never expose your CRON_SECRET in public repositories or client-side code.This secret should be treated with the same care as database passwords.

Monitoring & Logs

Check Cleanup Status

# Only works in development
curl http://localhost:12005/api/oauth/cleanup-pkce

# Requires authentication
curl -X POST https://your-domain.com/api/oauth/cleanup-pkce \
  -H "Authorization: Bearer YOUR_CRON_SECRET"

Response Format

{
  "success": true,
  "deletedCount": 5,
  "message": "Cleaned up 5 expired PKCE states",
  "timestamp": "2025-01-09T12:00:00.000Z"
}

Application Logs

Check your application logs for cleanup activity:

Docker

docker logs pluggedin-app | grep "OAuth Cleanup"

Systemd

journalctl -u pluggedin -f | grep "OAuth Cleanup"

Expected log output:

[OAuth Cleanup] Automatic PKCE state cleanup initialized (every 10 minutes)
[OAuth Cleanup] Deleted 3 expired PKCE states

Troubleshooting

Cleanup Not Running

In-process cleanup not working

Symptoms: No cleanup logs in application outputSolutions:

Verify you’re not in test environment (NODE_ENV !== 'test')
Check application logs for initialization message
Restart the application to trigger startup cleanup
Ensure lib/oauth/pkce-cleanup.ts is being imported somewhere

External cron returning 401

Symptoms: Unauthorized error from APISolutions:

Verify CRON_SECRET is set in environment
Check Authorization header format: Bearer YOUR_SECRET
Ensure secret matches in both .env and cron configuration

External cron not triggering

Symptoms: No API calls in logsSolutions:

Verify cron job configuration (timing, URL)
Check cron service logs (GitHub Actions, Vercel, etc.)
Test endpoint manually with curl
Ensure endpoint is accessible from cron service

Cleanup running but states not deleted

Symptoms: deletedCount: 0 in all responsesSolutions:

Check database connection
Verify PKCE states exist: SELECT * FROM oauth_pkce_states
Check expiration times: States expire after 10 minutes
Review application logs for errors

Best Practices

Production Deployment

Use External Cron

Configure external cron jobs for critical tasks (PKCE cleanup, scheduled emails) to ensure they run even during app restarts or deployments.

Set CRON_SECRET

Generate a strong random secret and configure it in your environment:

openssl rand -base64 32

Monitor Failures

Set up monitoring/alerting for cron job failures:

GitHub Actions: Email notifications
Vercel: Error tracking in dashboard
Custom: Log aggregation (Sentry, LogDNA, etc.)

Keep In-Process as Backup

The in-process scheduler acts as a failsafe if external cron fails. Don’t disable it.

Development Setup

For local development, the automatic in-process scheduler is sufficient:

No cron configuration needed
Cleanup runs automatically on startup
Continues every 10 minutes while app is running
Use GET endpoints for manual testing

Testing Cleanup Manually

# Trigger cleanup manually (GET)
curl http://localhost:12005/api/oauth/cleanup-pkce

# Trigger with authentication (POST)
curl -X POST https://your-domain.com/api/oauth/cleanup-pkce \
  -H "Authorization: Bearer YOUR_CRON_SECRET"

Summary

TL;DR:✅ In-process cleanup works automatically - no config needed✅ For production, add external cron jobs for reliability✅ Set CRON_SECRET to secure your cron endpoints✅ Both methods work together for redundancy

Recommended Production Setup:

Enable CLOUD_DEPLOY=true
Set strong CRON_SECRET
Configure external cron for OAuth cleanup (every 10 min)
Configure external cron for scheduled emails (every hour)
Monitor cron job execution and errors
Keep in-process scheduler as failsafe

Getting Started

Platform Features

PAP Agents

Guides

Tutorials

Security

Deployment

Observability

Testing

Migration Guides

Troubleshooting

Advanced Configuration

Integration Guides

Performance

Maintenance & Cron Jobs

Maintenance & Cron Jobs

Overview

In-Process Scheduler

External Cron Jobs

Automated Tasks

1. OAuth PKCE State Cleanup

2. Scheduled Email Processing

3. OAuth Session Cleanup

Environment Variables

Required for Cron Jobs

Monitoring & Logs

Check Cleanup Status

Response Format

Application Logs

Troubleshooting

Cleanup Not Running

Best Practices

Production Deployment

Development Setup

Testing Cleanup Manually

Summary

​Maintenance & Cron Jobs

​Overview

In-Process Scheduler

External Cron Jobs

​Automated Tasks

​1. OAuth PKCE State Cleanup

​2. Scheduled Email Processing

​3. OAuth Session Cleanup

​Environment Variables

​Required for Cron Jobs

​Monitoring & Logs

​Check Cleanup Status

​Response Format

​Application Logs

​Troubleshooting

​Cleanup Not Running

​Best Practices

​Production Deployment

​Development Setup

​Testing Cleanup Manually

​Summary

Maintenance & Cron Jobs

Overview

Automated Tasks

1. OAuth PKCE State Cleanup

2. Scheduled Email Processing

3. OAuth Session Cleanup

Environment Variables

Required for Cron Jobs

Monitoring & Logs

Check Cleanup Status

Response Format

Application Logs

Troubleshooting

Cleanup Not Running

Best Practices

Production Deployment

Development Setup

Testing Cleanup Manually

Summary