kakifilem
/
telegram-s3-uploader
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
telegram-s3-uploader/README.md

4.4 KiB
Raw Blame History

Telegram → S3 Uploader Bot

License Platform Python Framework Deploy Docker

A simple, private Telegram bot that uploads files to any S3-compatible storage (AWS S3, Cloudflare R2, MinIO, etc.) and returns a temporary presigned download link.

This project is designed to be:

  • Simple
  • Safe by default
  • Easy to deploy
  • Easy to extend

✨ Features

  • Upload files from Telegram to S3-compatible storage
  • Supports documents, videos, audio, and photos
  • Private bucket (no public access required)
  • Temporary presigned download links
  • User allowlist (private bot)
  • Works on local machine, VPS, Docker, and Railway
  • Clean, minimal codebase

📦 Supported Storage

This bot works with any S3-compatible provider, including:

  • AWS S3
  • Cloudflare R2
  • MinIO (local NAS)
  • Wasabi
  • DigitalOcean Spaces
  • Backblaze B2 (S3 API)

🔐 Security Model

  • Files are uploaded to a private bucket
  • Access is granted via temporary presigned URLs
  • Links expire automatically
  • Storage credentials are never exposed to users
  • Bot usage can be restricted with an allowlist
  • Local files are stored temporarily and cleaned up automatically

This bot is intended for private file upload and backup use cases.

🚀 Deployment

▶ Deploy on Railway

You can deploy this bot directly to Railway:

Deploy on Railway

After deployment, set the required environment variables in the Railway dashboard.

When deployed on Railway, this template attaches a Railway Bucket by default. You can remove it and configure any other S3-compatible storage via environment variables.

▶ Run locally

Python 3.13 is supported. Python 3.11+ is recommended for widest compatibility.

1. Clone the repository

git clone https://github.com/BigDaddyAman/telegram-s3-uploader
cd telegram-s3-uploader

2. Create virtual environment

python3.13 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies

pip install --upgrade pip
pip install -r requirements.txt

4. Configure environment

Copy .env.example to .env and fill in your values:

cp .env.example .env

5. Run the bot

python bot.py

▶ Run with Docker (build locally)

docker build -t telegram-s3-uploader .
docker run --env-file .env telegram-s3-uploader

⚙️ Environment Variables

Variable Description
API_ID Telegram API ID
API_HASH Telegram API hash
BOT_TOKEN Telegram bot token
ALLOWED_USERS Allowed Telegram user IDs (comma-separated)
S3_ENDPOINT Custom S3 endpoint (leave empty for AWS)
S3_REGION S3 region (required for AWS)
S3_ACCESS_KEY S3 access key
S3_SECRET_KEY S3 secret key
S3_BUCKET Bucket name
PRESIGNED_EXPIRE_SECONDS Presigned link expiration time (seconds)
ENABLE_PRESIGNED_URL Enable or disable presigned download links (true / false)

📁 File Storage Layout

Uploaded files are stored using a simple structure:

Files are downloaded to a temporary local directory and removed automatically after upload.

users/
└── <telegram_user_id>/
    └── YYYYMMDD_HHMMSS_filename.ext

This makes the storage easy to browse and suitable for backups.

🧭 Project Scope

This project is intentionally kept small and focused.

It is meant for:

  • Personal backups
  • Private file storage
  • Archiving Telegram content you own or manage

Features related to public distribution, streaming, or content sharing are out of scope.

🤝 Contributing

Contributions are welcome!

Please see CONTRIBUTING.md for guidelines and project scope.

🔐 Security

If you discover a security issue, please follow the instructions in SECURITY.md.

📄 License

This project is licensed under the MIT License. See LICENSE for details.