Skip to content

Commit ca7d973

Browse files
DeekshithSHDeekshithSH
committed
Initial docs (upto systemd)
0 parents  commit ca7d973

12 files changed

Lines changed: 1671 additions & 0 deletions

‎.github/workflows/docs.yml‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
name: Documentation
2+
on:
3+
push:
4+
branches:
5+
- master
6+
- main
7+
permissions:
8+
contents: read
9+
pages: write
10+
id-token: write
11+
jobs:
12+
deploy:
13+
environment:
14+
name: github-pages
15+
url: ${{ steps.deployment.outputs.page_url }}
16+
runs-on: ubuntu-latest
17+
steps:
18+
- uses: actions/configure-pages@v5
19+
- uses: actions/checkout@v5
20+
- uses: actions/setup-python@v5
21+
with:
22+
python-version: 3.x
23+
- run: pip install zensical
24+
- run: zensical build --clean
25+
- uses: actions/upload-pages-artifact@v4
26+
with:
27+
path: site
28+
- uses: actions/deploy-pages@v4
29+
id: deployment

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
site
2+
.cache

‎docs/getting-started/overview.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# TG-FileStream
2+
3+
TG-FileStream is a high-performance Telegram file streaming backend.
4+
5+
It allows efficient file delivery using:
6+
- aiohttp
7+
- Nginx reverse proxy
8+
- Worker-based scaling
9+
- Optional load balancing
10+
11+
---
12+
13+
## Features
14+
15+
- Large file support (30MB – 4GB)
16+
- Worker scaling
17+
- Nginx compatible
18+
- Production-ready deployment
19+
20+
---
21+
22+
## Deployment Overview
23+
24+
Deployment flow:
25+
26+
1. Install dependencies
27+
2. Configure environment
28+
3. Test locally
29+
4. Setup systemd
30+
5. Setup Nginx
31+
6. Configure DNS

‎docs/index.md‎

