Codakey
Play
← Back to typesense

How to Deploy & Use typesense

Typesense Deployment & Usage Guide

1. Prerequisites

Before installing Typesense, ensure you have:

  • Docker (recommended) or Linux/macOS for native installation
  • Node.js and npm (for using the official JavaScript client or running benchmarks)
  • Git (for cloning the repository)
  • C++ build tools (if building from source):
    • GCC 11+ or Clang 12+
    • CMake 3.21+
    • Make or Ninja
  • OpenSSL development libraries
  • cURL and zlib development libraries

For development and testing:

  • k6 load testing tool (for benchmarking)
  • InfluxDB (for storing benchmark metrics, optional)

2. Installation

Using Docker (Recommended)

# Pull the latest Typesense image
docker pull typesense/typesense:latest

# Or a specific version
docker pull typesense/typesense:26.0

# Run a single node
docker run -p 8108:8108 -v/tmp/typesense-data:/data typesense/typesense:latest \
  --data-dir /data \
  --api-key=your-api-key-here \
  --enable-cors

Using Package Managers

macOS (Homebrew):

brew install typesense/tap/typesense

Linux (DEB/RPM):

# Ubuntu/Debian
wget https://dl.typesense.org/releases/26.0/typesense-server-26.0-amd64.deb
sudo apt install ./typesense-server-26.0-amd64.deb

# RHEL/CentOS/Fedora
wget https://dl.typesense.org/releases/26.0/typesense-server-26.0-1.x86_64.rpm
sudo yum localinstall ./typesense-server-26.0-1.x86_64.rpm

Building from Source

# Clone the repository
git clone https://github.com/typesense/typesense.git
cd typesense

# Install dependencies (Ubuntu/Debian example)
sudo apt-get install -y gcc-11 g++-11 cmake libssl-dev libcurl4-openssl-dev zlib1g-dev

# Build
mkdir -p build && cd build
cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_COMPILER=g++-11 ..
make -j$(nproc)

# The binary will be at ./typesense-server

3. Configuration

Environment Variables

Typesense can be configured via command-line arguments or environment variables:

# Required configuration
export TYPESENSE_API_KEY=xyz
export TYPESENSE_DATA_DIR=/path/to/data

# Network configuration
export TYPESENSE_LISTEN_ADDRESS=0.0.0.0
export TYPESENSE_LISTEN_PORT=8108
export TYPESENSE_PEERING_PORT=8107

# Performance tuning
export TYPESENSE_CACHE_SIZE=512M
export TYPESENSE_LOG_DIR=/var/log/typesense

# For development
export TYPESENSE_ENABLE_CORS=true

API Key Setup

Generate a secure API key for your application:

# Using Docker
docker run typesense/typesense:latest --api-key=your-secure-api-key-here

# Using the binary
./typesense-server --api-key=your-secure-api-key-here

Configuration File

Create a config file (e.g., typesense.ini):

[server]
api-key = your-secure-api-key-here
data-dir = /data/typesense
listen-address = 0.0.0.0
listen-port = 8108
enable-cors = true
log-dir = /var/log/typesense

[cluster]
peering-port = 8107

Run with config file:

./typesense-server --config=typesense.ini

4. Build & Run

Development Mode

# Clone and setup
git clone https://github.com/typesense/typesense.git
cd typesense

# Build in debug mode
mkdir -p build-debug && cd build-debug
cmake -DCMAKE_BUILD_TYPE=Debug ..
make -j$(nproc)

# Run with verbose logging
./typesense-server --api-key=dev-key --data-dir=/tmp/typesense-dev --log-dir=/tmp/typesense-logs

Production Mode

# Build with optimizations
mkdir -p build-release && cd build-release
cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_FLAGS="-O3 -march=native" ..
make -j$(nproc)

# Run production server
./typesense-server \
  --api-key=production-key \
  --data-dir=/var/lib/typesense \
  --log-dir=/var/log/typesense \
  --enable-cors=false \
  --cache-size=2G

Using Docker Compose

Create docker-compose.yml:

version: '3.8'
services:
  typesense:
    image: typesense/typesense:26.0
    ports:
      - "8108:8108"
    volumes:
      - ./typesense-data:/data
    command: 
      - "--data-dir=/data"
      - "--api-key=${TYPESENSE_API_KEY}"
      - "--enable-cors"
    environment:
      - TYPESENSE_API_KEY=${TYPESENSE_API_KEY}
    restart: unless-stopped

Run with:

export TYPESENSE_API_KEY=your-key
docker-compose up -d

5. Deployment

Single Node Deployment

Using systemd (Linux):

# Create systemd service file at /etc/systemd/system/typesense.service
[Unit]
Description=Typesense Search Server
After=network.target

