docs: Production deployment guide - includes macOS launchd, not just Linux
- Dominant language
- Go
- Stars
- 24.4k
- Forks
- 873
- Avg merge
- 1d 5h
- Merged PRs (30d)
- 108
Description
## Problem
The deployment docs are Linux-only. macOS users get:
> "Some distributions of Linux do not support this tool; consult their documentation for configuration instructions."
That's it. No launchd plist example, no macOS-specific gotchas.
## What's missing
### macOS/launchd (completely undocumented)
- No launchd plist example
- No guidance on KeepAlive, RunAtLoad, graceful shutdown
- No mention of where to put data/logs on macOS
### Durability (buried in a 2023 blog post)
- `dolt_transaction_commit` is critical for durability but not explained in server docs
- No explanation of what survives ungraceful shutdown vs graceful
- The config.yaml template shows it commented out with no warning
### Crash recovery
- What to do after SIGKILL/OOM/power loss?
- How to verify database integrity?
- Any fsck equivalent?
## Real-world impact
I ran `dolt sql-server` on macOS for 13 days without launchd management. After an ungraceful restart, data was lost because:
1. No launchd = no graceful SIGTERM on logout/restart
2. `dolt_transaction_commit` wasn't enabled (I didn't know it mattered
3. No docs told me either of these things
## Suggested additions
1. **macOS launchd plist example** alongside the systemd unit
2. **Durability section** explaining and when fsync actually happens
3. **Production checklist** with recommended settings for both platforms
## Working launchd plist (for reference)
Here's what I ended up creating manually:
And the critical config.yaml setting:
EOF
)
Contributor guide
No contributing guide indexed for this repository
Research direction
Start by reading the existing Linux deployment docs and systemd unit, then compare the requested macOS launchd plist, durability guidance, crash-recovery steps, and production checklist against the server documentation and config.yaml template. Done means the documentation covers both platforms, explains dolt_transaction_commit and shutdown behavior, and gives macOS-specific paths and recovery guidance.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- macos
- Domain
- databases, documentation, operating-systems
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 42/100