Typesense on VPS: installation, configuration, and maintenance

Typesense on VPS is a high-performance, fault-tolerant, and scalable open-source search platform that can be installed and configured on a Virtual Private Server to provide fast and relevant search capabilities for your applications, databases, or websites, offering full control over infrastructure and data.

In a world where user experience directly depends on search speed and accuracy, choosing the right search engine becomes critically important. Typesense, thanks to its architecture optimized for low latency and high throughput, is an excellent alternative to more complex or resource-intensive solutions like Elasticsearch. Our goal at Valebyte.com is to provide you with a step-by-step guide on deploying Typesense on a server, leveraging the benefits of VPS hosting for maximum performance and flexibility.

This article will detail the process of installing Typesense, configuring it, securing it with a reverse proxy and HTTPS, and covering maintenance aspects such as backups and updates. We will also discuss which VPS configuration will be optimal for your tasks, so you can effectively use Typesense for your project.

What is Typesense and why choose it for VPS?

Typesense is a modern open-source search engine designed to provide instant (real-time) and faceted search with an emphasis on speed, relevance, and ease of use. It is written in C++ and optimized for handling large volumes of data, while offering minimal resource consumption compared to some alternatives. By choosing Typesense self-hosted on a VPS, you gain full control over data, security, and performance, which is especially important for projects with high privacy requirements or specific workloads.

Key features of Typesense that make it attractive for VPS deployment:

• Speed: Designed to provide low-latency search, even with millions of documents.
• Relevance: Built-in algorithms for smart result sorting, typo tolerance, and synonyms.
• Faceted Search: Allows filtering and categorization of results by multiple attributes.
• Scalability: Supports horizontal scaling for distributed workloads.
• Ease of Use: Simple API and minimal configuration requirements.
• Open Source: Full transparency and customization possibilities.

Typesense vs. Alternatives: A Brief Comparison

There are several powerful search engines on the market, each with its own advantages. Typesense is often compared to Elasticsearch and Meilisearch. Here's a brief table to help understand its positioning:

Characteristic	Typesense	Elasticsearch	Meilisearch
Primary Purpose	Instant, faceted search	Full-text search, log analytics, BI	Fast, relevant search
Installation/Management Complexity	Low-Medium	High	Low
Resource Consumption (RAM/CPU)	Low-Medium	High	Low-Medium
Implementation Language	C++	Java	Rust
Scalability	Horizontal (cluster)	Horizontal (cluster)	Vertical, horizontal in future
Typo Tolerance	Yes, built-in	Yes, via plugins/settings	Yes, built-in
Real-world Use Case	E-commerce product search, documentation	Log analytics, monitoring, complex search	Blog search, small catalogs

As the table shows, Typesense occupies a niche between the simplicity of Meilisearch and the power of Elasticsearch, offering an excellent balance for most web applications and services where search speed is critical.

System Requirements for Typesense on VPS

Before proceeding with Typesense installation on your server, it's important to assess the necessary system resources. VPS requirements for Typesense depend on the volume of data you plan to index, the expected load (queries per second - QPS), and the complexity of your queries.

Minimum and Recommended Configurations

For small projects or the development phase, Typesense requires modest resources. However, for a production environment with real load, more powerful VPS will be needed.

Minimum Requirements (for testing or very small projects up to 100,000 documents):

• CPU: 1 vCPU (2.0 GHz+)
• RAM: 1 GB
• Disk: 10 GB NVMe (SSD minimum)
• OS: Ubuntu 20.04+, Debian 11+

Recommended Requirements (for medium projects up to 5-10 million documents, up to 50 QPS):

• CPU: 2 vCPU (2.5 GHz+)
• RAM: 4 GB
• Disk: 50 GB NVMe (for optimal I/O performance)
• OS: Ubuntu 22.04+, Debian 12+

For large projects (over 10 million documents, 100+ QPS):

• CPU: 4+ vCPU
• RAM: 8 GB+ (depends on index size, often requires 2-3x index size)
• Disk: 100 GB+ NVMe (for large data volumes and high read/write speeds)
• OS: Ubuntu 22.04+, Debian 12+

Important Notes:

• RAM: Typesense stores its index in RAM for maximum speed. Therefore, the amount of RAM must be sufficient to accommodate the index and system processes. If your index takes up 2 GB, you will need at least 4 GB of RAM for the system to function normally.
• Disk: NVMe drives significantly outperform regular SSDs in I/O operations, which is critical for indexing and fast Typesense startup.
• CPU: The number of processor cores affects indexing speed and parallel query processing.
• Network: A stable and fast network connection is necessary for interaction between your application and Typesense.