[Service]
Type=simple
User=typesense
Group=typesense
ExecStart=/usr/bin/typesense-server \
  --api-key=your-api-key \
  --data-dir=/var/lib/typesense \
  --listen-address=0.0.0.0 \
  --listen-port=8108
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

# Enable and start
sudo systemctl daemon-reload
sudo systemctl enable typesense
sudo systemctl start typesense

Cluster Deployment

Typesense supports clustering for high availability. Deploy 3 or more nodes:

# Node 1
./typesense-server \
  --api-key=cluster-key \
  --data-dir=/data/node1 \
  --listen-port=8108 \
  --peering-port=8107 \
  --nodes=node1.example.com:8107,node2.example.com:8107,node3.example.com:8107

# Node 2
./typesense-server \
  --api-key=cluster-key \
  --data-dir=/data/node2 \
  --listen-port=8208 \
  --peering-port=8207 \
  --nodes=node1.example.com:8107,node2.example.com:8207,node3.example.com:8307

# Node 3 (similar pattern)

Cloud Deployment Options

  1. Typesense Cloud (Managed): https://cloud.typesense.org
  2. AWS EC2: Use AMI or deploy via Docker on t3.medium or larger instances
  3. Google Cloud Run: Containerized deployment with auto-scaling
  4. Kubernetes: Use the official Helm chart or deploy as StatefulSet
  5. DigitalOcean: Docker on Droplets or managed Kubernetes

Kubernetes Example:

apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: typesense
spec:
  serviceName: typesense
  replicas: 3
  selector:
    matchLabels:
      app: typesense
  template:
    metadata:
      labels:
        app: typesense
    spec:
      containers:
      - name: typesense
        image: typesense/typesense:26.0
        ports:
        - containerPort: 8108
          name: http
        - containerPort: 8107
          name: peering
        env:
        - name: TYPESENSE_API_KEY
          valueFrom:
            secretKeyRef:
              name: typesense-secrets
              key: api-key
        volumeMounts:
        - name: data
          mountPath: /data
        args:
        - "--data-dir=/data"
        - "--enable-cors"

6. Troubleshooting

Common Issues

1. Port Already in Use

# Check what's using port 8108
sudo lsof -i :8108
sudo netstat -tulpn | grep :8108

# Kill the process or change Typesense port
./typesense-server --listen-port=8208

2. Permission Denied on Data Directory

# Fix permissions
sudo mkdir -p /var/lib/typesense
sudo chown -R $(whoami):$(whoami) /var/lib/typesense

# Or run with appropriate user
sudo useradd -r -s /bin/false typesense
sudo chown -R typesense:typesense /var/lib/typesense

3. Memory Issues

# Adjust cache size based on available RAM
./typesense-server --cache-size=1G  # For 4GB RAM
./typesense-server --cache-size=4G  # For 16GB RAM

# Monitor memory usage
docker stats typesense-container
top -p $(pgrep typesense-server)

4. API Connection Errors

// Test connection
const client = new Typesense.Client({
  nodes: [{
    host: 'localhost',
    port: '8108',
    protocol: 'http'
  }],
  apiKey: 'your-api-key',
  connectionTimeoutSeconds: 5
});

// Check health
client.health.retrieve().then(health => {
  console.log('Typesense is healthy:', health.ok);
});

5. Slow Search Performance

  • Check disk I/O: iostat -x 1
  • Increase cache size: --cache-size=2G
  • Optimize schema fields (avoid too many optional fields)
  • Use appropriate field types (string, int32, float, bool, string[])
  • Implement pagination with page and per_page parameters

6. Building from Source Fails

# Ensure correct compiler versions
g++ --version  # Should be 11+
cmake --version  # Should be 3.21+

# Clean build directory and retry
rm -rf build && mkdir build && cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
make -j$(nproc)

# If OpenSSL issues occur
sudo apt-get install libssl-dev  # Ubuntu/Debian
sudo yum install openssl-devel   # RHEL/CentOS

7. Docker Container Exits Immediately

# Check logs
docker logs typesense-container

# Common causes:
# - Missing API key
# - Invalid data directory permissions
# - Port conflicts

# Run with interactive mode to see errors
docker run -it --rm typesense/typesense:latest \
  --api-key=test \
  --data-dir=/data

Logging and Monitoring

Enable verbose logging for debugging:

./typesense-server --log-dir=/var/log/typesense --log-slow-requests-time-ms=1000

Check logs:

# Docker
docker logs -f typesense-container

# Systemd
journalctl -u typesense -f

# Direct log files
tail -f /var/log/typesense/typesense.log

Getting Help

For production issues, enable debug mode temporarily:

./typesense-server --api-key=your-key --log-level=debug
← Project overviewView alternatives to typesense →