This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

Installation Guide

Complete setup guide for GTS-HolMirDas deployment and configuration.

Prerequisites

Docker and Docker Compose installed
GoToSocial instance running and accessible
Admin access to create GoToSocial applications
Basic command line knowledge

Installation Methods

Method 1: Docker Compose (Recommended)

This is the easiest and most reliable deployment method.

Step 1: Clone Repository

git clone https://git.klein.ruhr/matthias/gts-holmirdas
cd gts-holmirdas

Step 2: Configuration Files

# Copy configuration templates
cp .env.example .env
cp rss_feeds.example.txt rss_feeds.txt

Step 3: Configure Environment

Edit .env file:

nano .env

Required settings:

# GoToSocial Configuration
GTS_SERVER_URL=https://your-gts-instance.tld
GTS_ACCESS_TOKEN=your_access_token_here

# Processing Configuration  
MAX_POSTS_PER_RUN=25
DELAY_BETWEEN_REQUESTS=1
LOG_LEVEL=INFO

# File Paths (usually don't need to change)
RSS_URLS_FILE=/app/rss_feeds.txt

# Optional: Health Monitoring
HEALTHCHECK_URL=https://hc-ping.com/your-uuid

Step 4: Configure RSS Feeds

Edit rss_feeds.txt:

nano rss_feeds.txt

Example content:

# Tech & Homelab
https://fosstodon.org/tags/homelab.rss?limit=50
https://mastodon.social/tags/selfhosting.rss?limit=50
https://infosec.exchange/tags/security.rss?limit=50

# Development  
https://fosstodon.org/tags/docker.rss?limit=75
https://mastodon.social/tags/opensource.rss?limit=50
https://social.tchncs.de/tags/programming.rss?limit=50

# Add more feeds based on your interests

Step 5: Deploy

# Start the service
docker compose up -d

# Check logs
docker compose logs -f gts-holmirdas

# Check status
docker compose ps

Method 2: Standalone Docker

If you prefer manual Docker commands:

Build Image

docker build -t gts-holmirdas .

Run Container

docker run -d \
  --name gts-holmirdas \
  --env-file .env \
  -v ./data:/app/data \
  -v ./rss_feeds.txt:/app/rss_feeds.txt:ro \
  --restart unless-stopped \
  gts-holmirdas

Monitor

docker logs -f gts-holmirdas

GoToSocial Access Token Setup

Step 1: Create Application

Login to your GoToSocial web interface
Navigate to Settings → Applications
Click Create new application

Step 2: Configure Application

Application name: GTS-HolMirDas
Website: https://git.klein.ruhr/matthias/gts-holmirdas (optional)
Scopes: Select the following:
- ✅ read
- ✅ read:search
- ✅ read:statuses

Step 3: Get Access Token

Click Create application
Copy the Access token from the application details
Add it to your .env file as GTS_ACCESS_TOKEN

Important: Keep this token secure and never share it publicly!

Directory Structure

After installation, your directory should look like:

gts-holmirdas/
├── .env                    # Your configuration
├── .env.example           # Configuration template
├── compose.yml            # Docker Compose config
├── data/                  # Runtime data (auto-created)
│   ├── processed_urls.json
│   └── logs/
├── Dockerfile
├── gts_holmirdas.py      # Main application
├── LICENSE
├── README.md
├── requirements.txt
├── rss_feeds.txt         # Your RSS feeds
└── rss_feeds.example.txt # RSS feeds template

Initial Run and Verification

Check First Run

# Watch logs for first execution
docker compose logs -f gts-holmirdas

Expected output:

📊 GTS-HolMirDas Run Statistics:
   ⏱️  Runtime: 0:02:15
   📄 Total posts processed: 23
   🌐 Current known instances: 156
   ➕ New instances discovered: +12
   📡 RSS feeds processed: 8
   ⚡ Posts per minute: 10.2

Verify Federation

Check your GoToSocial federated timeline
You should see new posts appearing from different instances
Monitor the instance count growth over time

Post-Installation Setup

1. Customize RSS Feeds

Start with a small number of feeds (5-10) and gradually increase:

# Conservative start
https://fosstodon.org/tags/homelab.rss
https://mastodon.social/tags/selfhosting.rss
https://infosec.exchange/tags/privacy.rss

# Add more as you monitor performance

2. Monitor Resource Usage

# Check container resource usage
docker stats gts-holmirdas

# Monitor GoToSocial memory usage
docker stats gotosocial  # or your GTS container name

3. Set Up Log Rotation (Optional)

# Add to docker-compose.yml under gts-holmirdas service
logging:
  driver: "json-file"
  options:
    max-size: "10m"
    max-file: "3"

4. Configure Health Monitoring (Optional)

Sign up at Healthchecks.io (free)
Create a new check with 70-minute interval
Add the ping URL to your .env file as HEALTHCHECK_URL

Updating

Update to Latest Version

# Pull latest changes
git pull origin master

# Pull latest Docker image
docker compose pull

# Restart with new version
docker compose up -d

# Check logs
docker compose logs -f gts-holmirdas

Update Configuration

# Edit configuration
nano .env
nano rss_feeds.txt

# Apply changes
docker compose restart gts-holmirdas

Uninstalling

Complete Removal

# Stop and remove containers
docker compose down

# Remove data (optional - this deletes processed URLs history)
rm -rf ./data

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

Keep Data for Reinstall

# Stop containers but keep data
docker compose down

# Data directory remains for future use
ls -la ./data

Next Steps

After successful installation:

Performance & Scaling - Optimize for your server capacity
Advanced Configuration - Fine-tune settings
Monitoring & Stats - Understand the output
Troubleshooting - Common issues and solutions

Getting Help

If you encounter issues during installation:

Check our Troubleshooting Guide
Review logs: docker compose logs gts-holmirdas
Open an issue with:
- Your docker-compose.yml (remove sensitive data)
- Complete error logs
- System information (docker --version, uname -a)
- Steps to reproduce the problem