Cron Jobs & Scheduling

This guide explains how to set up automated exports from Trakt to Letterboxd using cron jobs.

What is Cron?

Cron is a time-based job scheduler in Unix-like operating systems. It allows commands or scripts to be run automatically at specified times.

Current Version (v1.x - Bash Implementation)

The current Bash implementation supports manual scheduling through system cron or Docker cron configurations.

Basic Docker Scheduling

You can set up a basic cron job using Docker and the host system's cron:

Option 1: Host System Cron

1. Create a script to run the Docker container:

#!/bin/bash
# File: /usr/local/bin/trakt-export.sh
cd /path/to/your/project
docker compose run --rm trakt-export ./Export_Trakt_4_Letterboxd.sh normal

2. Make it executable:

chmod +x /usr/local/bin/trakt-export.sh

3. Add to crontab:

crontab -e
# Add line: 0 4 * * * /usr/local/bin/trakt-export.sh

Option 2: Docker with Custom Cron

Create a custom Dockerfile that adds cron:

FROM johandevl/export-trakt-4-letterboxd:latest

# Install cron
RUN apt-get update && apt-get install -y cron

# Add crontab file
COPY crontab /etc/cron.d/trakt-export
RUN chmod 0644 /etc/cron.d/trakt-export
RUN crontab /etc/cron.d/trakt-export

# Start cron
CMD ["cron", "-f"]

Cron Schedule Examples

• Every day at 4:00 AM: 0 4 * * *
• Every Monday at 3:30 AM: 30 3 * * 1
• Every hour: 0 * * * *
• Every Sunday at 11:00 PM: 0 23 * * 0
• First day of each month at 2:00 AM: 0 2 1 * *

Manual Configuration

For the current version, you need to manually configure:

1. Authentication: Ensure your tokens are valid
2. Configuration: Set up your .config.cfg file
3. Output directories: Ensure proper volume mounts
4. Log monitoring: Set up log rotation if needed

Version 2.0 - Enhanced Scheduling (Coming Soon)

The upcoming Go implementation (v2.0) will include built-in scheduling features:

Built-in Cron Support (v2.0)

The v2.0 will feature integrated cron job support with environment variables:

• EXPORT_SCHEDULE: Sets the cron schedule using cron expressions
• EXPORT_MODE: Sets the export mode (normal, initial, or complete)
• EXPORT_TYPE: Sets what to export (all, movies, watchlist, etc.)

Future Docker Configuration (v2.0)

# docker-compose.yml (v2.0)
services:
  trakt-export:
    image: johandevl/export-trakt-4-letterboxd:v2.0
    environment:
      - EXPORT_SCHEDULE=0 4 * * * # Daily at 4 AM
      - EXPORT_MODE=complete
      - EXPORT_TYPE=all
    volumes:
      - ./config:/app/config
      - ./logs:/app/logs
      - ./exports:/app/exports

Enhanced Logging (v2.0)

The v2.0 will include:

• Structured logging with different levels
• Automatic log rotation
• Cron-specific log files
• Progress tracking

Current Workarounds

Until v2.0 is available, here are some workarounds for automation:

Using Docker Compose with Restart Policies

# Current approach with docker-compose.yml
version: "3"
services:
  trakt-export:
    image: johandevl/export-trakt-4-letterboxd:latest
    volumes:
      - ./config:/app/config
      - ./copy:/app/copy
      - ./backup:/app/backup
    # Run once and exit
    restart: "no"
    command: ["./Export_Trakt_4_Letterboxd.sh", "normal"]

Then use a system cron to restart:

# Crontab entry
0 4 * * * cd /path/to/project && docker compose up trakt-export

Using External Schedulers

You can use external tools like:

• cron (Linux/macOS)
• Task Scheduler (Windows)
• systemd timers (Linux)
• GitHub Actions (for cloud-based scheduling)

GitHub Actions Example

# .github/workflows/scheduled-export.yml
name: Scheduled Trakt Export
on:
  schedule:
    - cron: "0 4 * * *" # Daily at 4 AM UTC
  workflow_dispatch:

jobs:
  export:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Run export
        run: |
          # Configure and run export
          docker run --rm \
            -v ${{ github.workspace }}/config:/app/config \
            -v ${{ github.workspace }}/exports:/app/exports \
            johandevl/export-trakt-4-letterboxd:latest \
            ./Export_Trakt_4_Letterboxd.sh normal

Monitoring and Logs

Current Logging (v1.x)

The current version outputs logs to:

• Docker container logs: docker logs <container_name>
• Export directory: Check files in your mounted volumes

View Current Logs

# View container logs
docker logs trakt-export

# View with follow mode
docker logs -f trakt-export

# View recent logs
docker logs --tail 50 trakt-export

Troubleshooting

Common Issues

1. Permissions: Ensure proper file permissions for mounted volumes
2. Authentication: Check that your Trakt.tv tokens are valid
3. Network: Ensure Docker has internet access
4. Configuration: Verify your .config.cfg file is correctly set up

Debugging Tips

# Run interactively for debugging
docker run -it --rm \
  -v $(pwd)/config:/app/config \
  -v $(pwd)/copy:/app/copy \
  johandevl/export-trakt-4-letterboxd:latest \
  /bin/bash

# Manual run with verbose output
./Export_Trakt_4_Letterboxd.sh normal

Migration to v2.0

When v2.0 is released, migration will include:

• Built-in scheduler: No need for external cron setup
• Enhanced configuration: More granular scheduling options
• Better logging: Structured logs with rotation
• Progress tracking: Real-time export progress
• Notification support: Alerts on completion or errors

For the latest updates on v2.0 features, see the Release Plan.

---

Current information applies to v1.x (Bash implementation). Features marked as v2.0 are planned for the upcoming Go implementation.