dolthub / dolthub/dolt

docs: Production deployment guide - includes macOS launchd, not just Linux

Open
#11,225 1 comment 0 reactions 0 assignees View on GitHub
customer issue documentation enhancement sql server
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.