drumsergio/telegram-archive repository overview

⁠Telegram Archive

Automated Telegram backup with Docker. Performs incremental backups of messages and media on a configurable schedule.

This project is developed with AI assistance (Claude Code).

⁠Features

⁠📦 Backup Engine

• Incremental backups — Only downloads new messages since last backup
• Scheduled execution — Configurable cron schedule (default: every 6 hours)
• Real-time listener — Catch edits, deletions, and new messages instantly between backups
• Album support — Groups photos/videos sent together as albums
• Service messages — Tracks group photo changes, title changes, user joins/leaves
• Forwarded message info — Shows original sender name for forwarded messages
• Channel signatures — Displays post author when channels have signatures enabled
• Media deduplication — Symlinks identical files to save disk space
• Avatars always fresh — Profile photos updated on every backup run

⁠🎬 Media Support

• Photos, videos, documents, stickers, GIFs
• Voice messages and audio files with in-browser player
• Polls with vote counts and results
• Configurable size limits and selective download

⁠🌐 Web Viewer

• Telegram-like dark UI — Feels like the real app
• Mobile-friendly — Responsive design with iOS/Android optimizations
• Integrated lightbox — View photos and videos without leaving the page
• Keyboard navigation — Arrow keys to browse media, Esc to close
• Real-time updates — WebSocket sync shows new messages instantly
• Push notifications — Get notified even when browser is closed
• Search — Find chats by name and messages by text, across the whole archive or inside one chat
• JSON export — Download chat history with date range filters

⁠🔒 Security & Privacy

• Multi-user access control — Master account + DB-backed viewer accounts with per-user chat whitelists
• Admin panel — Create, edit, delete viewer accounts with fine-grained chat permissions
• Audit logging — Track all login attempts, admin actions, and API access
• Authenticated media — Media files require login and respect per-user permissions
• Mass deletion protection — Rate limiting prevents accidental data loss
• Runs as non-root — Docker best practices

⁠🗄️ Database

• SQLite (default) — Zero config, single file
• PostgreSQL — For larger deployments with real-time LISTEN/NOTIFY

⁠🗺️ Roadmap

See docs/ROADMAP.md⁠ for what's planned, and docs/CHANGELOG.md⁠ for complete version history.

Have a feature request? Open an issue⁠!

⁠📸 Screenshots

Click to view Desktop and Mobile screenshots

⁠Desktop

⁠Mobile

⁠Docker Images

Two separate Docker images are available (v4.0+):

⁠Quick Start

⁠1. Get Telegram API Credentials

1. Go to https://my.telegram.org/apps⁠
2. Log in with your phone number
3. Create a new application (any name/platform)
4. Note your API ID (numbers) and API Hash (letters+numbers)

⁠2. Deploy with Docker

# Clone the repository
git clone https://github.com/GeiserX/Telegram-Archive
cd Telegram-Archive

# Create data directories
mkdir -p data/session data/backups
chmod -R 755 data/

# Configure environment
cp .env.example .env

Edit .env with your credentials:

TELEGRAM_API_ID=12345678          # Your API ID
TELEGRAM_API_HASH=abcdef123456    # Your API Hash  
TELEGRAM_PHONE=+1234567890        # Your phone (with country code)
VIEWER_USERNAME=admin             # Required for web access
VIEWER_PASSWORD=change-this       # Required for web access

Optional: enable a SOCKS5 proxy for all Telegram connections (useful in regions where Telegram is blocked or behind corporate firewalls)

TELEGRAM_PROXY_TYPE=socks5
TELEGRAM_PROXY_ADDR=127.0.0.1
TELEGRAM_PROXY_PORT=1080
TELEGRAM_PROXY_USERNAME=
TELEGRAM_PROXY_PASSWORD=
TELEGRAM_PROXY_RDNS=false

⁠3. Authenticate with Telegram

Option A: Using the provided scripts (recommended for fresh installs)

# Run authentication
./init_auth.sh    # Linux/Mac
# init_auth.bat   # Windows

Option B: Direct Docker command (for existing deployments or re-authentication)

If your session expires or you need to re-authenticate an existing container:

# Generic command - adjust volume paths and credentials
docker run -it --rm \
  -e TELEGRAM_API_ID=YOUR_API_ID \
  -e TELEGRAM_API_HASH=YOUR_API_HASH \
  -e TELEGRAM_PHONE=+YOUR_PHONE_NUMBER \
  -e SESSION_NAME=telegram_backup \
  -v /path/to/your/session:/data/session \
  drumsergio/telegram-archive:8.13.0 \
  python -m src auth

Example for docker compose deployment:

# If using docker compose with a session volume
docker run -it --rm \
  --env-file .env \
  -v ./data:/data \
  drumsergio/telegram-archive:8.13.0 \
  python -m src auth

# Then restart the backup container
docker compose restart telegram-backup

What happens during authentication:

1. The script connects to Telegram's servers
2. Telegram sends a verification code to your Telegram app (check "Telegram" chat)
3. Enter the code when prompted
4. If you have 2FA enabled, enter your password when prompted
5. Session is saved to the mounted volume for future use

⁠4. Start Services

docker compose up -d

View your backup at http://localhost:8000⁠

The default compose binds the viewer to 127.0.0.1. Put it behind a reverse proxy only after setting VIEWER_USERNAME and VIEWER_PASSWORD. To deliberately run without auth for a local-only viewer, set ALLOW_ANONYMOUS_VIEWER=true — this grants read-only access only; writes still require the master account.

⁠Common Issues

⁠Web Viewer

The standalone viewer image (drumsergio/telegram-archive-viewer) lets you browse backups without running the backup scheduler.

# Example: Viewer-only deployment
services:
  telegram-viewer:
    image: drumsergio/telegram-archive-viewer:8.13.0
    ports:
      - "127.0.0.1:8000:8000"
    environment:
      BACKUP_PATH: /data/backups
      DATABASE_DIR: /data/db
      VIEWER_USERNAME: admin
      VIEWER_PASSWORD: your-secure-password
      VIEWER_TIMEZONE: Europe/Madrid
    volumes:
      # SQLite needs write access for WAL files, sessions, audit logs, and thumbnails.
      # Use :ro only when the database is PostgreSQL and media is mounted separately.
      - /path/to/data:/data

Browse your backups at http://localhost:8000⁠

⁠Configuration

All settings are configured via environment variables. Set them in your .env file or as environment: entries in docker-compose.yml. See .env.example⁠ for a ready-to-use template.

⁠Environment Variables

The Scope column shows whether each variable applies to the backup scheduler (B), the web viewer (V), or both (B/V).