matthias/gts-holmirdas
1
0
Fork 0
Code Issues Pull requests Projects Releases 5 Packages Wiki Activity Actions

Update Troubleshooting

Matthias Klein 2025-08-03 21:26:04 +00:00
parent d49f17ead4
commit 50b529b3ad
1 changed files with 41 additions and 41 deletions
Download patch file Download diff file Expand all files Collapse all files

82
Troubleshooting.md

@ -19,7 +19,7 @@ The RSS feed URLs in `rss_feeds.txt` contain invisible control characters, often
#### Method 1: Clean the file automatically #### Method 1: Clean the file automatically
```bash ```bash
# Stop the container first # Stop the container first
docker-compose down docker compose down
# Remove all control characters from rss_feeds.txt # Remove all control characters from rss_feeds.txt
sed -i 's/[[:cntrl:]]//g' rss_feeds.txt sed -i 's/[[:cntrl:]]//g' rss_feeds.txt
@ -29,7 +29,7 @@ cat rss_feeds.txt | tr -d '\000-\031' > rss_feeds_clean.txt
mv rss_feeds_clean.txt rss_feeds.txt mv rss_feeds_clean.txt rss_feeds.txt
# Restart container # Restart container
docker-compose up -d docker compose up -d
``` ```
#### Method 2: Recreate the file manually #### Method 2: Recreate the file manually
@ -45,7 +45,7 @@ https://mastodon.social/tags/selfhosting.rss?limit=100
EOF EOF
# Restart container # Restart container
docker-compose restart gts-holmirdas docker compose restart gts-holmirdas
``` ```
#### Method 3: Text editor approach #### Method 3: Text editor approach
@ -71,7 +71,7 @@ The Docker container cannot write to the mounted data directory due to incorrect
#### Method 1: Fix host directory permissions #### Method 1: Fix host directory permissions
```bash ```bash
# Stop the container # Stop the container
docker-compose down docker compose down
# Check current ownership # Check current ownership
ls -la ./data ls -la ./data
@ -81,11 +81,11 @@ sudo chown -R 1000:1000 ./data
sudo chmod -R 755 ./data sudo chmod -R 755 ./data
# Restart container # Restart container
docker-compose up -d docker compose up -d
``` ```
#### Method 2: Configure container user #### Method 2: Configure container user
Add user specification to your `docker-compose.yml`: Add user specification to your `compose.yml`:
```yaml ```yaml
services: services:
@ -103,7 +103,7 @@ services:
id -u # User ID id -u # User ID
id -g # Group ID id -g # Group ID
# Use these values in docker-compose.yml user field # Use these values in compose.yml user field
# Example: if output is 1001 and 1001, use user: "1001:1001" # Example: if output is 1001 and 1001, use user: "1001:1001"
``` ```
@ -155,8 +155,8 @@ curl -v https://your-gts-instance.tld/api/v1/instance
sudo systemctl restart docker sudo systemctl restart docker
# Recreate container with fresh networking # Recreate container with fresh networking
docker-compose down docker compose down
docker-compose up -d docker compose up -d
# Check container network # Check container network
docker network ls docker network ls
@ -181,7 +181,7 @@ curl -I https://mastodon.social/tags/test.rss
date date
# Update CA certificates in container # Update CA certificates in container
docker-compose exec gts-holmirdas apt-get update && apt-get install -y ca-certificates docker compose exec gts-holmirdas apt-get update && apt-get install -y ca-certificates
``` ```
--- ---
@ -240,8 +240,8 @@ Port already in use
#### Issue: Invalid Docker Compose Configuration #### Issue: Invalid Docker Compose Configuration
```bash ```bash
# Validate docker-compose.yml syntax # Validate compose.yml syntax
docker-compose config docker compose config
# Check for common issues: # Check for common issues:
# - Incorrect indentation (use spaces, not tabs) # - Incorrect indentation (use spaces, not tabs)
@ -268,7 +268,7 @@ grep -E "(GTS_SERVER_URL|GTS_ACCESS_TOKEN)" .env
# Check if port is already in use # Check if port is already in use
sudo netstat -tlnp | grep :8080 sudo netstat -tlnp | grep :8080
# Change port in docker-compose.yml if needed # Change port in compose.yml if needed
ports: ports:
- "8081:8080" # Use different external port - "8081:8080" # Use different external port
``` ```
@ -310,7 +310,7 @@ MAX_POSTS_PER_RUN=30 # Reduce processing volume
#### Issue: Duplicate Detection Slow #### Issue: Duplicate Detection Slow
```bash ```bash
# Clean processed URLs database (monthly maintenance) # Clean processed URLs database (monthly maintenance)
docker-compose exec gts-holmirdas rm -f /app/data/processed_urls.json docker compose exec gts-holmirdas rm -f /app/data/processed_urls.json
# This forces fresh state tracking # This forces fresh state tracking
# Posts will be reprocessed once, then normal operation resumes # Posts will be reprocessed once, then normal operation resumes
@ -323,22 +323,22 @@ docker-compose exec gts-holmirdas rm -f /app/data/processed_urls.json
### Soft Reset (Keep Configuration) ### Soft Reset (Keep Configuration)
```bash ```bash
# Stop container # Stop container
docker-compose down docker compose down
# Clear runtime data only # Clear runtime data only
rm -rf ./data/* rm -rf ./data/*
# Restart with clean state # Restart with clean state
docker-compose up -d docker compose up -d
``` ```
### Hard Reset (Full Clean) ### Hard Reset (Full Clean)
```bash ```bash
# Stop everything # Stop everything
docker-compose down docker compose down
# Remove all containers and images # Remove all containers and images
docker-compose rm -f docker compose rm -f
docker rmi $(docker images | grep gts-holmirdas | awk '{print $3}') docker rmi $(docker images | grep gts-holmirdas | awk '{print $3}')
# Clean up RSS feeds file # Clean up RSS feeds file
@ -352,15 +352,15 @@ sudo chown -R $(id -u):$(id -g) ./data
chmod -R 755 ./data chmod -R 755 ./data
# Rebuild and restart # Rebuild and restart
docker-compose build --no-cache docker compose build --no-cache
docker-compose up -d docker compose up -d
``` ```
### Nuclear Reset (Start From Scratch) ### Nuclear Reset (Start From Scratch)
```bash ```bash
# Stop and remove everything # Stop and remove everything
docker-compose down docker compose down
docker-compose rm -f docker compose rm -f
# Remove cloned repository # Remove cloned repository
cd .. cd ..
@ -375,7 +375,7 @@ cp rss_feeds.example.txt rss_feeds.txt
# Configure and deploy # Configure and deploy
nano .env nano .env
nano rss_feeds.txt nano rss_feeds.txt
docker-compose up -d docker compose up -d
``` ```
--- ---
@ -389,16 +389,16 @@ docker-compose up -d
# Use consistent line endings (Unix: LF) # Use consistent line endings (Unix: LF)
# Validate configuration before deployment # Validate configuration before deployment
docker-compose config docker compose config
``` ```
### 2. Regular Maintenance ### 2. Regular Maintenance
```bash ```bash
# Weekly: Check logs and performance # Weekly: Check logs and performance
docker-compose logs --tail=100 gts-holmirdas docker compose logs --tail=100 gts-holmirdas
# Monthly: Clean processed URLs # Monthly: Clean processed URLs
docker-compose exec gts-holmirdas rm -f /app/data/processed_urls.json docker compose exec gts-holmirdas rm -f /app/data/processed_urls.json
# Quarterly: Review and update RSS feeds # Quarterly: Review and update RSS feeds
nano rss_feeds.txt nano rss_feeds.txt
@ -409,7 +409,7 @@ nano rss_feeds.txt
# Monitor resource usage # Monitor resource usage
docker stats --no-stream gts-holmirdas gotosocial docker stats --no-stream gts-holmirdas gotosocial
# Set up log rotation in docker-compose.yml # Set up log rotation in compose.yml
logging: logging:
driver: "json-file" driver: "json-file"
options: options:
@ -421,7 +421,7 @@ logging:
```bash ```bash
# Regular backups of working configuration # Regular backups of working configuration
tar -czf gts-holmirdas-backup-$(date +%Y%m%d).tar.gz \ tar -czf gts-holmirdas-backup-$(date +%Y%m%d).tar.gz \
./data ./rss_feeds.txt ./docker-compose.yml ./.env ./data ./rss_feeds.txt ./compose.yml ./.env
# Store backups securely # Store backups securely
# Test restore procedure periodically # Test restore procedure periodically
@ -449,16 +449,16 @@ curl -s "https://example.org/tags/homelab.rss" | grep -E "(rss|feed|entry|item)"
LOG_LEVEL=DEBUG LOG_LEVEL=DEBUG
# Restart container # Restart container
docker-compose restart gts-holmirdas docker compose restart gts-holmirdas
# Watch detailed logs # Watch detailed logs
docker-compose logs -f gts-holmirdas docker compose logs -f gts-holmirdas
``` ```
### Container Shell Access ### Container Shell Access
```bash ```bash
# Access running container # Access running container
docker-compose exec gts-holmirdas /bin/bash docker compose exec gts-holmirdas /bin/bash
# Check internal files # Check internal files
ls -la /app/ ls -la /app/
@ -477,7 +477,7 @@ print(f'Entry count: {len(feed.entries)}')
### Network Debugging Inside Container ### Network Debugging Inside Container
```bash ```bash
# Access container shell # Access container shell
docker-compose exec gts-holmirdas /bin/bash docker compose exec gts-holmirdas /bin/bash
# Test network connectivity # Test network connectivity
ping -c 3 mastodon.social ping -c 3 mastodon.social
@ -494,16 +494,16 @@ pip list | grep -E "(requests|feedparser)"
### Log Analysis ### Log Analysis
```bash ```bash
# Extract specific error patterns # Extract specific error patterns
docker-compose logs gts-holmirdas 2>&1 | grep -i error docker compose logs gts-holmirdas 2>&1 | grep -i error
# Show last run statistics # Show last run statistics
docker-compose logs gts-holmirdas 2>&1 | grep -A 10 "Run Statistics" docker compose logs gts-holmirdas 2>&1 | grep -A 10 "Run Statistics"
# Monitor real-time processing # Monitor real-time processing
docker-compose logs -f gts-holmirdas | grep -E "(Processing|Error|Statistics)" docker compose logs -f gts-holmirdas | grep -E "(Processing|Error|Statistics)"
# Save full logs for analysis # Save full logs for analysis
docker-compose logs --no-log-prefix gts-holmirdas > debug.log docker compose logs --no-log-prefix gts-holmirdas > debug.log
``` ```
--- ---
@ -523,16 +523,16 @@ When reporting issues, always include:
```bash ```bash
# System Information # System Information
docker --version docker --version
docker-compose --version docker compose --version
uname -a uname -a
df -h # Disk space df -h # Disk space
# Container Status # Container Status
docker-compose ps docker compose ps
docker-compose logs --tail=50 gts-holmirdas docker compose logs --tail=50 gts-holmirdas
# Configuration (remove sensitive data) # Configuration (remove sensitive data)
cat docker-compose.yml cat compose.yml
cat .env | sed 's/GTS_ACCESS_TOKEN=.*/GTS_ACCESS_TOKEN=***HIDDEN***/' cat .env | sed 's/GTS_ACCESS_TOKEN=.*/GTS_ACCESS_TOKEN=***HIDDEN***/'
wc -l rss_feeds.txt # Number of RSS feeds wc -l rss_feeds.txt # Number of RSS feeds
``` ```
@ -589,7 +589,7 @@ If your instance is completely broken:
```bash ```bash
# Stop everything immediately # Stop everything immediately
docker-compose down docker compose down
# Restore from backup (if available) # Restore from backup (if available)
tar -xzf gts-holmirdas-backup-YYYYMMDD.tar.gz tar -xzf gts-holmirdas-backup-YYYYMMDD.tar.gz