Docker

This comprehensive guide explains how to use Export Trakt 4 Letterboxd with Docker, including the advanced image management system and Docker Compose configurations.

Advantages of Docker

Using Docker offers several advantages:

• Simplified Installation: No need to manually install dependencies
• Environment Isolation: Clean, isolated runtime environment
• Easy Updates: Simple image pulling for updates
• Automated Exports: Built-in cron scheduling support
• Portability: Works across different operating systems
• Image Management: Intelligent Docker image lifecycle management

Prerequisites

• Docker installed on your system
• Docker Compose (recommended)
• A Trakt.tv account and Trakt application (Client ID and Client Secret)

Docker Image Strategy

Available Image Tags

The project implements an intelligent Docker image management system with the following tagging strategy:

Main Branch Images

• latest: Always the latest stable version
• main: Fixed tag for the main branch
• v1.2.3: Semantic version tags (e.g., v2.0.13)

Development Images

• develop: Always the latest development version

Pull Request Images

• PR-123: Test images for specific pull requests before merge

Supported Registries

The project maintains images on two registries for redundancy:

• Docker Hub: johandevl/export-trakt-4-letterboxd
• GitHub Container Registry: ghcr.io/johandevl/export_trakt_4_letterboxd

Automatic Versioning Process

The system automatically manages semantic versioning with the following sequence:

1. PR merged to main → Push to main branch (no immediate Docker build)
2. auto-tag.yml triggers and creates new Git tag (e.g., v2.0.14)
3. Git tag push automatically triggers docker-build.yml
4. Docker image created with tags: latest, main, v2.0.14

Benefits

• Single build per merge (no double builds)
• Exact semantic versioning synchronized with Git tags
• Perfect synchronization between Git and Docker versions
• Optimized process without redundant builds

Automatic Image Cleanup

The system includes intelligent cleanup to prevent registry bloat:

PR Cleanup (triggered on PR closure)

• Automatically deletes PR-{number} images from both registries
• Only triggers when PRs on main or develop are closed

Scheduled Cleanup (daily at 2 AM UTC)

• Automatically cleans obsolete images
• Preserves protected tags:
  • latest, main, develop
  • All semantic versions (v1.2.3)
  • Active PR tags (PR-123)
• Deletes everything else

Docker Compose (Recommended)

Installation with Docker Compose

1. Clone the repository:

   git clone https://github.com/JohanDevl/Export_Trakt_4_Letterboxd.git
   cd Export_Trakt_4_Letterboxd
   

2. Create a .env file (optional) to configure environment variables:

   CRON_SCHEDULE=0 4 * * *
   EXPORT_OPTION=normal
   

3. Start the container:

   docker compose up -d
   

4. Configure Trakt authentication:

   docker compose exec trakt-export ./setup_trakt.sh
   

5. Run the export:

   docker compose exec trakt-export ./export_trakt
   

Available Compose Profiles

The Docker Compose configuration supports multiple execution modes:

Immediate Execution Profiles (--run)

Profile	Command	Purpose
run-watched	--run --export watched --mode normal	Export watched movies only
run-all	--run --export all --mode complete	Export all data (recommended)
run-collection	--run --export collection --mode normal	Export collection only
run-ratings	--run --export ratings --mode complete	Export ratings only
run-watchlist	--run --export watchlist --mode normal	Export watchlist only
run-shows	--run --export shows --mode complete	Export shows only

Scheduled Execution Profiles (--schedule)

Profile	Schedule	Command	Purpose
schedule-6h	Every 6 hours	--schedule "0 */6 * * *" --export all --mode complete	Production scheduler
schedule-daily	Daily at 2:30 AM	--schedule "30 2 * * *" --export all --mode complete	Daily backup
schedule-weekly	Sundays at 3:00 AM	--schedule "0 3 * * 0" --export all --mode complete	Weekly backup
schedule-15min	Every 15 minutes	--schedule "*/15 * * * *" --export watched --mode normal	High-frequency testing
schedule-custom	Configurable	Custom via environment variables	Custom schedule

Usage Examples

# Test configuration with watched movies only
docker compose --profile run-watched up

# Export all data once (recommended)
docker compose --profile run-all up

# Start production scheduler (every 6 hours)
docker compose --profile schedule-6h up -d

# Custom schedule example
SCHEDULE="0 */4 * * *" EXPORT_TYPE="watched" EXPORT_MODE="normal" \
docker compose --profile schedule-custom up -d

docker-compose.yml Structure

