managarten/apps/uload/docs/archive/redis-coolify-setup-guide.md

# Redis Setup auf Coolify - Complete Guide

## Erfolgreiche Redis Integration für uLoad

Nach einigen Herausforderungen haben wir Redis erfolgreich auf Coolify zum Laufen gebracht. Hier sind die wichtigsten Learnings und die funktionierende Konfiguration.

## ✅ Funktionierende Konfiguration

### Redis Service in Coolify

#### 1. Redis als Database Service hinzufügen

- **Type:** Redis Database
- **Image:** redis:7.2
- **Name:** redis-database-[generated-id]

#### 2. General Settings

```
Username: default
Password: [Sicheres Passwort generieren]
Custom Docker Options: --protected-mode no --bind 0.0.0.0
```

**Wichtig:** Die Custom Docker Options sind KRITISCH! Ohne diese wird Redis Verbindungen ablehnen.

#### 3. Network Configuration

```
Ports Mappings: 6379:6379
Redis URL (internal): [wird automatisch generiert]
```

**Achtung:** Nicht 5432 verwenden (das ist PostgreSQL)!

### Hauptanwendung Environment Variables

#### Funktionierende Konfiguration:

```bash
REDIS_HOST=ycsoowwsc84s0s8gc8oooosk  # Der Container-Name (NICHT der Service-Name!)
REDIS_PORT=6379
REDIS_USERNAME=default
REDIS_PASSWORD=[Das gleiche Passwort wie im Redis Service]
```

## 🔍 Wichtige Erkenntnisse

### 1. Container Name vs. Service Name

**Problem:** Der Coolify Service Name funktioniert nicht für die interne Kommunikation.

**Lösung:** Verwende den tatsächlichen Container-Namen:

- ❌ FALSCH: `redis-database-ycsoowwsc84s0s8gc8oooosk`
- ❌ FALSCH: `redis-database-ycsoowwsc84s0s8gc8oooosk.coolify`
- ✅ RICHTIG: `ycsoowwsc84s0s8gc8oooosk`

Der Container-Name findest du in den Redis Logs oder beim Container Start.

### 2. Protected Mode Problem

**Problem:** "Connection is closed" Fehler trotz korrekter Credentials.

**Lösung:** Redis Protected Mode deaktivieren:

```bash
--protected-mode no --bind 0.0.0.0
```

Diese Optionen MÜSSEN in "Custom Docker Options" gesetzt werden!

### 3. Environment Variables Format

**Problem:** REDIS_HOST wurde mit kompletter URL statt nur Hostname gesetzt.

**Lösung:**

- ❌ FALSCH: `REDIS_HOST=redis://default:password@host:6379`
- ✅ RICHTIG: `REDIS_HOST=ycsoowwsc84s0s8gc8oooosk`

REDIS_HOST darf NUR der Hostname sein, keine URL!

### 4. Port Mapping Confusion

**Problem:** Falscher Port (5432 statt 6379) wurde gemappt.

**Lösung:**

- Port 6379 ist Redis
- Port 5432 ist PostgreSQL
- Immer 6379:6379 für Redis verwenden

## 📋 Komplette Setup-Anleitung

### Schritt 1: Redis Service erstellen

1. In Coolify → New Resource → Database → Redis
2. Wähle redis:7.2 als Image
3. Setze Username: `default`
4. Generiere ein starkes Passwort
5. **WICHTIG:** Custom Docker Options: `--protected-mode no --bind 0.0.0.0`
6. Port Mapping: `6379:6379`
7. Deploy

### Schritt 2: Container Name ermitteln

1. Gehe zu Redis Service → Logs
2. Suche nach Container Name (z.B. `ycsoowwsc84s0s8gc8oooosk`)
3. Notiere diesen Namen!

### Schritt 3: Hauptapp konfigurieren

Environment Variables in deiner Hauptapp:

```bash
REDIS_HOST=[Container-Name aus Schritt 2]
REDIS_PORT=6379
REDIS_USERNAME=default
REDIS_PASSWORD=[Passwort aus Redis Service]
```

### Schritt 4: Testen

