Getting Started & Installation
Relevant source files
The following files were used as context for generating this wiki page:
tldw (Too Long; Didn't Watch) is an open-source research assistant and media analysis platform designed for ingesting, transcribing, and querying various media formats. The system is built as a FastAPI-first backend paired with a Next.js WebUI, supporting a wide range of LLM providers and local inference options.
The installation process is designed to accommodate different deployment needs, ranging from a quick Docker-based production setup for single users to a more complex multi-user configuration with PostgreSQL. For contributors, a local development installation path is provided to facilitate code modifications and testing.
Sources: CLAUDE.md:3-10, Docs/Architecture.md:215-225
Deployment Profiles
The project defines three primary onboarding profiles based on the user's requirements for scale and persistence.
| Profile | Target Audience | Description |
|---|---|---|
| Docker Single-User | Personal/Self-hosted | The default recommended production path. Provisions a Dockerized stack with an API key. |
| Docker Multi-User + Postgres | Teams/Public | Recommended for multi-tenant deployments. Uses JWT auth and centralized PostgreSQL. |
| Local Single-User | Developers | Used for development, debugging, or contributors working on the core codebase. |
Sources: Docs/Plans/2026-03-15-default-production-onboarding.md:46-56, Docs/Architecture.md:215-225
Installation Flow Overview
The following diagram illustrates the high-level logic for selecting and executing an installation path.
Visual representation of the onboarding decision tree and associated commands.
Sources: Docs/Plans/2026-03-15-default-production-onboarding.md:148-170, Docs/Website/index.html:115-150
Quickstart (Recommended Path)
The default production onboarding path uses Docker to provision a single-user deployment. This path minimizes environment conflicts and ensures all dependencies, such as ffmpeg, are correctly configured.
Prerequisites
Before running the quickstart commands, users must perform a preflight check:
git clone https://github.com/rmusser01/tldw_server.git
cd tldw_server
make quickstart-prereqs
Sources: Docs/Website/index.html:120-130, Docs/Release_Checklist.md:105-110
Execution
To launch the full stack (API + WebUI), the following command is used:
make quickstart
This command delegates to quickstart-docker, setting up the API at localhost:8000 and the WebUI at localhost:8080.
Sources: Docs/Website/index.html:130-140, Docs/Plans/2026-03-15-default-production-onboarding.md:162-165
Manual & Development Installation
For developers or environments where Docker is not feasible, the project supports a local installation using a Python virtual environment.
Backend Setup
- Virtual Environment: Always activate the virtual environment first:
source .venv/bin/activate. - Dependencies: Install the package in editable mode:
pip install -e .. - Authentication: Initialize the AuthNZ system:
cp tldw_Server_API/Config_Files/.env.example tldw_Server_API/Config_Files/.env python -m tldw_Server_API.app.core.AuthNZ.initialize - Configuration: Add provider keys to the
.envorConfig_Files/config.txt.
Sources: CLAUDE.md:200-210, AGENTS.md:200-210
Startup Preflight Logic
The system includes a startup_preflight.py script that validates the environment before the server begins operation.
The sequence of checks performed during the startup preflight to ensure environment stability.
Sources: Docs/Plans/2026-03-30-ftue-audit-v2-implementation-plan.md:66-95
Configuration Management
The system uses a hierarchical configuration approach. Precedence is as follows: Environment Variables > .env file > config.txt.
| Configuration Type | Recommended Use |
|---|---|
| .env | Secrets (API keys, passwords, JWT tokens). |
| config.txt | Runtime tuning (chunking strategies, RAG settings, TTS providers). |
| Env Vars | Transient overrides (e.g., CI/CD, Docker Compose settings). |
Sources: Docs/Plans/2026-03-30-ftue-audit-v2-implementation-plan.md:175-185, CLAUDE.md:185-195
Core Component Access
Once installed and running, the following endpoints provide access to documentation and configuration:
- API Documentation:
http://127.0.0.1:8000/docs - Quickstart Config:
http://127.0.0.1:8000/api/v1/config/quickstart - WebUI (Docker):
http://localhost:8080
Sources: CLAUDE.md:215-220, Docs/Website/index.html:145-150
The installation of tldw_server establishes the foundation for a personal research workbench. By providing both containerized production paths and flexible local development setups, the project ensures that users can maintain control over their data—including source material, transcripts, and notes—regardless of the chosen deployment method.