Todd
238
docs/INSTALL.md
Normal file
238
docs/INSTALL.md
Normal file
@@ -0,0 +1,238 @@
|
||||
# Media Downloader Installation Guide
|
||||
|
||||
## Quick Install
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
media-downloader
|
||||
```
|
||||
|
||||
### Service Management
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
sudo chown -R $USER:$USER /path/to/media/directory
|
||||
```
|
||||
|
||||
### Instagram Session Issues
|
||||
|
||||
If Instagram downloads fail:
|
||||
|
||||
1. Check session validity:
|
||||
```bash
|
||||
media-downloader --check-session
|
||||
```
|
||||
|
||||
2. Update session file:
|
||||
```bash
|
||||
cp new-session-file ~/.instaloader_sessions/session-username
|
||||
```
|
||||
|
||||
### Database Issues
|
||||
|
||||
Reset the database if needed:
|
||||
|
||||
```bash
|
||||
sudo rm /opt/media-downloader/database/media_downloader.db
|
||||
sudo systemctl restart media-downloader
|
||||
```
|
||||
|
||||
Or use the built-in reset command:
|
||||
|
||||
```bash
|
||||
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`
|
||||
Reference in New Issue
Block a user