Lines changed: 169 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,169 @@
1+
# TG-FileStream
2+
3+
> This project is released under the **GNU AGPL v3** license.
4+
> You are free to use, modify, and distribute it — as long as you share your changes under the same license.
5+
6+
**TG-FileStream** is a lightweight web server and Telegram client that acts as a proxy between Telegram servers and HTTP clients, allowing direct downloads of Telegram media files via HTTP.
7+
8+
> 📌 Check out [TODO.md](./TODO.md) for the latest development progress and planned features.
9+
10+
---
11+
12+
## 📝 Notes
13+
14+
- If you want one without database checkout [DeekshithSH/tgfilestream](https://github.com/DeekshithSH/tgfilestream) or [simple branch](https://github.com/SpringsFern/TG-FileStream/tree/simple)
15+
16+
---
17+
18+
## 🚀 Features
19+
20+
- Download Telegram media via HTTP links
21+
- Fast, concurrent chunked downloading
22+
23+
---
24+
25+
## 🛠️ Setup
26+
27+
### 1. Clone the repository
28+
29+
```bash
30+
git clone https://github.com/SpringsFern/TG-FileStream.git
31+
cd TG-FileStream
32+
```
33+
34+
### 2. Install dependencies
35+
36+
```bash
37+
pip install -r requirements.txt
38+
```
39+
40+
### 3. Create a `.env` file
41+
42+
Store the required environment variables in a `.env` file:
43+
44+
```env
45+
API_ID=1234567
46+
API_HASH=1a2b3c4d5e6f7g8h9i0jklmnopqrstuv
47+
BOT_TOKEN=1234567890:AAExampleBotTokenGeneratedHere
48+
BIN_CHANNEL=-1002605638795
49+
HOST=0.0.0.0
50+
PORT=8080
51+
PUBLIC_URL=http://127.0.0.1:8080
52+
DB_BACKEND=mongodb
53+
MONGODB_URI=mongodb://admin:pAswaRd@192.168.27.1
54+
```
55+
56+
### 4. Run the server
57+
58+
```bash
59+
python3 -m tgfs
60+
```
61+
62+
---
63+
64+
## ⚙️ Environment Variables
65+
66+
| Variable | Required/Default | Description |
67+
| -------------------- | ---------------------- | ---------------------------------------------------------------------------- |
68+
| `API_ID` | ✅ | App ID from [my.telegram.org](https://my.telegram.org) |
69+
| `API_HASH` | ✅ | API hash from [my.telegram.org](https://my.telegram.org) |
70+
| `BOT_TOKEN` | ✅ | Bot token from [@BotFather](https://t.me/BotFather) |
71+
| `BIN_CHANNEL` | ✅ | Channel ID where files sent to the bot are stored |
72+
| `DB_BACKEND` | ✅ | Which Database server to use. either `mongodb` or `mysql` |
73+
| `HOST` | `0.0.0.0` | Host address to bind the server (default: `0.0.0.0`) |
74+
| `PORT` | `8080` | Port to run the server on (default: `8080`) |
75+
| `PUBLIC_URL` | `https://0.0.0.0:8080` | Public-facing URL used to generate download links |
76+
| `DEBUG` | `False` | Show Extra Logs |
77+
| `CONNECTION_LIMIT` | `5` | Number of connections to create per DC for a single client |
78+
| `DOWNLOAD_PART_SIZE` | `1048576 (1MB)` | Number of bytes to request in a single chunk |
79+
| `NO_UPDATE` | `False` | Whether to reply to messages sent to the bot (True to disable replies) |
80+
| `SEQUENTIAL_UPDATES` | `False` | Handle telegram updates sequentially |
81+
| `FILE_INDEX_LIMIT` | `10` | Number of files to display at once with `/files` command |
82+
| `MAX_WARNS` | `3` | Maximum number of warns before user get banned |
83+
| `ADMIN_IDS` | `None` | User id of users who can use admin commands. Each id is seperated by `,` |
84+
| `ALLOWED_IDS` | `None` | Only users with these IDs can use the bot. Separate multiple IDs with `,` |
85+
86+
87+
### Multi Token Environment Variables
88+
| Variable | Required/Default | Description |
89+
| -------------- | ---------------- | ---------------------------------------------------------------------------- |
90+
| `MULTI_TOKENx` | ✅ | Use Multiple Telegram Clients when downloading files to avoid flood wait, Replace x with Number |
91+
| | | Example: |
92+
| `MULTI_TOKEN1` | | MULTI_TOKEN1=1234567890:AAExampleBotTokenGeneratedHere|
93+
| `MULTI_TOKEN2` | | MULTI_TOKEN2=0987654321:AAExampleBotTokenGeneratedHere|
94+
| `MULTI_TOKEN3` | | MULTI_TOKEN3=5432167890:AAExampleBotTokenGeneratedHere|
95+
96+
### MySQL Environment Variables
97+
Set the following variables if you choose MySQL as the database in `DB_BACKEND`
98+
99+
| Variable | Required/Default | Description |
100+
| ---------------- | ---------------- | ------------------------------------------ |
101+
| `MYSQL_HOST` | ✅ | MySQL DataBase Host Name |
102+
| `MYSQL_PORT` | ✅ | MySQL Database Port Number |
103+
| `MYSQL_USER` | ✅ | MySQL Database Username |
104+
| `MYSQL_PASSWORD` | ✅ | MySQL Database Password |
105+
| `MYSQL_DB` | ✅ | MySQL Database Name |
106+
| `MYSQL_MINSIZE` | `1` | Minimum sizes of the MySQL Connection pool |
107+
| `MYSQL_MAXSIZE` | `5` | Maximum sizes of the MySQL Connection pool |
108+
109+
### MongoDB Environment Variables
110+
Set the following variables if you choose MongoDB as the database in `DB_BACKEND`
111+
112+
| Variable | Required/Default | Description |
113+
| ---------------- | ---------------- | --------------------- |
114+
| `MONGODB_URI` | ✅ | MongoDB Database URI |
115+
| `MONGODB_DBNAME` | `TGFS` | MongoDB Database name |
116+
117+
---
118+
119+
## 📂 Usage
120+
121+
Once the server is running, you can:
122+
123+
- Access Telegram media files via HTTP:
124+
125+
- Or simply send a file to your bot, and it will respond with a download link.
126+
127+
This will stream the file directly from Telegram servers to the client.
128+
129+
---
130+
131+
## 🛠️ Contributing & Reporting Issues
132+
133+
Found a bug or have a feature request? Please [open an issue](https://github.com/SpringsFern/TG-FileStream/issues) on GitHub.
134+
135+
### 🐞 Reporting Issues
136+
When reporting a bug, **please include**:
137+
- Steps to reproduce the issue
138+
- Expected behavior vs actual behavior
139+
- Relevant logs, screenshots, or error messages (if any)
140+
- Environment details (OS, Python version, etc.)
141+
142+
**Example issue title:**
143+
`[Bug] Download fails for large files`
144+
145+
### 💡 Requesting Features
146+
When suggesting a new feature, **please include**:
147+
- A clear and concise description of the feature
148+
- The motivation or use case for it
149+
- Expected behavior (input/output examples if applicable)
150+
- Any alternatives you've considered
151+
152+
**Example feature title:**
153+
`[Feature] Add support for viewing generated links`
154+
155+
---
156+
157+
Contributions are welcome!
158+
Feel free to fork the project and open a pull request.
159+
160+
> 🔍 **Note:** Make sure to test your code thoroughly before submitting a PR to help maintain stability and performance.
161+
162+
---
163+
164+
## 💡 Credits
165+
166+
- **Deekshith SH** – Me
167+
- **Tulir** – Original author of [`tgfilestream`](https://github.com/tulir/tgfilestream), whose code inspired this project and is referenced in `paralleltransfer.py`
168+
169+
---

‎docs/setup/clone-repository.md‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
# Clone the Repository
2+
3+
This section explains how to download the TG-FileStream source code to your server.
4+
5+
---
6+
7+
## 1. Navigate to Your Deployment Directory
8+
9+
Choose a suitable directory to store the project.
10+
11+
Example:
12+
13+
```bash
14+
cd $HOME
15+
```
16+
17+
You may also use:
18+
19+
- `/var/www`
20+
- `/opt`
21+
- Any custom deployment directory
22+
23+
---
24+
25+
## 2. Clone the Repository
26+
27+
```bash
28+
git clone https://github.com/SpringsFern/TG-FileStream.git
29+
```
30+
31+
---
32+
33+
## 3. Change Directory
34+
35+
```bash
36+
cd TG-FileStream
37+
```
38+
39+
Verify the contents:
40+
41+
```bash
42+
ls -la
43+
```
44+
45+
You should see files and directory like:
46+
47+
- main application tgfs
48+
- requirements.txt
49+
- README.md
50+
51+
---
52+
53+
## 4. Optional: Checkout Specific Branch
54+
55+
If deploying a specific branch:
56+
57+
```bash
58+
git checkout <branch-name>
59+
```
60+
61+
Example:
62+
63+
```bash
64+
git checkout simple
65+
```
66+
67+
---
68+
69+
## 5. Keep Repository Updated (Optional)
70+
71+
To update later:
72+
73+
```bash
74+
git pull
75+
```
76+
77+
⚠ If you modified local files, commit or stash changes before pulling updates.

0 commit comments

Comments
 (0)