matthias/gts-holmirdas

Fork 0

Table of Contents

Troubleshooting

🚨 Common Issues

RSS Feed URL Control Characters Error

Method 1: Clean the file automatically
Method 2: Recreate the file manually
Method 3: Text editor approach

Permission Denied Error

Method 1: Fix host directory permissions
Method 2: Configure container user
Method 3: Check your user ID
Method 4: Create data directory with correct permissions

Network Connection Issues

Issue: DNS Resolution Problems
Issue: HTTPS Connectivity Problems
Issue: Container Network Problems
Issue: Firewall/Proxy Issues
Issue: SSL Certificate Problems

GoToSocial API Issues

Issue: Invalid Access Token
Issue: Insufficient Permissions
Issue: Rate Limiting

Container Won't Start

Issue: Invalid Docker Compose Configuration
Issue: Environment Variables Not Set
Issue: Port Conflicts

Performance Issues

Issue: Processing Takes Too Long
Issue: High Memory Usage
Issue: Duplicate Detection Slow

🔧 Complete Reset Procedures

Soft Reset (Keep Configuration)
Hard Reset (Full Clean)
Nuclear Reset (Start From Scratch)

🛡️ Prevention Tips

1. Configuration Best Practices
2. Regular Maintenance
3. Monitoring Setup
4. Backup Strategy
5. URL Testing Before Adding

🔍 Advanced Debugging

Enable Debug Mode
Container Shell Access
Network Debugging Inside Container
Log Analysis

📞 Getting Help

Before Reporting Issues
Information to Include
Issue Template

🤝 Community & Contributing

Emergency Recovery

Troubleshooting

Complete troubleshooting guide for common GTS-HolMirDas issues and their solutions.

🚨 Common Issues

RSS Feed URL Control Characters Error

Error Message:

Error fetching RSS feed https://example.org/tags/homelab.rss: URL can't contain control characters

Cause: The RSS feed URLs in rss_feeds.txt contain invisible control characters, often introduced during copy/paste operations from web browsers or text editors.

Solutions:

Method 1: Clean the file automatically

# Stop the container first
docker compose down

# Remove all control characters from rss_feeds.txt
sed -i 's/\r//g; s/[[:cntrl:]]//g' rss_feeds.txt

# Alternative approach using tr
cat rss_feeds.txt | tr -d '\000-\031' > rss_feeds_clean.txt
mv rss_feeds_clean.txt rss_feeds.txt

# Restart container
docker compose up -d

Method 2: Recreate the file manually

# Backup current file
cp rss_feeds.txt rss_feeds.txt.backup

# Create new clean file
cat > rss_feeds.txt << 'EOF'
https://mastodon.social/tags/homelab.rss
https://fosstodon.org/tags/homelab.rss?limit=50
https://mastodon.social/tags/selfhosting.rss?limit=100
EOF

# Restart container
docker compose restart gts-holmirdas

Method 3: Text editor approach

Open rss_feeds.txt in a plain text editor (nano, vim, notepad++)
Manually retype the URLs instead of copy/pasting
Ensure each URL is on its own line with no trailing spaces
Save and restart the container

Permission Denied Error

Error Message:

Could not save processed URLs: [Errno 13] Permission denied: "/app/data/processed_urls.json"

Cause: The Docker container cannot write to the mounted data directory due to incorrect file permissions or user/group ownership.

Solutions:

Method 1: Fix host directory permissions

# Stop the container
docker compose down

# Check current ownership
ls -la ./data

# Fix ownership (adjust user ID if needed)
sudo chown -R 1000:1000 ./data
sudo chmod -R 755 ./data

# Restart container
docker compose up -d

Method 2: Configure container user

Add user specification to your compose.yml:

services:
  gts-holmirdas:
    image: your-image:latest
    user: "1000:1000"  # Match your host user ID
    volumes:
      - ./data:/app/data:rw
    # ... other configurations

Method 3: Check your user ID

# Find your user ID and group ID
id -u    # User ID
id -g    # Group ID

# Use these values in compose.yml user field
# Example: if output is 1001 and 1001, use user: "1001:1001"

Method 4: Create data directory with correct permissions

# Create data directory if it doesn't exist
mkdir -p ./data

# Set correct ownership and permissions
sudo chown -R $(id -u):$(id -g) ./data
chmod -R 755 ./data

Network Connection Issues

Error Messages:

Failed to get instance count: HTTPSConnectionPool(host='gts.teqqy.social', port=443): Max retries exceeded
Network is unreachable
Connection timeout
SSL: CERTIFICATE_VERIFY_FAILED

Causes and Solutions:

Issue: DNS Resolution Problems

# Test DNS resolution
nslookup your-gts-instance.tld
dig your-gts-instance.tld

# If DNS fails, check /etc/resolv.conf or network settings

Issue: HTTPS Connectivity Problems

# Test HTTPS connectivity
curl -I https://your-gts-instance.tld/api/v1/instance

