media-downloader/docs/INSTALL.md

Media Downloader Installation Guide

Quick Install

# 1. Run setup to create configuration
python3 setup.py

# 2. Edit configuration
nano config/settings.json

# 3. Install to /opt
sudo ./scripts/install.sh

Prerequisites

• Python 3.7 or higher
• sudo access for installation to /opt
• Instagram session file (optional, for private accounts)

Installation Steps

1. Prepare Configuration

Run the setup script to create a default configuration:

python3 setup.py

This will:

• Create a default config.json file
• Create required directories
• Interactively configure usernames

2. Edit Configuration

Edit config/settings.json to set your paths and preferences:

nano config/settings.json

Key settings to configure:

• instagram: Instagram session-based downloads (requires login)
• fastdl: FastDL anonymous Instagram downloads
• imginn: ImgInn anonymous Instagram downloads (posts/stories/tagged)
• toolzu: Toolzu Instagram downloads
• snapchat: Snapchat story downloads
• tiktok.accounts: List of TikTok accounts to download
• forums.configs: Forum thread monitoring and downloads
• *.destination_path: Where to save downloaded media
• immich: API settings if using Immich integration
• pushover: Push notification settings

3. Add Instagram Session (Optional)

For private Instagram accounts, you need a session file:

# Place your session file in the home directory
cp your-session-file ~/.instaloader_sessions/session-username

4. Install to /opt

Run the installer with sudo:

sudo ./scripts/install.sh

The installer will:

• Copy files to /opt/media-downloader
• Install Python dependencies
• Create systemd service and timer
• Set up command-line wrapper
• Configure permissions

Post-Installation

Manual Run

media-downloader

Service Management

# Check status
sudo systemctl status media-downloader

# Start/stop service
sudo systemctl start media-downloader
sudo systemctl stop media-downloader

# Enable/disable timer (runs every 6 hours)
sudo systemctl enable media-downloader.timer
sudo systemctl start media-downloader.timer

View Logs

# Service logs
sudo journalctl -u media-downloader -f

# Application logs
tail -f /opt/media-downloader/logs/*.log

Configuration

The main configuration file is located at:

/opt/media-downloader/config/settings.json

Edit with:

sudo nano /opt/media-downloader/config/settings.json
sudo systemctl restart media-downloader

Directory Structure

/opt/media-downloader/
├── config/
│   └── settings.json     # Main configuration
├── database/
│   ├── media_downloader.db    # Main database
│   └── scheduler_state.db     # Scheduler state
├── media-downloader.py   # Main script
├── db                    # Database CLI wrapper
├── modules/              # Download modules
├── wrappers/             # Subprocess wrappers
├── utilities/            # Utility scripts
│   └── db_manager.py     # Database management CLI
├── logs/                 # Log files
├── temp/                 # Temporary downloads
├── cookies/              # Forum cookies
└── sessions/             # Instagram sessions

Uninstallation

To remove the installation:

sudo /opt/media-downloader/scripts/uninstall.sh

This will:

• Stop and remove systemd services
• Backup configuration and sessions
• Remove installation directory
• Keep downloaded media files

Database Management

The application includes a database management CLI for managing downloaded media records:

# Using the wrapper script
cd /opt/media-downloader
./db stats                          # Show database statistics
./db list --limit 20                # List recent 20 downloads
./db list --username evalongoria    # List downloads by username
./db list --platform instagram      # List downloads by platform
./db delete MEDIA_ID                # Delete post by media ID
./db delete MEDIA_ID1 MEDIA_ID2     # Delete multiple posts
./db delete-user USERNAME           # Delete all posts by username
./db delete-today-except USERNAME   # Delete today's posts except from user
./db clear-old --days 180           # Clear downloads older than 180 days

# Or using the main CLI
media-downloader --db stats
media-downloader --db list --limit 10
media-downloader --db delete MEDIA_ID

Troubleshooting

Permission Issues

Ensure the service user has access to destination directories:

sudo chown -R $USER:$USER /path/to/media/directory

Instagram Session Issues

If Instagram downloads fail:

1. Check session validity:

media-downloader --check-session

2. Update session file:

cp new-session-file ~/.instaloader_sessions/session-username

Database Issues

Reset the database if needed:

sudo rm /opt/media-downloader/database/media_downloader.db
sudo systemctl restart media-downloader

Or use the built-in reset command:

media-downloader --reset-db

Security Notes

• Session files contain sensitive data - keep them secure
• Configuration may contain API keys - restrict access
• Run service as non-root user (handled by installer)
• Review downloaded content before sharing

Support

For issues or questions:

• Check logs in /opt/media-downloader/logs/
• Review configuration in config/settings.json
• Ensure all paths exist and are writable
• Use ./db stats to check database status
• Check scheduler status with media-downloader --scheduler-status