docs: clarify dump/snapshot staging uses TMPDIR

[capJavert]

Description

Creating a dump or snapshot first builds an uncompressed staging copy in the directory pointed to by TMPDIR (default /tmp), not in --dump-dir or --snapshot-dir. On instances with a large database and a small /tmp partition this causes "No space left on device" even when the configured output directory has free space. Document the behavior and the TMPDIR fix.

So i struggled with this one for quite a while until realising the TMPDIR nuance so think it should be part of the docs at least.

I used Claude code for partial investigation of what is happening with TMPDIR.

Checklist

For internal Meilisearch team member only:

• I checked and followed our internal guidelines
• ⚠️ I updated the code samples according to our internal guidelines

For external maintainers

• Did you use any AI tool while implementing this PR (code, tests, docs, etc.)? If yes, disclose it in the PR description and describe what it was used for. AI usage is allowed when it is disclosed.
• Have you made sure that the title is accurate and descriptive of the changes?

Documentation Clarification: Dump and Snapshot Staging Behavior

This documentation PR clarifies how Meilisearch handles dump and snapshot creation, particularly around where temporary staging files are written.

What Changed

• Updated resources/self_hosting/configuration/reference.mdx with new notes for --dump-dir/MEILI_DUMP_DIR and --snapshot-dir/MEILI_SNAPSHOT_DIR.
• Clarified that these options only control the location of the final compressed dump/snapshot output files.

Key Points

• During dump/snapshot creation, Meilisearch first creates an uncompressed staging copy in a temporary directory under TMPDIR (defaulting to /tmp).
• As a result, users can encounter “No space left on device” errors when /tmp is too small—even if the configured dump/snapshot output directory has sufficient free space.
• The documentation provides guidance to resolve storage issues by setting TMPDIR to a filesystem with adequate capacity.

Technical Details

• Files changed: resources/self_hosting/configuration/reference.mdx
• Lines changed: +8/-0
• Impact: Documentation only; no code behavior changes

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 384fe04e-6693-4ee3-b8d4-9c0b8fdb3742

📥 Commits

Reviewing files that changed from the base of the PR and between d07fe13 and c2d153c.

📒 Files selected for processing (1)

• resources/self_hosting/configuration/reference.mdx

✅ Files skipped from review due to trivial changes (1)

• resources/self_hosting/configuration/reference.mdx

---

📝 Walkthrough

Walkthrough

Two informational notes are added to resources/self_hosting/configuration/reference.mdx: one under the --dump-dir option and one under --snapshot-dir. Both notes clarify that Meilisearch stages an uncompressed/temporary copy in the directory indicated by TMPDIR (defaulting to /tmp) before writing the final compressed file to the configured output directory.

Changes

TMPDIR Staging Notes for Dump and Snapshot Options

Layer / File(s)	Summary
TMPDIR staging notes for --dump-dir and --snapshot-dir resources/self_hosting/configuration/reference.mdx	Adds a note under each option clarifying that Meilisearch uses a TMPDIR-controlled staging directory (default /tmp) during dump and snapshot creation, with the final file written to the configured output directory.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~2 minutes

Poem

🐇 A warning most wise, a note most clear,
/tmp holds the staging before files appear.
No space on device? Check TMPDIR first!
The rabbit has documented the worst.
Now snapshots and dumps shall confuse you no more~ ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title directly and specifically describes the main change: clarifying that dump/snapshot staging uses TMPDIR instead of the output directories.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

🧹 Nitpick comments (1)

resources/self_hosting/configuration/reference.mdx (1)

128-130: ⚡ Quick win

Use consistent terminology across the dump and snapshot notes.

The dump note (L129) describes staging as "uncompressed copy" while the snapshot note (L301) describes it as "full flat copy." Since both describe the same underlying mechanism, use parallel terminology. "Uncompressed copy" is more precise and directly conveys what happens during staging.

📝 Suggested revision for snapshot note (lines 300–302)

 <Note>
-`--snapshot-dir` only controls where the final `.snapshot` file is written. While creating a snapshot, Meilisearch first copies a full flat copy of your database into a temporary staging directory. This directory is located in the path indicated by the `TMPDIR` environment variable, defaulting to `/tmp` on most systems, and not in `--snapshot-dir`. On instances with a large database and a small `/tmp` partition, this can cause `No space left on device` errors even when `--snapshot-dir` points to a volume with plenty of free space. To avoid this, set `TMPDIR` to a directory on a volume with enough space for a full copy of your database before launching Meilisearch.
+`--snapshot-dir` only controls where the final `.snapshot` file is written. While creating a snapshot, Meilisearch first builds an uncompressed copy of your database in a temporary staging directory. This directory is located in the path indicated by the `TMPDIR` environment variable, defaulting to `/tmp` on most systems, and not in `--snapshot-dir`. On instances with a large database and a small `/tmp` partition, this can cause `No space left on device` errors even when `--snapshot-dir` points to a volume with plenty of free space. To avoid this, set `TMPDIR` to a directory on a volume with enough space for an uncompressed copy of your database before launching Meilisearch.
 </Note>

Also applies to: 300-302

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@resources/self_hosting/configuration/reference.mdx` around lines 128 - 130,
The documentation uses inconsistent terminology to describe the staging
directory behavior in two different notes. At lines 128-130 (dump note), the
staging directory is described as an "uncompressed copy" of data, while at lines
300-302 (snapshot note), the same concept is referred to as a "full flat copy."
Update the snapshot note at lines 300-302 to replace "full flat copy" with
"uncompressed copy" to maintain consistent and precise terminology across both
notes, since they both describe the same underlying staging mechanism.

Source: Coding guidelines

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@resources/self_hosting/configuration/reference.mdx`:
- Around line 128-130: The documentation uses inconsistent terminology to
describe the staging directory behavior in two different notes. At lines 128-130
(dump note), the staging directory is described as an "uncompressed copy" of
data, while at lines 300-302 (snapshot note), the same concept is referred to as
a "full flat copy." Update the snapshot note at lines 300-302 to replace "full
flat copy" with "uncompressed copy" to maintain consistent and precise
terminology across both notes, since they both describe the same underlying
staging mechanism.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: aa6ff575-d5b2-4f12-875a-ccd352e8d86f

📥 Commits

Reviewing files that changed from the base of the PR and between 4430928 and d07fe13.

📒 Files selected for processing (1)

• resources/self_hosting/configuration/reference.mdx