The configuration file includes:

services:
  export-trakt-base: &export-trakt-base
    image: johandevl/export-trakt-4-letterboxd:latest
    volumes:
      - ./config:/app/config
      - ./exports:/app/exports
      - ./logs:/app/logs
    environment:
      - TZ=UTC

Direct Docker Usage

You can also use the Docker image directly without Docker Compose:

Using Latest Stable Version

docker run -d \
  --name trakt-export \
  -v $(pwd)/config:/app/config \
  -v $(pwd)/exports:/app/exports \
  -v $(pwd)/logs:/app/logs \
  -e TZ=UTC \
  johandevl/export-trakt-4-letterboxd:latest \
  --run --export all --mode complete

Using Development Version

docker pull johandevl/export-trakt-4-letterboxd:develop
docker run -d \
  --name trakt-export-dev \
  -v $(pwd)/config:/app/config \
  -v $(pwd)/exports:/app/exports \
  -v $(pwd)/logs:/app/logs \
  johandevl/export-trakt-4-letterboxd:develop \
  --run --export watched --mode normal

Testing Pull Request

docker pull johandevl/export-trakt-4-letterboxd:PR-123
docker run --rm \
  -v $(pwd)/config:/app/config \
  -v $(pwd)/exports:/app/exports \
  johandevl/export-trakt-4-letterboxd:PR-123 \
  --run --export watched --mode normal

Using Specific Version

docker pull johandevl/export-trakt-4-letterboxd:v2.0.13
docker run -d \
  --name trakt-export-v2013 \
  -v $(pwd)/config:/app/config \
  -v $(pwd)/exports:/app/exports \
  -v $(pwd)/logs:/app/logs \
  johandevl/export-trakt-4-letterboxd:v2.0.13 \
  --schedule "0 4 * * *" --export all --mode complete

Environment Variables

The following environment variables are available:

• TZ: Timezone for scheduling (default: UTC)
• SCHEDULE: Cron schedule for automated exports
• EXPORT_TYPE: Export type (watched, all, collection, ratings, watchlist, shows)
• EXPORT_MODE: Export mode (normal, complete)

Volume Structure

The following volumes should be mounted in the container:

• ./config:/app/config: Contains the configuration files (config.toml)
• ./exports:/app/exports: Contains the generated CSV files for Letterboxd
• ./logs:/app/logs: Contains application log files

Useful Docker Commands

View Container Logs

# Docker Compose
docker compose logs trakt-export

# Direct Docker
docker logs trakt-export

Run Commands in Container

# Docker Compose
docker compose exec trakt-export bash

# Direct Docker
docker exec -it trakt-export bash

Manually Run Export

# Docker Compose
docker compose exec trakt-export ./export_trakt --run --export all --mode complete

# Direct Docker
docker exec -it trakt-export ./export_trakt --run --export watched --mode normal

Container Management

# Stop container
docker stop trakt-export

# Restart container
docker restart trakt-export

# Remove container
docker rm trakt-export

# Remove image
docker rmi johandevl/export-trakt-4-letterboxd:latest

GitHub Actions Workflows

The project uses automated workflows for Docker image management:

• docker-build.yml: Builds and publishes multi-platform images
• docker-cleanup.yml: Automatically cleans obsolete images
• auto-tag.yml: Creates semantic version tags automatically

Migration from Legacy Configuration

Old Command	New Equivalent
docker compose up	docker compose --profile run-watched up
docker compose --profile complete up	docker compose --profile run-all up
docker compose --profile scheduled up -d	docker compose --profile schedule-6h up -d

Troubleshooting

Common Issues

1. Authentication Problems: Ensure OAuth setup is completed
2. Permission Issues: Check volume mount permissions
3. Network Issues: Verify internet connectivity for Trakt.tv API
4. Schedule Not Running: Check timezone settings and cron syntax

Getting Help

For more information:

• Authentication: See OAuth Authentication guide
• Configuration: See Configuration guide
• Cron Jobs: See Cron Jobs guide
• Troubleshooting: See Troubleshooting guide

Performance Features

The Docker images include enterprise-grade performance optimizations:

• Worker Pool System: Concurrent processing for 10x throughput improvement
• LRU Cache: 70-90% API call reduction through intelligent caching
• Streaming Processing: 80% memory reduction for large datasets
• Circuit Breaker: Resilient API calls with automatic failure recovery

This comprehensive Docker integration provides a production-ready, scalable solution for automated Trakt.tv data exports with intelligent image lifecycle management.