Getting Started (Self-Hosting Profiles)

Choose exactly one base setup profile and follow it end-to-end. The solo journey is: prepare, start, verify, open the WebUI, complete a first successful chat, then add your first source.

Solo setup chooser

Recommended default:

• Run make quickstart from the repo root for the Docker single-user + WebUI path. That is the one obvious start command for most first-time solo users and the shortest alias for make setup-docker-single, make start-docker-single, and make verify-docker-single.
• Use Docker single-user when you want the shortest self-hosted path with the bundled WebUI and API-key auth.
• Use Local single-user as a peer solo choice for development, debugging, or contributor workflows; once the WebUI is reachable, it uses the same first-time setup flow.
• Use Docker multi-user + Postgres as the shared server/operator path when you need JWT auth, a first admin account, and bundled Postgres.

Deployment mode chooser:

Goal	Start here	Use when	Follow-up docs
Local single-user	Local single-user	You are developing, debugging, or running a local contributor setup.	Start the local WebUI after the API verifies, then complete first-time setup in the WebUI.
Docker single-user + WebUI	Docker single-user + WebUI	You want the shortest self-hosted path with the bundled WebUI and API key auth.	Minimal deployment, reverse proxy examples, and CDN/static assets.
Docker multi-user + Postgres	Docker multi-user + Postgres	You need JWT auth, a first admin account, and bundled Postgres.	Shared server/operator path: use the multi-user setup guide and operator checklist rather than the solo wizard.
Production or horizontal scaling	Docker multi-user + Postgres first, then horizontal scaling	You are preparing a shared or multi-node deployment.	Resource requirements, sidecar workers, and monitoring/operations docs.
Offline or air-gapped	Offline and air-gapped deployment	You need controlled egress, preloaded models, or disconnected operation.	Validate provider, model, and package assumptions before first production use.
Sidecar workers	Sidecar workers	You want background workers split from the API/WebUI process.	Use the profile guide first, then add worker compose or service units after the base stack verifies.
Audio or GPU setup	CPU audio setup or GPU/accelerated audio setup	Speech, transcription, TTS, or diarization is part of day-one setup.	Start from a healthy base profile, then add CPU or GPU audio prerequisites.
Monitoring and operations	make monitoring-up plus Docs/Deployment/Monitoring/README.md	You need Prometheus, Grafana, Alertmanager, or operator runbooks.	Monitoring published output is generated as top-level Docs/Published/Monitoring; do not move it by hand.

Canonical base profiles:

1. Docker single-user + WebUI
   • Prepare: make setup-docker-single
   • Start: make start-docker-single
   • Verify: make verify-docker-single
2. Docker multi-user + Postgres
   • Prepare: export generated ADMIN_USERNAME / ADMIN_PASSWORD, then make setup-docker-multi
   • Start: make start-docker-multi
   • Verify: make verify-docker-multi
3. Local single-user
   • Install: make install-local
   • Prepare: make setup-local-single
   • Start: make start-local-single
   • Verify: make verify-local-single
   • No-make shortcuts: ./quick-launch.sh, quick-launch.command, or .\quick-launch.ps1

Solo completion gate:

1. Verify the runtime and WebUI are reachable.
2. Open the WebUI.
3. Use the first-time setup wizard to configure chat/provider, ingest defaults, audio defaults, privacy/security, and optional advanced settings.
4. Complete the first successful chat. This is the setup completion gate.
5. Add your first source as the next guided milestone.

Generated multi-user admin bootstrap:

export ADMIN_USERNAME=tldw-admin
export ADMIN_PASSWORD="$(python3 -c 'import secrets; print(secrets.token_urlsafe(24))')"
make setup-docker-multi

Optional add-ons:

• First-time audio setup: CPU systems
• First-time audio setup: GPU/accelerated systems
• GPU/STT Add-on (legacy pointer to the accelerated guide)

How To Use These Guides

• Pick the profile that matches your target environment.
• For most users, start with the quickstart-docker-webui path via make quickstart.
• Treat LAN/custom-host browser access as advanced configuration and stay on the default same-origin browser API requests through the WebUI proxy unless you specifically need another device or origin to reach the API.
• Complete the guide sections in order: prepare, start, verify, first value, audio path, troubleshoot, and optional add-ons.
• Treat first value as the WebUI first-chat gate plus the immediate add-your-first-source milestone; the CLI ingest/search check is a runtime verification aid, not the product completion gate.
• Do not mix setup commands from other docs unless the guide explicitly links to them.
• Apply add-ons only after your chosen base profile is healthy.
• If speech is part of day-one setup, switch to the CPU or GPU/accelerated audio guide after the base profile is healthy instead of starting with the older STT/TTS reference pages.

Notes

• This page is the onboarding index for self-hosting.
• For legacy/deeper reference material, use linked docs from each profile guide.

Migration Disposition (2026-02-28)

Onboarding setup content was consolidated into these canonical guides.

Path	Action	Replacement
README.md	migrated	Docs/Getting_Started/README.md
Docs/Deployment/First_Time_Production_Setup.md	redirected	Docs/Getting_Started/Profile_Docker_Multi_User_Postgres.md
Docs/User_Guides/Server/CLI_Reference.md	redirected	Docs/Getting_Started/README.md