Meilisearch backup naar Hetzner Storage Box (Restic)¶

Overzicht¶

Op de server FL09PLO-MEI01 (Hetzner VPS CPX11, beheerd via Ploi.io) draait een Meilisearch instantie. Elke nacht wordt een volledige dump van Meilisearch aangemaakt via de REST API. Deze dump wordt vervolgens door Restic via SFTP gesynchroniseerd naar de Hetzner Storage Box.

Er wordt bewust gekozen voor een dump in plaats van een snapshot. Een dump is versie-onafhankelijk (moet wel dezelfde versie of nieuwer zijn) en kan worden geïmporteerd in elke Meilisearch versie, wat herstel aanzienlijk flexibeler maakt.

Restic deduplicatie

Restic slaat alleen gewijzigde blokken op (content-addressed deduplicatie). De opslag groeit daardoor beperkt, ook bij dagelijkse volledige dumps.

Configuratie overzicht¶

Onderdeel	Waarde
Server	FL09PLO-MEI01
Meilisearch user	`root`
Meilisearch data	`/home/ploi/data.ms`
Dump directory	`/var/backups/meilisearch/dumps`
Backup script	`/usr/local/bin/meilisearch-backup.sh`
Restic repository	`sftp:storagebox-brekz-384620:/home/restic`
Logbestand	`/var/log/meilisearch-backup.log`
Schema	Dagelijks om 03:00 uur
Retentiebeleid	Onbeperkt (geen automatische opschoning)
StorageBox	Hetzner BX11 #384620

Installatie & configuratie¶

Stap 1 — Benodigde software installeren¶

Verbind via SSH als ploi met FL09PLO-MEI01 via je SSH-client, en start een root sessie:

sudo -i

Installeer vervolgens Restic en jq:

apt update && apt install -y restic jq

Controleer de installatie:

restic version
jq --version

Stap 2 — SSH sleutel aanmaken voor de Storage Box¶

Maak een toegewijd SSH sleutelpaar aan voor de Restic verbinding:

ssh-keygen -t ed25519 -f /root/.ssh/storagebox_384620_restic -N "" -C "restic@fl09plo-mei01"

Voeg de publieke sleutel toe aan de Hetzner Storage Box via de door Hetzner aanbevolen methode:

cat /root/.ssh/storagebox_384620_restic.pub | ssh -p 23 <storagebox-user>@<storagebox-user>.your-storagebox.de install-ssh-key

Voer het wachtwoord van de Storage Box in wanneer daarom gevraagd wordt (beschikbaar in 1Password).

Hetzner Storage Box inloggegevens

De inloggegevens van de Hetzner Storage Box zijn beschikbaar in 1Password.

Hetzner - Storage box BX11 Brekz (FTP) BX11 #384620

Stap 3 — SSH alias configureren¶

Voeg een SSH alias toe in /root/.ssh/config zodat Restic de Storage Box kan bereiken:

Host storagebox-brekz-384620
    HostName <storagebox-user>.your-storagebox.de
    User <storagebox-sub-user>
    Port 23
    IdentityFile /root/.ssh/storagebox_384620_restic

Poortnummer

Hetzner Storage Box gebruikt poort 23 voor SSH/SFTP, niet de standaard poort 22.

Test de verbinding, je zou geen wachtwoord in hoeven te vullen hiervoor:

ssh storagebox-brekz-384620

Stap 4 — Dump directory aanmaken¶

Maak de lokale directory aan waar Meilisearch de dumps in wegschrijft:

mkdir -p /var/backups/meilisearch/dumps

Stap 5 — Meilisearch dump directory configureren in Ploi¶

De dump directory moet worden meegegeven als opstartparameter aan Meilisearch.

Ga in de Ploi UI naar de parameters van de Meilisearch service en voeg toe:

--dump-dir /var/backups/meilisearch/dumps

Herstart vereist

Na het aanpassen van de parameter moet Meilisearch opnieuw worden gestart via Ploi voordat de instelling actief is.

