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
```bash
# Stop the container first
docker-compose down
docker compose down
# Remove all control characters from 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
# Restart container
docker-compose up -d
docker compose up -d
```
#### Method 2: Recreate the file manually
@ -45,7 +45,7 @@ https://mastodon.social/tags/selfhosting.rss?limit=100
EOF
# Restart container
docker-compose restart gts-holmirdas
docker compose restart gts-holmirdas
```
#### 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
```bash
# Stop the container
docker-compose down
docker compose down
# Check current ownership
ls -la ./data
@ -81,11 +81,11 @@ sudo chown -R 1000:1000 ./data
sudo chmod -R 755 ./data
# Restart container
docker-compose up -d
docker compose up -d
```
#### Method 2: Configure container user
Add user specification to your `docker-compose.yml`:
Add user specification to your `compose.yml`:
```yaml
services:
@ -103,7 +103,7 @@ services:
id -u # User 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"
```
@ -155,8 +155,8 @@ curl -v https://your-gts-instance.tld/api/v1/instance
sudo systemctl restart docker
# Recreate container with fresh networking
docker-compose down
docker-compose up -d
docker compose down
docker compose up -d
# Check container network
docker network ls
@ -181,7 +181,7 @@ curl -I https://mastodon.social/tags/test.rss
date
# 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
```bash
# Validate docker-compose.yml syntax
docker-compose config
# Validate compose.yml syntax
docker compose config
# Check for common issues:
# - 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
sudo netstat -tlnp | grep :8080
# Change port in docker-compose.yml if needed
# Change port in compose.yml if needed
ports:
- "8081:8080" # Use different external port
```
@ -310,7 +310,7 @@ MAX_POSTS_PER_RUN=30 # Reduce processing volume
#### Issue: Duplicate Detection Slow
```bash
# 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
# 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)
```bash
# Stop container
docker-compose down
docker compose down
# Clear runtime data only
rm -rf ./data/*
# Restart with clean state
docker-compose up -d
docker compose up -d
```
### Hard Reset (Full Clean)
```bash
# Stop everything
docker-compose down
docker compose down
# Remove all containers and images
docker-compose rm -f
docker compose rm -f
docker rmi $(docker images | grep gts-holmirdas | awk '{print $3}')
# Clean up RSS feeds file
@ -352,15 +352,15 @@ sudo chown -R $(id -u):$(id -g) ./data
chmod -R 755 ./data
# Rebuild and restart
docker-compose build --no-cache
docker-compose up -d
docker compose build --no-cache
docker compose up -d
```
### Nuclear Reset (Start From Scratch)
```bash
# Stop and remove everything
docker-compose down
docker-compose rm -f
docker compose down
docker compose rm -f
# Remove cloned repository
cd ..
@ -375,7 +375,7 @@ cp rss_feeds.example.txt rss_feeds.txt
# Configure and deploy
nano .env
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)
# Validate configuration before deployment
docker-compose config
docker compose config
```
### 2. Regular Maintenance
```bash
# Weekly: Check logs and performance
docker-compose logs --tail=100 gts-holmirdas
docker compose logs --tail=100 gts-holmirdas
# 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
nano rss_feeds.txt
@ -409,7 +409,7 @@ nano rss_feeds.txt
# Monitor resource usage
docker stats --no-stream gts-holmirdas gotosocial
# Set up log rotation in docker-compose.yml
# Set up log rotation in compose.yml
logging:
driver: "json-file"
options:
@ -421,7 +421,7 @@ logging:
```bash
# Regular backups of working configuration
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
# 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
# Restart container
docker-compose restart gts-holmirdas
docker compose restart gts-holmirdas
# Watch detailed logs
docker-compose logs -f gts-holmirdas
docker compose logs -f gts-holmirdas
```
### Container Shell Access
```bash
# Access running container
docker-compose exec gts-holmirdas /bin/bash
docker compose exec gts-holmirdas /bin/bash
# Check internal files
ls -la /app/
@ -477,7 +477,7 @@ print(f'Entry count: {len(feed.entries)}')
### Network Debugging Inside Container
```bash
# Access container shell
docker-compose exec gts-holmirdas /bin/bash
docker compose exec gts-holmirdas /bin/bash
# Test network connectivity
ping -c 3 mastodon.social
@ -494,16 +494,16 @@ pip list | grep -E "(requests|feedparser)"
### Log Analysis
```bash
# 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
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
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
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
# System Information
docker --version
docker-compose --version
docker compose --version
uname -a
df -h # Disk space
# Container Status
docker-compose ps
docker-compose logs --tail=50 gts-holmirdas
docker compose ps
docker compose logs --tail=50 gts-holmirdas
# Configuration (remove sensitive data)
cat docker-compose.yml
cat compose.yml
cat .env | sed 's/GTS_ACCESS_TOKEN=.*/GTS_ACCESS_TOKEN=***HIDDEN***/'
wc -l rss_feeds.txt # Number of RSS feeds
```
@ -589,7 +589,7 @@ If your instance is completely broken:
```bash
# Stop everything immediately
docker-compose down
docker compose down
# Restore from backup (if available)
tar -xzf gts-holmirdas-backup-YYYYMMDD.tar.gz