tgdrive/teldrive 2.0.0

on GitHub

Teldrive 2.0 — rebuilt backend, new web UI

This is a full rewrite of Teldrive. The server, API, database layer, background jobs, and web interface were all rebuilt. Read the breaking changes and migration section before upgrading.

Highlights

• New backend — explicit domain services for auth, files, uploads, transfers, shares, channels, and bots, with a versioned TypeSpec-defined HTTP API.
• New web UI — embedded in the server binary. File browsing with list/grid views, split view, search, resumable uploads with progress, previews, trash, sharing with user grants, and a tasks view for background jobs.
• Resumable uploads & streaming downloads — session-based uploads with BLAKE3 hashing, HTTP range support for seeking/streaming large files.
• Background jobs — PostgreSQL-backed job queue with retries, periodic schedules, orphan cleanup, trash purging, and server-side local imports.
• Live events — server-sent events power upload progress and task updates in the UI.
• Content encryption — optional versioned server-managed file encryption with key rotation.
• Access control — per-user roles, allowed-users restriction, API keys, and share passwords/expiry.
• Nix support — flake with source and binary packages, NixOS and Home Manager modules, and shell completions.
• Installers — checksum-verified Linux and Windows install scripts published with the docs.

Breaking changes

• New HTTP API. v1 API clients, rclone backends pinned to v1, and third-party integrations need updating. See the API reference in the docs.
• New configuration. Config file format, setting names, environment variable mapping (TELDRIVE_*), and CLI flags have changed. Do not reuse a v1 config file; regenerate from the new reference.
• New database schema. v2 uses a new schema (default teldrive) plus job/event tables. A v1 database is migrated automatically on first start (see below) — this is one-way.
• Container tags changed. Images are now ghcr.io/tgdrive/teldrive:2 and ghcr.io/tgdrive/teldrive:2.0.0. There is no latest tag and the old :v2 branch tag is discontinued. Pin an exact version in production.
• Telegram session re-login may be required. Stored v1 sessions are migrated where possible; if login state is lost, sign in again — your files and channels are preserved in Telegram/PostgreSQL.
• Dropped/renamed features. Check the docs for the current feature set; v1-only endpoints and flags are gone.

Migrating from v1

1. Stop all v1 writes and shut down every v1 instance.
2. Back up PostgreSQL (pg_dumpall) and save your keys separately — you cannot recover encrypted data without them.
3. Point v2 at the same PostgreSQL database and configure a stable security.data-key plus signing key.
4. Start v2 (or run teldrive check). It detects the v1 schema and migrates data into staging schemas, validates, then swaps. Watch the logs for database.legacy_migration.completed and reported row counts.
5. Verify users, channels, bots, folder structure, and test downloads before exposing the server. Keep the pre-migration backup until you have a tested post-migration backup.
6. To opt out of automatic migration, set database.auto-migrate-legacy: false — startup will then refuse a v1 database instead of migrating it.

Full steps: https://tgdrive.github.io/teldrive/deployment/v1-migration

Fresh install

• Docker/Podman: https://tgdrive.github.io/teldrive/getting-started/quick-start (Compose generator included)
• Linux/Windows binary: https://tgdrive.github.io/teldrive/installation/binary
• Nix / NixOS / Home Manager: https://tgdrive.github.io/teldrive/installation/nix

Verify downloads against teldrive_checksums.txt:

sha256sum -c teldrive_checksums.txt --ignore-missing

Upgrade checklist (v2.x to v2.y)

1. Read the release notes. 2. Record the current version. 3. Back up PostgreSQL and confirm you have the data key and content-encryption keys. 4. Keep the previous image/binary available. 5. Deploy, run teldrive check, smoke-test login, listing, upload/download, shares, and tasks.

An older binary may not work against a schema migrated by a newer version — a full rollback can require restoring the pre-upgrade database backup.