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:

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:

--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:

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:

// 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):

# 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

--maxmemory 512mb
--maxmemory-policy allkeys-lru

2. Persistence

--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
• Coolify Documentation
• ioredis Documentation

---

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