At Valebyte.com, you will find a wide selection of VPS plans that can be configured to meet any of these requirements, ensuring high performance and reliability for your Typesense.

Preparing VPS for Typesense Installation with Docker

For maximum flexibility, isolation, and ease of management, we recommend installing Typesense as a Docker container. This allows for easy deployment, updates, and migration of Typesense between servers. Before proceeding with Typesense installation, you need to prepare your VPS.

System Update and Docker Engine Installation

Connect to your VPS via SSH. First, update the system packages:

sudo apt update && sudo apt upgrade -y

Next, install the necessary dependencies for Docker:

sudo apt install -y apt-transport-https ca-certificates curl software-properties-common

Add the official Docker GPG key:

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

Add the Docker repository to APT sources:

echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

Update the package list and install Docker Engine:

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io

Verify that Docker is installed and running:

sudo systemctl status docker

You should see the status "active (running)".

Installing Docker Compose

Docker Compose significantly simplifies the management of multi-container applications. Let's install it:

sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

Check the Docker Compose version:

docker-compose --version

For convenience working with Docker without sudo, add your user to the docker group:

sudo usermod -aG docker $USER

After executing this command, you may need to restart your SSH session or log out and log back in for the changes to take effect.

Step-by-step Typesense Installation on VPS via Docker Compose

Now that your VPS is ready, let's proceed with Typesense installation. We will use Docker Compose for convenient deployment.

Creating the docker-compose.yml file for Typesense

Create a directory for your Typesense project and navigate into it:

mkdir ~/typesense-data
cd ~/typesense-data

Create the `docker-compose.yml` file:

nano docker-compose.yml

Paste the following content into the file. Don't forget to replace YOUR_TYPESENSE_API_KEY with a long, complex, and unique string — this is your Typesense access key. Also, ensure that port 8108 is not occupied on your server.

version: '3.8'

services:
  typesense:
    image: typesense/typesense:0.25.1 # Use the actual stable version
    container_name: typesense
    restart: always
    ports:
      - "8108:8108" # Port for Typesense API
    volumes:
      - ./data:/data # Persist Typesense data on the host
    environment:
      TYPESENSE_API_KEY: YOUR_TYPESENSE_API_KEY # Absolutely replace this!
      TYPESENSE_DATA_DIR: /data
      TYPESENSE_LOG_DIR: /data/log
      TYPESENSE_MAX_MEMORY_LIMIT_BYTES: 4294967296 # RAM limit in bytes (4GB), adjust to your VPS
      TYPESENSE_PERSISTENT_SNAPSHOT_INTERVAL_SECONDS: 3600 # Snapshot interval
      TYPESENSE_LISTEN_PORT: 8108
      TYPESENSE_ENABLE_CORS: "true" # Enable CORS if your application will access from a different domain
    ulimits:
      nofile:
        soft: 65536
        hard: 65536
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8108/health"]
      interval: 30s
      timeout: 10s
      retries: 5
      start_period: 20s

Configuration Explanations:

• image: typesense/typesense:0.25.1: Specifies the Typesense Docker image and its version. It is recommended to use a specific version, not latest.
• container_name: typesense: Assigns a descriptive name to the container.
• restart: always: Ensures automatic restart of Typesense after failures or VPS reboots.
• ports: - "8108:8108": Maps host port 8108 to container port 8108.
• volumes: - ./data:/data: Mounts the local ./data folder into the container at path /data. This ensures all Typesense data (indexes) are preserved even if the container is recreated.
• TYPESENSE_API_KEY: Critically important parameter! This key will be used for authentication when interacting with the Typesense API. Generate a complex key (e.g., using openssl rand -hex 32).
• TYPESENSE_MAX_MEMORY_LIMIT_BYTES: Limits the amount of RAM Typesense can use. Set a value appropriate for your VPS. For example, 4294967296 bytes = 4 GB.
• TYPESENSE_ENABLE_CORS: "true": If your client application will access Typesense from a different domain, enable CORS. Otherwise, for security, it's better to leave it as "false" or configure it more strictly.
• ulimits: Increases the number of open files, which is important for Typesense performance when dealing with a large number of documents.
• healthcheck: Defines a container health check so Docker can determine when Typesense is ready for use.

Starting Typesense

