Migrating a Typesense Ubuntu Server to Another Server: Backup + Restore

Migrating your self-hosted Typesense instance to a new server is a crucial task—whether you’re upgrading hardware, moving to another cloud provider, or just performing server maintenance.

This guide walks you through the correct steps to backup, transfer, and restore your Typesense data safely and reliably.

Key Concepts

Typesense stores your data in the path defined by the data-dir parameter (e.g., /var/lib/typesense). However, this data cannot be safely backed up while the server is running, as it keeps files open for writes.

To avoid corruption, Typesense provides a Snapshot API to take consistent backups.

1. Create a Backup Using the Snapshot API

Best option if your Typesense instance is running normally.

Call the Snapshot API to create a filesystem-safe snapshot:

curl -X POST 'http://localhost:8108/snapshot' \
  -H 'X-TYPESENSE-API-KEY: YOUR_ADMIN_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"snapshot_path": "/tmp/typesense-snapshot"}'

Then archive the snapshot directory:

tar -czvf backup.tar.gz -C /tmp typesense-snapshot

(Optional) Clean up the snapshot directory:

rm -rf /tmp/typesense-snapshot

2. Alternative: Stop Typesense and Copy the Data Directory

If the Snapshot API isn’t available (e.g., Typesense is unresponsive):

Stop the Typesense server:

sudo systemctl stop typesense-server.service

Then archive the data directory directly:

tar -czvf backup.tar.gz -C /var/lib typesense

Important: Only do this after stopping the server to ensure file consistency.

3. Transfer the Backup to Another Server Using SCP + SSH Keys

Generate SSH keys (if you haven’t already) on your local machine:

ssh-keygen -t ed25519 -C "[email protected]"

Save it in the default location (~/.ssh/id_ed25519) and leave the passphrase blank for automation.

Copy the public key to the new server:

ssh-copy-id -i ~/.ssh/id_ed25519.pub user@new-server-ip

Transfer the backup using SCP:

scp -i ~/.ssh/id_ed25519 backup.tar.gz user@new-server-ip:/tmp/

If this doesn’t work, first make sure that the ed25519.pub contents are moved to a new line in the file:

~/.ssh/authorized_keys

4. Restore Backup on the New Server

You might still need to install Typesense on the new server, set up SSL, etc.

Then, stop any running Typesense instance:

sudo systemctl stop typesense-server.service

Clean the existing data directory (verify that this really is your new, empty, server, not your old server with data):

sudo rm -rf /var/lib/typesense/*

Extract the backup:

sudo tar -xzf /tmp/backup.tar.gz -C /var/lib/

Make sure the extracted data is at the correct path, e.g., /var/lib/typesense.

Start Typesense again and remove the backup tar file:

sudo systemctl start typesense-server.service
rm /tmp/backup.tar.gz

Typesense will detect the snapshot on startup and rebuild its in-memory indices.

Final Checklist

• Backup created using Snapshot API or after stopping Typesense
• Data archived and verified
• SSH key-based access configured
• SCP transfer completed securely
• Typesense restarted successfully on the new server

Pro Tips

• Test your backup before relying on it in production. Try restoring it to a staging server.
• Automate regular snapshots using cron + curl + tar.
• Use secure API keys and never expose the Typesense admin key in public scripts.
• Always check the Typesense logs after starting the service: journalctl -u typesense-server.service

Conclusion

Migrating a Typesense instance doesn’t have to be scary. With a solid understanding of how the snapshot mechanism works and a bit of SSH magic, you can move your data between servers reliably and safely.

If you run into issues with the snapshot API, a cold shutdown and manual backup still works—just follow the steps carefully.

It’s all on your own risk.

Last Updated on 30 July 2025