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