Stap 6 — Master key bestand aanmaken¶

De Meilisearch master key staat hardcoded als parameter in de systemd service. Maak een apart bestand aan zodat het backup script de key kan uitlezen:

nano /root/.meilisearch-master-key
chmod 600 /root/.meilisearch-master-key

Plak de master key in de editor en sla op en sluit nano.

Master key plakken

Let op dat als je de master key plakt, dat je niet daarna nog een enter of iets anders toevoegd.

De key zou dan niet meer overeenkomen met wat Meilisearch verwacht, en de backup zal dan falen.

Master key ophalen

De master key is op twee manieren op te halen:

Via de Ploi UI: navigeer naar de Meilisearch service en bekijk de ingestelde parameters.

Via de server: lees de systemd service definitie uit:

systemctl cat meilisearch

Stap 7 — Restic wachtwoord instellen¶

Restic versleutelt de repository met een wachtwoord. Het wachtwoord is beschikbaar in 1Password onder:

Entry: Hetzner - Storage box BX11 Brekz (FTP) BX11 #384620
Sectie: FL09PLO-MEI01 Restic backup
Veld: Restic repository password

Sla het wachtwoord op in een bestand op de server:

nano /root/.meilisearch-restic-password
chmod 600 /root/.meilisearch-restic-password

Plak het repository wachtwoord in de editor en sla op en sluit nano.

Stap 8 — Restic repository initialiseren¶

Maak eerst de doeldirectory aan op de Storage Box via SFTP:

sftp -P 23 storagebox-brekz-384620
mkdir restic
exit

Initialiseer daarna de Restic repository op de Storage Box:

restic -r sftp:storagebox-brekz-384620:/home/restic --password-file /root/.meilisearch-restic-password init

Controleer of de initialisatie geslaagd is:

restic -r sftp:storagebox-brekz-384620:/home/restic --password-file /root/.meilisearch-restic-password snapshots

Stap 9 — Backup script aanmaken¶

Maak het backup script aan:

nano /usr/local/bin/meilisearch-backup.sh

Plak de volgende inhoud:

#!/bin/bash

set -euo pipefail

MEILI_URL="http://localhost:7700"
MEILI_MASTER_KEY_FILE="/root/.meilisearch-master-key"
DUMP_DIR="/var/backups/meilisearch/dumps"
RESTIC_REPO="sftp:storagebox-brekz-384620:/home/restic"
RESTIC_PASSWORD_FILE="/root/.meilisearch-restic-password"
LOG_PREFIX="[$(date '+%Y-%m-%d %H:%M:%S')]"

MEILI_MASTER_KEY=$(cat "$MEILI_MASTER_KEY_FILE")

if [ -z "$MEILI_MASTER_KEY" ]; then
    echo "$LOG_PREFIX ERROR: MEILI_MASTER_KEY not found in $MEILI_MASTER_KEY_FILE." >&2
    exit 1
fi

echo "$LOG_PREFIX Starting Meilisearch dump..."

# Trigger dump via REST API
TASK_RESPONSE=$(curl -s -f -X POST "$MEILI_URL/dumps" \
    -H "Authorization: Bearer $MEILI_MASTER_KEY")
TASK_UID=$(echo "$TASK_RESPONSE" | jq -r '.taskUid')

if [ -z "$TASK_UID" ] || [ "$TASK_UID" = "null" ]; then
    echo "$LOG_PREFIX ERROR: Failed to start dump task. Response: $TASK_RESPONSE" >&2
    exit 1
fi

echo "$LOG_PREFIX Dump started (task UID: $TASK_UID). Waiting for completion..."