# Test with verbose output for debugging
curl -v https://your-gts-instance.tld/api/v1/instance

Issue: Container Network Problems

# Restart Docker daemon
sudo systemctl restart docker

# Recreate container with fresh networking
docker compose down
docker compose up -d

# Check container network
docker network ls
docker network inspect gts-holmirdas_default

Issue: Firewall/Proxy Issues

# Check if running behind firewall/proxy
# Ensure outbound HTTPS (port 443) is allowed

# Test from host system
curl -I https://mastodon.social/tags/test.rss

# If host works but container doesn't, check Docker networking

Issue: SSL Certificate Problems

# If you see SSL certificate errors
# Check if system clock is correct
date

# Update CA certificates in container
docker compose exec gts-holmirdas apt-get update && apt-get install -y ca-certificates

GoToSocial API Issues

Error Messages:

Unauthorized: Invalid access token
Forbidden: Insufficient permissions  
Rate limit exceeded

Issue: Invalid Access Token

# Verify token in .env file
cat .env | grep GTS_ACCESS_TOKEN

# Test token manually
curl -H "Authorization: Bearer YOUR_TOKEN" \
     https://your-gts-instance.tld/api/v1/accounts/verify_credentials

Solution:

Go to your GoToSocial Settings → Applications
Delete the old application
Create new application with correct scopes: read, read:search, read:statuses
Update .env file with new token
Restart container

Issue: Insufficient Permissions

Solution: Recreate application with all required scopes:

✅ read
✅ read:search
✅ read:statuses

Issue: Rate Limiting

# Increase delay between requests
DELAY_BETWEEN_REQUESTS=3  # Increase from 1-2

# Reduce processing volume temporarily
MAX_POSTS_PER_RUN=20     # Reduce from higher values

Container Won't Start

Error Messages:

Error response from daemon: invalid reference format
Environment variable not set
Port already in use

Issue: Invalid Docker Compose Configuration

# Validate compose.yml syntax
docker compose config

# Check for common issues:
# - Incorrect indentation (use spaces, not tabs)
# - Missing quotes around special characters
# - Invalid environment variable references

Issue: Environment Variables Not Set

# Check .env file exists and has correct format
ls -la .env
cat .env

# Ensure no spaces around equals signs:
# ✅ Correct: GTS_SERVER_URL=https://example.com
# ❌ Wrong:   GTS_SERVER_URL = https://example.com

# Check for required variables
grep -E "(GTS_SERVER_URL|GTS_ACCESS_TOKEN)" .env

Issue: Port Conflicts

# Check if port is already in use
sudo netstat -tlnp | grep :8080

# Change port in compose.yml if needed
ports:
  - "8081:8080"  # Use different external port

Performance Issues

Issue: Processing Takes Too Long

Runtime: 0:25:30  # Over 25 minutes is too slow

Solutions:

# Reduce processing volume
MAX_POSTS_PER_RUN=25     # Reduce from higher values
DELAY_BETWEEN_REQUESTS=2 # Increase from 1

# Reduce RSS feed count temporarily
# Keep only highest-quality feeds

# Check network latency
ping mastodon.social
ping your-gts-instance.tld

Issue: High Memory Usage

# Monitor memory usage
docker stats gts-holmirdas
docker stats gotosocial

# If memory usage is too high:
MAX_POSTS_PER_RUN=30     # Reduce processing volume
# Reduce RSS feeds with high ?limit= parameters

Issue: Duplicate Detection Slow

# Clean processed URLs database (monthly maintenance)
docker compose exec gts-holmirdas rm -f /app/data/processed_urls.json

# This forces fresh state tracking
# Posts will be reprocessed once, then normal operation resumes

🔧 Complete Reset Procedures

Soft Reset (Keep Configuration)

# Stop container
docker compose down

