docs: add self-hosting backup guide

[sanmaxdev]

Summary

• Add English and Korean self-hosting backup guidance for .tapflow-data/.
• Cover SQLite/Litestream replication, restore order, and files that need separate backup.
• Add an Unreleased changelog entry.

Checklist

• Docs build passing
• No any
• No interface changes
• No sensitive info

Related .work/ docs

N/A

Closes #166

Summary by CodeRabbit

• Documentation
  • Added self-hosted relay backup guidance for persistent data stored under local.dataDir (default .tapflow-data/), covering the SQLite database (tapflow.db + WAL), uploaded files, recordings, and relay secrets (.env, jwt-secret).
  • Included recommended Litestream setup for replicating SQLite changes to S3-compatible object storage and clarified restore ordering for moving to a new host.
  • Updated the Korean self-hosting guide with the same backup/restore workflow, noting that Litestream protects only the SQLite database.

[vercel]

@sanmaxdev is attempting to deploy a commit to the jo-duchan's projects Team on Vercel.

A member of the Team first needs to authorize it.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 5b74824d-bdf4-4a16-b1d5-add981c0222e

📥 Commits

Reviewing files that changed from the base of the PR and between efaadaf and 6433a87.

📒 Files selected for processing (2)

• docs/guide/self-hosting.md
• docs/ko/guide/self-hosting.md

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

• docs/ko/guide/self-hosting.md
• docs/guide/self-hosting.md

---

📝 Walkthrough

Walkthrough

Adds backup documentation for self-hosted relay data in English and Korean, including .tapflow-data/ contents, Litestream-based SQLite replication, restore steps, and a changelog entry.

Changes

Self-hosted relay backup guidance

Layer / File(s)	Summary
Backup scope and inventory CHANGELOG.md, docs/guide/self-hosting.md, docs/ko/guide/self-hosting.md	Adds the new backup guidance entry and the backup sections that list relay state locations and the files or directories to include in backups.
Litestream setup and restore docs/guide/self-hosting.md, docs/ko/guide/self-hosting.md	Adds Litestream setup, replication, PM2 process separation, SQLite restore commands, and notes about which artifacts still require separate backup handling.

Estimated review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• jo-duchan/tapflow#304: Updates self-hosting guidance around relay secret persistence in .tapflow-data/.env, which overlaps with the backup and restore coverage for .env and jwt-secret.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly matches the main change: adding self-hosting backup guidance.
Description check	✅ Passed	The description follows the required template and includes a useful summary, checklist, and related docs section.
Linked Issues check	✅ Passed	The docs additions cover English/Korean backup guidance, Litestream replication, restore flow, and separate handling for non-DB artifacts, matching #166.
Out of Scope Changes check	✅ Passed	The only extra change is the changelog entry, which is in scope for the documented update.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ 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.}

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

docs/guide/self-hosting.md (1)

293-333: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

State the Litestream ownership boundary explicitly.

This section shows how to install and run Litestream, but it never says tapflow does not bundle or supervise it. Add that one sentence so the operational contract is unambiguous.

Suggested wording

+[Litestream](https://litestream.io/) is an external process; tapflow does not bundle or manage it.
 [Litestream](https://litestream.io/) streams SQLite WAL changes to object storage such as AWS S3, Cloudflare R2, Backblaze B2, or any S3-compatible endpoint. It does not require tapflow schema changes or a separate database server.

🤖 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 `@docs/guide/self-hosting.md` around lines 293 - 333, The Litestream setup
section should explicitly state that tapflow does not bundle, install, or
supervise Litestream itself. Add a single sentence near the Litestream
install/run steps in the self-hosting guide, using the existing Litestream and
tapflow relay setup context, to make it clear that operators are responsible for
managing Litestream as a separate process.

🤖 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.

Inline comments:
In `@docs/guide/self-hosting.md`:
- Around line 279-289: The self-hosting backup section hardcodes
`.tapflow-data/` instead of the effective data directory, which can mislead
operators on installs that override `local.dataDir` via `TAPFLOW_DATA_DIR`.
Update the wording in the self-hosting guide to refer to the resolved data dir
from `tapflow.config.json`/`config.ts`, and keep `.tapflow-data/` only as the
default example while preserving the inventory entries for `tapflow.db`, WAL
files, uploads, recordings, and secrets.

---

Nitpick comments:
In `@docs/guide/self-hosting.md`:
- Around line 293-333: The Litestream setup section should explicitly state that
tapflow does not bundle, install, or supervise Litestream itself. Add a single
sentence near the Litestream install/run steps in the self-hosting guide, using
the existing Litestream and tapflow relay setup context, to make it clear that
operators are responsible for managing Litestream as a separate process.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: eb3052f5-df3f-4a61-9941-c3a4119ccb8f

📥 Commits

Reviewing files that changed from the base of the PR and between 2db3a9b and 0bfb1bf.

📒 Files selected for processing (3)

• CHANGELOG.md
• docs/guide/self-hosting.md
• docs/ko/guide/self-hosting.md

[sanmaxdev]

Updated the backup section to use the resolved data directory, and clarified that Litestream runs as a separate process.

Rechecked:

• pnpm docs:build
• pre-commit lint/typecheck

[jo-duchan]

Checked the paths and behavior against the relay code — everything lines up:

• data dir default .tapflow-data/ and the TAPFLOW_DATA_DIR override (config.ts)
• tapflow.db + the WAL sidecars, since the relay opens the DB in WAL mode (db.ts, journal_mode = WAL)
• uploads/, recordings/, .env, and jwt-secret all resolve under the data dir
• the table list (accounts/apps/builds/sessions/comments/tokens/settings) matches the migrations

The "back up the WAL files too, or let Litestream capture them" note is the right call — a plain copy of a live SQLite db can miss un-checkpointed WAL data.

Approving. Two optional follow-ups, neither blocking:

1. KO: "해석된 데이터 디렉토리" reads a bit literal for resolved — "확정된" or "실제 사용되는 데이터 디렉토리" flows better.
2. brew install litestream is macOS-only, but the section above covers Linux VPS deploys. A one-line pointer to the Litestream release binary for Linux would cover those readers.