From cdc82390e8f63d3579cdf56dc3b106ad98e97880 Mon Sep 17 00:00:00 2001 From: Matthias Klein Date: Sun, 3 Aug 2025 20:24:06 +0000 Subject: [PATCH] Update Installation-Guide --- Installation-Guide.-.md | 288 +++++++++++++++++++++++++++++++++++++++- 1 file changed, 287 insertions(+), 1 deletion(-) diff --git a/Installation-Guide.-.md b/Installation-Guide.-.md index 5d08b7b..ba4835c 100644 --- a/Installation-Guide.-.md +++ b/Installation-Guide.-.md @@ -1 +1,287 @@ -Welcome to the Wiki. \ No newline at end of file +# 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 +```bash +git clone https://git.klein.ruhr/matthias/gts-holmirdas +cd gts-holmirdas +``` + +#### Step 2: Configuration Files +```bash +# Copy configuration templates +cp .env.example .env +cp rss_feeds.example.txt rss_feeds.txt +``` + +#### Step 3: Configure Environment +Edit `.env` file: +```bash +nano .env +``` + +Required settings: +```bash +# 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`: +```bash +nano rss_feeds.txt +``` + +Example content: +```bash +# 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 +```bash +# 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 +```bash +docker build -t gts-holmirdas . +``` + +#### Run Container +```bash +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 +```bash +docker logs -f gts-holmirdas +``` + +## GoToSocial Access Token Setup + +### Step 1: Create Application +1. Login to your GoToSocial web interface +2. Navigate to **Settings** → **Applications** +3. 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 +1. Click **Create application** +2. Copy the **Access token** from the application details +3. 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 +```bash +# 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 +1. Check your GoToSocial federated timeline +2. You should see new posts appearing from different instances +3. 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: + +```bash +# 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 +```bash +# 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) +```bash +# 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) +1. Sign up at [Healthchecks.io](https://healthchecks.io) (free) +2. Create a new check with 70-minute interval +3. Add the ping URL to your `.env` file as `HEALTHCHECK_URL` + +## Updating + +### Update to Latest Version +```bash +# 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 +```bash +# Edit configuration +nano .env +nano rss_feeds.txt + +# Apply changes +docker compose restart gts-holmirdas +``` + +## Uninstalling + +### Complete Removal +```bash +# 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 +```bash +# Stop containers but keep data +docker compose down + +# Data directory remains for future use +ls -la ./data +``` + +## Next Steps + +After successful installation: + +1. **[Performance & Scaling](Performance-Scaling)** - Optimize for your server capacity +2. **[Advanced Configuration](Advanced-Configuration)** - Fine-tune settings +3. **[Monitoring & Stats](Monitoring-Stats)** - Understand the output +4. **[Troubleshooting](Troubleshooting)** - Common issues and solutions + +## Getting Help + +If you encounter issues during installation: + +1. **Check our [Troubleshooting Guide](Troubleshooting)** +2. **Review logs:** `docker compose logs gts-holmirdas` +3. **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 \ No newline at end of file