# Clear runtime data only
rm -rf ./data/*

# Restart with clean state
docker compose up -d

Hard Reset (Full Clean)

# Stop everything
docker compose down

# Remove all containers and images
docker compose rm -f
docker rmi $(docker images | grep gts-holmirdas | awk '{print $3}')

# Clean up RSS feeds file
cat rss_feeds.txt | tr -d '\000-\031' > rss_feeds_clean.txt
mv rss_feeds_clean.txt rss_feeds.txt

# Reset data directory
sudo rm -rf ./data
mkdir -p ./data
sudo chown -R $(id -u):$(id -g) ./data
chmod -R 755 ./data

# Rebuild and restart
docker compose build --no-cache
docker compose up -d

Nuclear Reset (Start From Scratch)

# Stop and remove everything
docker compose down
docker compose rm -f

# Remove cloned repository
cd ..
rm -rf gts-holmirdas

# Start fresh installation
git clone https://git.klein.ruhr/matthias/gts-holmirdas
cd gts-holmirdas
cp .env.example .env
cp rss_feeds.example.txt rss_feeds.txt

# Configure and deploy
nano .env
nano rss_feeds.txt
docker compose up -d

🛡️ Prevention Tips

1. Configuration Best Practices

# Always use plain text editors for config files
# Avoid copy/paste from web browsers
# Use consistent line endings (Unix: LF)

# Validate configuration before deployment
docker compose config

2. Regular Maintenance

# Weekly: Check logs and performance
docker compose logs --tail=100 gts-holmirdas

# Monthly: Clean processed URLs
docker compose exec gts-holmirdas rm -f /app/data/processed_urls.json

# Quarterly: Review and update RSS feeds
nano rss_feeds.txt

3. Monitoring Setup

# Monitor resource usage
docker stats --no-stream gts-holmirdas gotosocial

# Set up log rotation in compose.yml
logging:
  driver: "json-file"
  options:
    max-size: "10m"
    max-file: "3"

4. Backup Strategy

# Regular backups of working configuration
tar -czf gts-holmirdas-backup-$(date +%Y%m%d).tar.gz \
    ./data ./rss_feeds.txt ./compose.yml ./.env

# Store backups securely
# Test restore procedure periodically

5. URL Testing Before Adding

# Always test new RSS URLs manually
curl -I "https://example.org/tags/homelab.rss"

# Check for proper RSS format
curl -s "https://example.org/tags/homelab.rss" | head -20

# Validate RSS structure
curl -s "https://example.org/tags/homelab.rss" | grep -E "(rss|feed|entry|item)"

🔍 Advanced Debugging

Enable Debug Mode

# Add to .env file
LOG_LEVEL=DEBUG

# Restart container
docker compose restart gts-holmirdas

# Watch detailed logs
docker compose logs -f gts-holmirdas

Container Shell Access

# Access running container
docker compose exec gts-holmirdas /bin/bash

# Check internal files
ls -la /app/
cat /app/rss_feeds.txt
cat /app/data/processed_urls.json

# Test RSS fetching manually
python3 -c "
import feedparser
feed = feedparser.parse('https://mastodon.social/tags/test.rss')
print(f'Feed title: {feed.feed.title}')
print(f'Entry count: {len(feed.entries)}')
"

Network Debugging Inside Container

# Access container shell
docker compose exec gts-holmirdas /bin/bash

# Test network connectivity
ping -c 3 mastodon.social
nslookup your-gts-instance.tld

# Test RSS feeds
curl -I https://mastodon.social/tags/test.rss
curl -I https://your-gts-instance.tld/api/v1/instance

# Check Python dependencies
pip list | grep -E "(requests|feedparser)"

Log Analysis

# Extract specific error patterns
docker compose logs gts-holmirdas 2>&1 | grep -i error

# Show last run statistics
docker compose logs gts-holmirdas 2>&1 | grep -A 10 "Run Statistics"

# Monitor real-time processing
docker compose logs -f gts-holmirdas | grep -E "(Processing|Error|Statistics)"

# Save full logs for analysis
docker compose logs --no-log-prefix gts-holmirdas > debug.log

📞 Getting Help

Before Reporting Issues

Try the troubleshooting steps above
Check existing issues at the repository
Gather complete information (see below)

Information to Include

When reporting issues, always include:

# System Information
docker --version
docker compose --version
uname -a
df -h  # Disk space

# Container Status
docker compose ps
docker compose logs --tail=50 gts-holmirdas

# Configuration (remove sensitive data)
cat compose.yml
cat .env | sed 's/GTS_ACCESS_TOKEN=.*/GTS_ACCESS_TOKEN=***HIDDEN***/'
wc -l rss_feeds.txt  # Number of RSS feeds

Issue Template

When creating an issue, use this template:

## Problem Description
Brief description of what's not working

## Error Messages

Paste complete error messages here


## System Information
- OS: 
- Docker version: 
- Docker Compose version:
- RAM available:
- Disk space:

## Configuration
- Number of RSS feeds: 
- MAX_POSTS_PER_RUN: 
- DELAY_BETWEEN_REQUESTS:
- GoToSocial version:

## Steps to Reproduce
1. 
2. 
3. 

## Expected vs Actual Behavior
Expected: 
Actual: 

## Additional Context
Any other relevant information

🤝 Community & Contributing

Contributing Guide - Development setup and contribution guidelines (coming soon)
Issues: Report bugs or request features
Contact: @matthias@me.klein.ruhr on the Fediverse

Emergency Recovery

If your instance is completely broken:

# Stop everything immediately
docker compose down

# Restore from backup (if available)
tar -xzf gts-holmirdas-backup-YYYYMMDD.tar.gz

# Or nuclear reset and reconfigure
rm -rf gts-holmirdas
git clone https://git.klein.ruhr/matthias/gts-holmirdas
# Reconfigure from scratch following Installation Guide

Remember: Most issues are configuration-related and can be resolved by carefully following the troubleshooting steps above. Don't hesitate to ask for help if you're stuck!