Typesense installieren: Docker, Bare Metal und Production-Setup

Typesense lässt sich sehr schnell installieren. Für lokale Tests reicht ein einzelner Docker-Befehl. Für Produktion braucht es jedoch mehr: persistente Daten, API-Key-Strategie, Reverse Proxy, HTTPS, Backups, Monitoring und ein klares Sicherheitsmodell.

Dieser Leitfaden zeigt drei Stufen:

• Docker-Quickstart für Entwicklung
• Docker Compose für reproduzierbare Setups
• Bare-Metal- und Production-Setup mit Reverse Proxy und API Keys

Der offizielle Typesense-Installationsleitfaden beschreibt Docker, Linux-Pakete, macOS/Homebrew und Typesense Cloud als Installationswege; standardmäßig startet Typesense auf Port 8108.

Wie installiere ich Typesense am schnellsten?

Der schnellste Weg führt über Docker. Damit starten Sie einen lauffähigen Typesense-Server mit persistentem Volume und API-Key in wenigen Sekunden.

docker run -p 8108:8108 \
-v typesense-data:/data \
typesense/typesense:0.25.2 \
--data-dir /data \
--api-key=xyz-super-secret \
--enable-cors

Danach testen Sie die Erreichbarkeit:

curl http://localhost:8108/health

Erwartete Antwort:

{"ok":true}

Der öffentliche Docker-Hub-Eintrag typesense/typesense wird von Typesense gepflegt und beschreibt Typesense als Suchengine für Instant Search, Auto-Suggest, Facetten- und Vektorsuche.

 

Welche Installations-Optionen bietet Typesense?

Docker

Docker ist der pragmatischste Einstieg.

Geeignet für:

• lokale Entwicklung
• Testsysteme
• kleine Staging-Umgebungen
• Container-basierte Deployments

Vorteile:

• schnell startklar
• leicht reproduzierbar
• einfach zu entfernen
• gut für CI/CD

 

Native Linux-Pakete

Für produktive Linux-Server ohne Container-Stack eignen sich DEB- und RPM-Pakete.

Vorteile:

• systemd-Integration
• Journal-Logging
• Auto-Restart
• klassische Serverwartung

Die offizielle Dokumentation nennt native Linux-Pakete als unterstützten Installationsweg.

 

macOS und Typesense Cloud

Für lokale Experimente unter macOS ist Homebrew praktisch.

Wer gar keine Infrastruktur betreiben möchte, nutzt Typesense Cloud. Die Entscheidung zwischen Cloud und Self-Hosted sollte jedoch nicht nur über Kosten, sondern auch über Betriebskompetenz getroffen werden.

Mehr dazu: /typesense-cloud-vs-self-hosted/

 

Stabiles Docker-Compose-Setup

Für Teams ist Docker Compose meist besser als ein einzelner docker run-Befehl.

services:
typesense:
image: typesense/typesense:0.25.2
restart: unless-stopped
ports:
- "8108:8108"
volumes:
- typesense-data:/data
environment:
TYPESENSE_API_KEY: ${TYPESENSE_API_KEY}
TYPESENSE_DATA_DIR: /data
TYPESENSE_ENABLE_CORS: "true"

volumes:
typesense-data:

Die .env-Datei:

TYPESENSE_API_KEY=xyz-super-secret

Start:

docker compose up -d

Logs prüfen:

docker compose logs -f typesense

Wichtig: Die .env-Datei gehört nicht ins Git-Repository.

 

Typesense Bare Metal auf Linux installieren

Auf produktiven Linux-Servern ohne Container-Layer ist die Paketinstallation eine robuste Option.

 

Debian / Ubuntu

curl -O https://dl.typesense.org/releases/0.25.2/typesense-server-0.25.2-amd64.deb
sudo apt install ./typesense-server-0.25.2-amd64.deb

 

RHEL / AlmaLinux / Rocky Linux

sudo dnf install https://dl.typesense.org/releases/0.25.2/typesense-server-0.25.2-1.x86_64.rpm

Dienst aktivieren:

sudo systemctl enable --now typesense-server
sudo systemctl status typesense-server

Die Typesense-Dokumentation weist darauf hin, dass der API-Key in der Konfigurationsdatei unter /etc/typesense/typesense-server.ini eingesehen oder geändert werden kann.

 

Was steht in der Typesense-Konfiguration?

Die zentrale Konfiguration liegt typischerweise in:

/etc/typesense/typesense-server.ini

Beispiel:

[server]
api-key = xyz-super-secret
data-dir = /var/lib/typesense
api-port = 8108
peering-port = 8107
enable-cors = true
log-dir = /var/log/typesense
log-level = INFO
snapshot-interval-seconds = 3600

Wichtige Parameter:

Parameter	Bedeutung
api-key	Admin- oder Bootstrap-Key
data-dir	Datenverzeichnis
api-port	HTTP-API-Port
peering-port	Cluster-Kommunikation
enable-cors	CORS für Browserzugriffe
snapshot-interval-seconds	Snapshot-Intervall

 

Der API-Port ist standardmäßig 8108. Für Cluster-Kommunikation wird zusätzlich ein Peering-Port genutzt; dieser sollte niemals öffentlich exponiert werden.

 

Reverse Proxy und HTTPS einrichten