Save the `docker-compose.yml` file and start Typesense:

docker-compose up -d

The -d command runs the container in the background. To verify that the container is running, execute:

docker-compose ps

You should see the typesense container with a status of Up.

You can check Typesense logs with the command:

docker-compose logs -f typesense

At this stage, Typesense self-hosted is already running on your VPS and accessible via the server's IP address on port 8108.

Configuring Reverse Proxy (Nginx/Caddy) and HTTPS

Direct access to Typesense on port 8108 is not a secure or convenient solution for a production environment. It is recommended to use a reverse proxy server (Nginx or Caddy) for traffic routing, HTTPS encryption, and additional security. This will also allow you to use a domain name instead of an IP address.

Installing Nginx and Certbot

Install Nginx:

sudo apt install -y nginx

Install Certbot for automatic acquisition and renewal of Let's Encrypt SSL certificates:

sudo apt install -y certbot python3-certbot-nginx

Nginx Configuration for Typesense

Create a new configuration file for your domain (e.g., typesense.yourdomain.com):

sudo nano /etc/nginx/sites-available/typesense.conf

Paste the following configuration, replacing typesense.yourdomain.com with your actual domain:

server {
    listen 80;
    server_name typesense.yourdomain.com;

    location / {
        proxy_pass http://localhost:8108;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_buffering off; # Disable buffering for real-time
        proxy_request_buffering off;
        proxy_http_version 1.1;
        proxy_set_header Connection ""; # For HTTP/1.1
    }
}

Create a symbolic link to sites-enabled and check Nginx syntax:

sudo ln -s /etc/nginx/sites-available/typesense.conf /etc/nginx/sites-enabled/
sudo nginx -t

If the syntax is correct, restart Nginx:

sudo systemctl restart nginx

Obtaining an HTTPS Certificate with Certbot

Now, obtain an SSL certificate for your domain using Certbot:

sudo certbot --nginx -d typesense.yourdomain.com

Follow Certbot's instructions. It will automatically configure Nginx to use HTTPS and add a redirect from HTTP to HTTPS. After this, your Typesense will be accessible via https://typesense.yourdomain.com.

Alternative: Caddy for Typesense

Caddy is a modern web server that automatically manages HTTPS certificates, making its setup even simpler than Nginx+Certbot. If you prefer Caddy, first install it:

sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update
sudo apt install -y caddy

Create or edit the file /etc/caddy/Caddyfile:

sudo nano /etc/caddy/Caddyfile

Add the following configuration, replacing typesense.yourdomain.com with your domain:

typesense.yourdomain.com {
    reverse_proxy localhost:8108 {
        # Additional proxy settings if needed, for example:
        # header_up Host {host}
        # header_up X-Real-IP {remote_ip}
        # header_up X-Forwarded-For {remote_ip}
        # header_up X-Forwarded-Proto {scheme}
    }
}

Check Caddy's configuration and restart it:

sudo caddy validate
sudo systemctl restart caddy

Caddy will automatically obtain and configure HTTPS for your domain. This makes installing Caddy on a VPS an excellent choice for many projects.

Typesense Maintenance: Backups and Updates

Regular maintenance is key to stable Typesense operation. This includes creating data backups and timely updates.

Backing up Typesense Data

Since Typesense stores all its data in the /data folder (which we mounted to ./data on the host), backing up comes down to archiving this folder. It's important to perform backups when Typesense is in a stable state or by using its built-in mechanisms.

Method 1: Copying the Mounted Folder

The simplest way is to copy the ~/typesense-data/data folder. However, for data consistency, it's recommended to first create an index "snapshot" via the Typesense API, and then copy it.

Example command to create a snapshot (from outside the container):

curl -X POST "http://localhost:8108/operations/snapshot" \
-H "Content-Type: application/json" \
-H "X-Typesense-API-Key: YOUR_TYPESENSE_API_KEY" \
-d '{"snapshot_path": "/data/snapshots/$(date +%Y%m%d%H%M%S)"}'

Then you can archive the ~/typesense-data/data/snapshots/ folder. Or, if you are not using snapshots, simply archive the entire ~/typesense-data/data folder:

tar -czvf typesense_backup_$(date +%Y%m%d%H%M%S).tar.gz ~/typesense-data/data

Store backups in a secure location, preferably on another server or in cloud storage.

Method 2: Backup from within the Container

You can also use docker exec to create a backup:

docker exec typesense curl -X POST "http://localhost:8108/operations/snapshot" \
-H "Content-Type: application/json" \
-H "X-Typesense-API-Key: YOUR_TYPESENSE_API_KEY" \
-d '{"snapshot_path": "/data/snapshots/$(date +%Y%m%d%H%M%S)"}'
# Then copy the snapshot file from the host

Automate this process using cron jobs for regular backups.

Updating Typesense Docker

Updating Typesense installed via Docker Compose is a simple process:

1. Stop the current container:

   cd ~/typesense-data
   docker-compose down

2. Change the version in `docker-compose.yml`:

   Edit the docker-compose.yml file and change the line image: typesense/typesense:0.25.1 to the new, current version (e.g., 0.26.0).

3. Pull the new image and start the container:

   docker-compose pull typesense
   docker-compose up -d

4. Check the status:

   docker-compose ps

   Ensure that the container is running with the new version.

Before updating, it is always recommended to review the release notes of the new Typesense version, as changes to data structure or configuration may sometimes be required.

Choosing the Optimal VPS Configuration for Typesense under Real Load

Choosing the right VPS plan for Typesense is a balance between performance and cost. Valebyte.com offers various configurations that can meet any needs. The main thing is to correctly assess your future load.

Factors Affecting VPS Choice

When choosing a VPS for Typesense, consider the following key factors:

1. Data Volume: How many documents do you plan to index? What will be the total index size on disk (and in RAM)? Typesense stores the index in memory for speed, so RAM is a critical resource. A rough rule of thumb: for an index of size X GB, you will need 2X-3X GB of RAM.
2. Queries Per Second (QPS): How many search queries should your Typesense handle simultaneously? High QPS requires more CPU and possibly more RAM for caching.
3. Query Complexity: How complex will your search queries be (faceted search, filters, sorting by multiple fields)? Complex queries consume more CPU.
4. Indexing Speed: How often will you add/update documents? The indexing process also requires CPU and disk I/O resources.
5. Geographic Location: Place your VPS closer to your target audience to minimize latency.

Examples of VPS Configurations from Valebyte.com

Here are a few examples of VPS configurations that might suit various Typesense use cases, with approximate cost estimates:

Scenario	CPU	RAM	Disk (NVMe)	Approximate Cost (Valebyte.com)	Description
Development / Small Project	1 vCPU	2 GB	20 GB	From $5/month	Ideal for testing, personal projects, websites with 10-50k documents and low load (up to 10 QPS).
Medium Project / Startup	2 vCPU	4-8 GB	50-100 GB	From $10-20/month	Suitable for e-commerce stores, blogs, documentation with 100k - 5M documents and moderate load (up to 50 QPS). For example, for Docmost or Lemmy.
Large Project / High Load	4-8 vCPU	16-32 GB	200-500 GB	From $40-80/month	For large catalogs, portals with millions of documents (5-50M) and high load (100+ QPS). A Typesense cluster might be required.
Very Large / Enterprise	8+ vCPU	64+ GB	500 GB+	From $100+/month	For corporate solutions, aggregators, search engines with hundreds of millions of documents and very high load, often in a clustered configuration.

Optimization Recommendations:

• Monitoring: Be sure to set up monitoring for your VPS (CPU, RAM, disk I/O) and Typesense itself to promptly react to load growth and scale resources.
• NVMe Disks: Always choose a VPS with NVMe disks for Typesense. This will significantly improve indexing performance and recovery after restarts.
• Memory Limit: Use the TYPESENSE_MAX_MEMORY_LIMIT_BYTES parameter in docker-compose.yml to prevent Typesense from consuming all available RAM, leaving space for the OS and other processes.
• Client-side Caching: Use search query caching on your application side to reduce the load on Typesense.
• Data Schema Optimization: A properly designed Typesense data schema (indexed fields, sortable fields, facets) significantly impacts performance.

Our VPS servers provide a reliable foundation for deploying Typesense, and flexible pricing plans allow you to choose the optimal configuration for your needs, whether it's a small project or a high-load service. For example, NocoDB or Activepieces often use internal search mechanisms that can be significantly improved with Typesense.

Conclusion

Installing Typesense on a VPS via Docker Compose is an effective way to get a powerful and fast search engine under your full control. By following this step-by-step guide, you will be able to deploy Typesense, configure secure access via a reverse proxy with HTTPS, and ensure its stable operation through backups and updates, as well as choose the optimal VPS configuration from Valebyte.com that perfectly matches your project's requirements.