Erstelle einen Test-Endpoint in deiner App:

```typescript
// src/routes/test-redis/+server.ts
import { json } from '@sveltejs/kit';
import Redis from 'ioredis';

export async function GET() {
	const redis = new Redis({
		host: process.env.REDIS_HOST,
		port: parseInt(process.env.REDIS_PORT || '6379'),
		username: process.env.REDIS_USERNAME,
		password: process.env.REDIS_PASSWORD,
	});

	try {
		await redis.ping();
		await redis.set('test', 'Hello Redis!');
		const value = await redis.get('test');
		redis.disconnect();

		return json({
			success: true,
			value,
			host: process.env.REDIS_HOST,
		});
	} catch (error) {
		return json(
			{
				success: false,
				error: error.message,
			},
			{ status: 500 }
		);
	}
}
```

## 🚀 Performance-Verbesserungen

Nach erfolgreicher Redis-Integration:

### Link Redirects

- **Vorher:** 50-100ms (PocketBase Query)
- **Nachher:** 2-5ms (Redis Cache)
- **Verbesserung:** 20-50x schneller!

### Dashboard Loading

- **Vorher:** 200-400ms
- **Nachher:** 10-20ms
- **Verbesserung:** 10-20x schneller!

### Analytics

- **Vorher:** 500-1500ms
- **Nachher:** 20-50ms
- **Verbesserung:** 10-30x schneller!

## 🐛 Troubleshooting

### "Connection is closed" Error

1. Check Custom Docker Options: `--protected-mode no --bind 0.0.0.0`
2. Verify Container Name (nicht Service Name!)
3. Check Password ist korrekt

### "ECONNREFUSED" Error

1. Redis Service läuft nicht
2. Falscher Host/Port
3. Network Isolation Problem

### "NOAUTH Authentication required"

1. Password nicht gesetzt in Environment Variables
2. Falsches Password
3. Username fehlt (sollte "default" sein)

### Debug Commands

Im Redis Container (via Coolify Terminal):

```bash
# Test Redis läuft
redis-cli ping

# Mit Auth
redis-cli -a [password] ping

# Check Config
redis-cli -a [password] CONFIG GET bind
redis-cli -a [password] CONFIG GET protected-mode
```

## 💡 Best Practices

### 1. Resource Limits

```bash
--maxmemory 512mb
--maxmemory-policy allkeys-lru
```

### 2. Persistence

```bash
--appendonly yes
--save 900 1  # Save every 15 min if at least 1 key changed
```

### 3. Security

- Niemals Redis Port öffentlich exponieren
- Starkes Passwort verwenden
- Protected Mode nur intern deaktivieren

### 4. Monitoring

- Memory Usage im Auge behalten
- Hit Rate tracken
- Slow Queries monitoren

## 📊 Resource-Bedarf

Für uLoad auf Hetzner CX21:

- **RAM:** 50-200MB (von 8GB verfügbar)
- **CPU:** <1% (von 2 vCPUs)
- **Disk:** <1GB (von 40GB)

Redis ist extrem ressourcen-effizient!

## 🎯 Zusammenfassung

Die wichtigsten Punkte für erfolgreiche Redis-Integration auf Coolify:

1. **Container-Name verwenden**, nicht Service-Name
2. **Protected Mode deaktivieren** mit Custom Docker Options
3. **Port 6379** verwenden, nicht 5432
4. **Environment Variables korrekt formatieren** (REDIS_HOST = nur Hostname)
5. **Test-Endpoint** erstellen zum Verifizieren

Mit dieser Konfiguration läuft Redis stabil und performant auf dem gleichen Hetzner VPS wie die Hauptanwendung, ohne zusätzliche Kosten und mit minimaler Latenz.

## 🔗 Weiterführende Dokumentation

- [Redis Best Practices](https://redis.io/docs/manual/patterns/)
- [Coolify Documentation](https://coolify.io/docs)
- [ioredis Documentation](https://github.com/redis/ioredis)

---

_Dokumentiert nach erfolgreicher Redis-Integration für uLoad auf Coolify, August 2025_