Skip to content

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
  2. Prepare: make setup-docker-single
  3. Start: make start-docker-single
  4. Verify: make verify-docker-single
  5. Docker multi-user + Postgres
  6. Prepare: export generated ADMIN_USERNAME / ADMIN_PASSWORD, then make setup-docker-multi
  7. Start: make start-docker-multi
  8. Verify: make verify-docker-multi
  9. Local single-user
  10. Install: make install-local
  11. Prepare: make setup-local-single
  12. Start: make start-local-single
  13. Verify: make verify-local-single
  14. 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:

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