Typesense on Ubuntu 24.04 on Azure User Guide

Overview

Typesense is a fast, open source, typo tolerant search engine built for instant, relevant search. It delivers as you type full text search that tolerates spelling mistakes, and adds semantic and vector search so results can be ranked by meaning as well as keywords, making it a strong backend for site and product search, in application search bars, and retrieval for AI applications. The cloudimg image installs the latest stable Typesense server from the official release at /opt/typesense, run by an unprivileged typesense system account, fronts it with an nginx reverse proxy on TCP 80, persists all data on a dedicated Azure data disk, and generates a unique api key on the first boot of every VM. Backed by 24/7 cloudimg support.

What is included:

• The latest stable Typesense server binary at /opt/typesense, run by an unprivileged typesense account
• nginx reverse proxy on :80 in front of the Typesense server (bound to loopback :8108, REST API)
• A dedicated Azure data disk at /var/lib/typesense holding the on disk store, indexes and documents (data-dir) — separate from the OS disk and re-provisioned with every VM
• Secure by default: a strong per VM api key (TYPESENSE_API_KEY) generated at first boot in a root only file, with no default login to change
• typesense.service + nginx.service as systemd units, enabled and active
• 24/7 cloudimg support

The health endpoint is open so load balancers can probe it; every data endpoint requires the api key.

Prerequisites

An active Azure subscription, an SSH key pair, and a VNet + subnet in the target region. Standard_B2s (2 vCPU / 4 GiB RAM) is a good starting point; scale up for larger indexes or higher query volume. NSG inbound: allow 22/tcp from your management network and 80/tcp from the clients that query Typesense (front port 80 with TLS for public exposure — see Enabling HTTPS).

Step 1 — Deploy from the Azure Marketplace

Sign in to the Azure Portal, choose Create a resource, search the Marketplace for Typesense by cloudimg, and select Create. On Basics pick your subscription, resource group, region and size; under Administrator account choose SSH public key and paste your key; under Inbound port rules allow SSH (22) and HTTP (80). Review the dedicated data disk on the Disks tab, then Review + create then Create.

Step 2 — Deploy from the Azure CLI

az vm create \
  --resource-group <your-rg> \
  --name typesense \
  --image <marketplace-image-urn> \
  --size Standard_B2s \
  --admin-username azureuser \
  --ssh-key-values ~/.ssh/id_ed25519.pub \
  --vnet-name <your-vnet> --subnet <your-subnet> \
  --public-ip-sku Standard

az vm open-port --resource-group <your-rg> --name typesense --port 80 --priority 1010

Step 3 — Connect to your VM

ssh azureuser@<vm-public-ip>

Step 4 — Confirm the services are running

systemctl is-active typesense.service nginx.service
ss -tln | grep -E ':80 |:8108 '
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1/health

Both services report active, the server listens on loopback 127.0.0.1:8108 and nginx on :80, and the health endpoint returns 200.

Step 5 — Retrieve your api key

The api key is generated uniquely on the first boot of your VM and written to a root only file:

sudo cat /root/typesense-credentials.txt

The TYPESENSE_API_KEY value is the key; callers authenticate by sending it in the X-TYPESENSE-API-KEY header. There is no default key baked into the image, so nothing to rotate before you go live.

Step 6 — Call the API and confirm auth is enforced

The health probe is open; data endpoints require the api key. Read the key into a shell variable, confirm the server version, and prove that a request without the key is rejected:

KEY=$(sudo grep '^TYPESENSE_API_KEY=' /root/typesense-credentials.txt | cut -d= -f2-)
curl -s -H "X-TYPESENSE-API-KEY: $KEY" http://127.0.0.1/debug | python3 -c "import sys,json; print('version:', json.load(sys.stdin)['version'])"
echo "no key   -> HTTP $(curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1/collections)"
echo "with key -> HTTP $(curl -s -o /dev/null -w '%{http_code}' -H "X-TYPESENSE-API-KEY: $KEY" http://127.0.0.1/collections)"

A request to /collections without the key returns 401; with the key it returns 200.

Step 7 — Create a collection, index a document and run typo tolerant search

Create a collection (a schema), add a document, then search with a deliberate typo to see Typesense return the right result anyway:

KEY=$(sudo grep '^TYPESENSE_API_KEY=' /root/typesense-credentials.txt | cut -d= -f2-)
curl -s -X POST http://127.0.0.1/collections -H "X-TYPESENSE-API-KEY: $KEY" -H 'Content-Type: application/json' \
  -d '{"name":"books","fields":[{"name":"title","type":"string"}]}' -o /dev/null -w 'create -> HTTP %{http_code}\n'
curl -s -X POST http://127.0.0.1/collections/books/documents -H "X-TYPESENSE-API-KEY: $KEY" -H 'Content-Type: application/json' \
  -d '{"id":"1","title":"The Hitchhiker Guide to the Galaxy"}' -o /dev/null -w 'index  -> HTTP %{http_code}\n'
curl -s "http://127.0.0.1/collections/books/documents/search?q=hitchiker&query_by=title" -H "X-TYPESENSE-API-KEY: $KEY" \
  | python3 -c "import sys,json; d=json.load(sys.stdin); print('found:', d.get('found'), '->', d['hits'][0]['document']['title'] if d.get('hits') else None)"

The search query hitchiker is misspelled yet still matches The Hitchhiker Guide to the Galaxy — Typesense corrects typos automatically. Collections and documents you create persist on the dedicated data disk at /var/lib/typesense.

Step 8 — From your application

Point any Typesense client (JavaScript, Python, Go, PHP, Ruby and more) at the VM. Use the VM public IP as the host, port 80, protocol http (or 443 and https once you enable TLS), and the api key from Step 5. Replace <vm-public-ip> and <your-api-key>:

curl "http://<vm-public-ip>/collections/books/documents/search?q=galaxy&query_by=title" \
  -H "X-TYPESENSE-API-KEY: <your-api-key>"

The install layout keeps the server binary on the OS disk and all search data on the dedicated data disk, run by an unprivileged service account.

Enabling HTTPS

For production, terminate TLS at nginx with a real domain pointed at the VM's public IP. Install certbot and request a certificate (replace the domain):

sudo apt-get update && sudo apt-get install -y certbot python3-certbot-nginx
sudo certbot --nginx -d your-domain.example.com

certbot edits the nginx site at /etc/nginx/sites-available/cloudimg-typesense to add the TLS listener and arranges automatic renewal. Point your client at https://your-domain.example.com and keep sending the api key.

Backup and maintenance

All Typesense data — the on disk store, indexes and documents — lives on the dedicated data disk at /var/lib/typesense. Snapshot that disk in Azure to back up your search data. The api key is in /etc/typesense/typesense-server.ini (api-key). Keep the OS patched with sudo apt update && sudo apt upgrade. Restart with sudo systemctl restart typesense.service; view logs with sudo journalctl -u typesense.service or under /var/log/typesense.

Support

This image is backed by 24/7 cloudimg support. Contact us by email and chat for help with schema and collection design, semantic and vector search configuration, backups, TLS termination and scaling.

All product and company names are trademarks or registered trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.