jedarden/miroir

Fork 0

Commit graph

Author	SHA1	Message	Date
jedarden	91c99bb414	docs(migrations): add re-index and live cutover migration guides (P11.3) Adds two new migration path documents for users migrating from single-node Meilisearch to Miroir: - from-meilisearch-reindex.md: For large corpora (> 10 GB), re-index from source data. Covers database, queue, and S3-based indexing with performance tips and troubleshooting. - from-meilisearch-live-cutover.md: Zero-downtime migration via dual-write. Includes degraded mode handling (X-Miroir-Degraded header), rollback procedures, and metrics to watch during cutover. Both docs include SDK examples (Python, TypeScript, Go), verification steps, and troubleshooting sections. Acceptance: - All 3 migration docs complete (dump-reload existed) - Dump-reload covers streaming + broadcast fallback modes - Live cutover names X-Miroir-Degraded header and metrics Closes: miroir-uyx.3 Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>	2026-05-24 14:39:58 -04:00
jedarden	c5238b1bcd	docs(troubleshooting): add common issues guide and diagnostic playbook (P11.5) Implements P11.5 acceptance criteria: - Created docs/troubleshooting.md with 10 common issues - Created docs/troubleshooting/diagnostics.md with systematic diagnostic playbook - Documented 3 required plan §11 issues (primary key required, degraded search results, stuck tasks) - Added 7 additional issues from Phase 9 chaos testing and operations - Cross-linked from README, migration runbook, and dump import guide Documented issues: 1. "primary key required" - Miroir vs Meilisearch difference 2. Search returns fewer results - degraded node handling 3. Task polling stuck - per-node task status recovery 4. Node drain blocked - RF constraints 5. Migration stuck after coordinator crash - recovery procedures 6. High memory usage on Redis - cleanup procedures 7. Index creation fails - topology inconsistency 8. Alias flip conflicts - single vs multi alias types 9. Search timeout during migration - throttling options 10. CDC cursor out of sync - recovery and re-index Diagnostic playbook covers: - Cluster health checks (pods, nodes, resources) - Topology verification and node agreement - Metrics analysis (degraded shards, task queue, latency) - Log analysis for error patterns - Task status inspection - Anti-entropy status - External dependency checks - Self-diagnostics and canary tests Closes: miroir-uyx.5	2026-05-24 14:02:13 -04:00

Author

SHA1

Message

Date

jedarden

91c99bb414

docs(migrations): add re-index and live cutover migration guides (P11.3)

Adds two new migration path documents for users migrating from
single-node Meilisearch to Miroir:

- from-meilisearch-reindex.md: For large corpora (> 10 GB), re-index
  from source data. Covers database, queue, and S3-based indexing
  with performance tips and troubleshooting.

- from-meilisearch-live-cutover.md: Zero-downtime migration via
  dual-write. Includes degraded mode handling (X-Miroir-Degraded
  header), rollback procedures, and metrics to watch during cutover.

Both docs include SDK examples (Python, TypeScript, Go), verification
steps, and troubleshooting sections.

Acceptance:
- All 3 migration docs complete (dump-reload existed)
- Dump-reload covers streaming + broadcast fallback modes
- Live cutover names X-Miroir-Degraded header and metrics

Closes: miroir-uyx.3

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

2026-05-24 14:39:58 -04:00

jedarden

c5238b1bcd

docs(troubleshooting): add common issues guide and diagnostic playbook (P11.5)

Implements P11.5 acceptance criteria:
- Created docs/troubleshooting.md with 10 common issues
- Created docs/troubleshooting/diagnostics.md with systematic diagnostic playbook
- Documented 3 required plan §11 issues (primary key required, degraded search results, stuck tasks)
- Added 7 additional issues from Phase 9 chaos testing and operations
- Cross-linked from README, migration runbook, and dump import guide

Documented issues:
1. "primary key required" - Miroir vs Meilisearch difference
2. Search returns fewer results - degraded node handling
3. Task polling stuck - per-node task status recovery
4. Node drain blocked - RF constraints
5. Migration stuck after coordinator crash - recovery procedures
6. High memory usage on Redis - cleanup procedures
7. Index creation fails - topology inconsistency
8. Alias flip conflicts - single vs multi alias types
9. Search timeout during migration - throttling options
10. CDC cursor out of sync - recovery and re-index

Diagnostic playbook covers:
- Cluster health checks (pods, nodes, resources)
- Topology verification and node agreement
- Metrics analysis (degraded shards, task queue, latency)
- Log analysis for error patterns
- Task status inspection
- Anti-entropy status
- External dependency checks
- Self-diagnostics and canary tests

Closes: miroir-uyx.5

2026-05-24 14:02:13 -04:00

2 commits