Update Installation-Guide
parent
d187077171
commit
cdc82390e8
1 changed files with 287 additions and 1 deletions
|
|
@ -1 +1,287 @@
|
|||
Welcome to the Wiki.
|
||||
# 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
|
||||
Loading…
Add table
Add a link
Reference in a new issue