# Wait for dump to complete
MAX_WAIT=300
ELAPSED=0
while true; do
    STATUS=$(curl -s -f "$MEILI_URL/tasks/$TASK_UID" \
        -H "Authorization: Bearer $MEILI_MASTER_KEY" | jq -r '.status')

    if [ "$STATUS" = "succeeded" ]; then
        echo "$LOG_PREFIX Dump completed successfully."
        break
    elif [ "$STATUS" = "failed" ] || [ "$STATUS" = "canceled" ]; then
        echo "$LOG_PREFIX ERROR: Dump failed (status: $STATUS)." >&2
        exit 1
    fi

    if [ "$ELAPSED" -ge "$MAX_WAIT" ]; then
        echo "$LOG_PREFIX ERROR: Dump timed out after ${MAX_WAIT}s." >&2
        exit 1
    fi

    sleep 5
    ELAPSED=$((ELAPSED + 5))
done

echo "$LOG_PREFIX Starting Restic backup of $DUMP_DIR..."

restic -r "$RESTIC_REPO" --password-file "$RESTIC_PASSWORD_FILE" backup "$DUMP_DIR"

echo "$LOG_PREFIX Restic backup done. Cleaning up local dumps (keeping last 7)..."

# Remove all but the 7 most recent dumps (sorted by filename = timestamp)
ls -t "$DUMP_DIR"/*.dump 2>/dev/null | tail -n +8 | xargs -r rm -f

echo "$LOG_PREFIX Backup completed successfully."

Maak het script uitvoerbaar:

chmod +x /usr/local/bin/meilisearch-backup.sh

Stap 10 — Script handmatig testen¶

Voer het script eenmalig handmatig uit om te controleren of alles werkt:

/usr/local/bin/meilisearch-backup.sh

Controleer of er een dumpbestand is aangemaakt:

ls -lh /var/backups/meilisearch/dumps/

Controleer of de Restic snapshot is aangemaakt:

restic -r sftp:storagebox-brekz-384620:/home/restic --password-file /root/.meilisearch-restic-password snapshots

Stap 11 — Cronjob instellen¶

Voeg de cronjob toe aan de root crontab. Zorg dat je in een root sessie zit (sudo -i) voordat je dit uitvoert:

crontab -e

Voeg de volgende regel toe:

0 3 * * * /usr/local/bin/meilisearch-backup.sh >> /var/log/meilisearch-backup.log 2>&1

De cronjob draait dagelijks om 03:00 uur en doet het volgende in volgorde:

Triggert een Meilisearch dump via de REST API
Wacht tot de dump volledig is
Voert een Restic backup uit van de dump directory naar de Storage Box

Verificatie¶

Logs controleren¶

tail -f /var/log/meilisearch-backup.log

Restic snapshots bekijken¶

restic -r sftp:storagebox-brekz-384620:/home/restic --password-file /root/.meilisearch-restic-password snapshots

Inhoud van een snapshot inspecteren¶

restic -r sftp:storagebox-brekz-384620:/home/restic --password-file /root/.meilisearch-restic-password ls latest

Herstel procedure¶

Stap 1 — Dump ophalen uit Restic¶

Herstel de meest recente backup naar een tijdelijke directory:

mkdir -p /tmp/meilisearch-restore
restic -r sftp:storagebox-brekz-384620:/home/restic --password-file /root/.meilisearch-restic-password \
    restore latest --target /tmp/meilisearch-restore

Het herstelde dumpbestand (.dump) bevindt zich dan in /tmp/meilisearch-restore/var/backups/meilisearch/dumps/.

Stap 2 — Dump importeren in Meilisearch¶

Stop Meilisearch via Ploi, importeer de dump via de --import-dump vlag, en start daarna opnieuw:

# Voorbeeld — pas het pad aan naar het gewenste .dump bestand
meilisearch --db-path /home/ploi/data.ms \
    --import-dump /tmp/meilisearch-restore/var/backups/meilisearch/dumps/<bestandsnaam>.dump

Dataverlies bij importeren

Het importeren van een dump overschrijft de bestaande Meilisearch data. Zorg dat dit bewust wordt gedaan, bij voorkeur na het stoppen van de service.

Versie-onafhankelijkheid

Een Meilisearch dump kan worden geïmporteerd in een andere (nieuwere) versie van Meilisearch. Dit is het voornaamste voordeel ten opzichte van snapshots.