Für Production sollte Typesense nicht ungeschützt über HTTP ins Internet gestellt werden.

Die offizielle Production-Dokumentation empfiehlt für produktive Setups HTTPS, Firewall-Regeln und eine saubere Zertifikatskonfiguration.

 

Caddy

Caddy ist für viele Teams der einfachste Weg zu HTTPS.

search.example.com {
reverse_proxy 127.0.0.1:8108
}

Caddy übernimmt:

• HTTPS
• Zertifikatsausstellung
• automatische Erneuerung
• Reverse Proxy

Die Caddy-Dokumentation beschreibt reverse_proxy als Standard-Direktive für Weiterleitung an Upstream-Services.

 

Nginx

server {
listen 443 ssl http2;
server_name search.example.com;

ssl_certificate /etc/letsencrypt/live/search.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/search.example.com/privkey.pem;

location / {
proxy_pass http://127.0.0.1:8108;
proxy_set_header Host $host;
}
}

Caddy ist oft schneller eingerichtet. Nginx passt besser, wenn bereits ein etablierter Nginx-Stack existiert.

 

Warum Scoped API Keys ins Frontend gehören

Der Admin-Key darf nie im Browser landen.

Er erlaubt weitreichenden Zugriff auf Collections und Dokumente. Für Frontends sollten ausschließlich Search-only oder Scoped API Keys verwendet werden.

Typesense unterstützt API Keys mit feingranularen Einschränkungen. Scoped Search Keys erzwingen eingebettete Suchparameter serverseitig; Nutzer können diese Einschränkungen nicht überschreiben.

Beispiel:

import Typesense from "typesense";

const adminClient = new Typesense.Client({
nodes: [{ host: "search.example.com", port: 443, protocol: "https" }],
apiKey: process.env.TYPESENSE_ADMIN_KEY,
});

const scopedKey = adminClient.keys().generateScopedSearchKey(
process.env.TYPESENSE_SEARCH_ONLY_KEY,
{
filter_by: "tenant_id:=acme",
expires_at: Math.floor(Date.now() / 1000) + 3600
}
);

Typische Einsatzfälle:

• Mandantentrennung
• Kundengruppen-Sichtbarkeit
• B2B-Preis- und Sortimentstrennung
• zeitlich begrenzte Suchzugriffe

 

Erste Collection anlegen und Suche testen

Collection erstellen

curl "http://localhost:8108/collections" \
-X POST \
-H "X-TYPESENSE-API-KEY: xyz-super-secret" \
-H "Content-Type: application/json" \
-d '{
"name":"products",
"fields":[
{"name":"title","type":"string"},
{"name":"price","type":"float"}
]
}'

Dokument indexieren

curl "http://localhost:8108/collections/products/documents" \
-X POST \
-H "X-TYPESENSE-API-KEY: xyz-super-secret" \
-H "Content-Type: application/json" \
-d '{
"id":"1",
"title":"Akku-Bohrschrauber 18V",
"price":129.90
}'

Suche ausführen

curl "http://localhost:8108/collections/products/documents/search?q=bohr&query_by=title" \
-H "X-TYPESENSE-API-KEY: xyz-super-secret"

Damit ist die Installation funktional geprüft.

 

Häufige Fallstricke bei der Installation

Port 8108 ist bereits belegt

Prüfen:

ss -tulpn | grep 8108

Häufige Ursache:

• alter Testcontainer
• lokaler Entwicklungsserver
• parallele Typesense-Instanz

 

Volume-Permissions stimmen nicht

Bei Bind-Mounts können Schreibrechte fehlen.

Typische Lösung:

sudo chown -R 1000:1000 ./typesense-data

Zu wenig RAM

Typesense arbeitet stark speicherorientiert.

Faustregel:

• Indexgröße + 50 % Puffer
• kleine Tests: 1-2 GB
• mittlere Shops: 4-8 GB
• größere B2B-Kataloge: 16 GB+

 

Snapshot-Frequenz zu aggressiv

Sehr häufige Snapshots können auf schwachen Disks Latenzspitzen erzeugen.

Für viele Setups ist ein Intervall von 3600 Sekunden ein sinnvoller Startpunkt.

 

Production-Hardening-Checkliste

Vor Go-Live prüfen:

• HTTPS aktiv
• Admin-Key nur serverseitig
• Search-only oder Scoped Keys im Frontend
• Firewall erlaubt nur nötige Ports
• Datenverzeichnis persistent
• Snapshots aktiv
• Restore getestet
• Monitoring aktiv
• API-Key-Rotation geplant
• Logs zentralisiert
• Peering-Port nicht öffentlich

Typesense empfiehlt in Production unter anderem Firewall-Regeln, HTTPS und eine Strategie für API-Key-Rotation.

 

Fazit

Typesense ist schnell installiert. Für lokale Tests reicht Docker. Für Produktion braucht es aber ein sauberes Betriebsmodell.

Der pragmatische Weg:

1. lokal mit Docker starten
2. Staging mit Docker Compose aufsetzen
3. Production mit Reverse Proxy, HTTPS, Scoped Keys und Monitoring betreiben
4. bei höheren Anforderungen Cloud vs. Self-Hosted sauber bewerten

Die Installation ist der einfache Teil. Stabiler Betrieb entsteht durch Backups, Monitoring, API-Key-Strategie und saubere Daten-Pipelines.