Setup Worker Instances (Optional)¶

This step configures multiple TGFS worker instances for load balancing.

It allows:

• Running multiple server instances
• Distributing traffic using Nginx

⚠ This step is optional. You can skip it if a single instance is sufficient.

1. systemd Setup¶

Service Architecture¶

TG-FileStream uses:

• tgfs.service → Main instance
• tgfs-worker@.service → Worker instances (templated)

Each worker:

• Runs on a different port
• Uses a separate session
• Can be load balanced via Nginx

Create Worker Template Service¶

Create:

sudo nano /etc/systemd/system/tgfs-worker@.service

Paste:

[Unit]
Description=TG-FileStream Worker
After=network.target
Requires=tgfs.service

[Service]
Type=simple
User=<username>
Group=<group>

WorkingDirectory=<TG-FileStream Clone Path>

ExecStart=<TG-FileStream Clone Path>/<virtual-env-dir>/bin/python -m tgfs --port %i --no-update --session %i

Restart=always
RestartSec=3

NoNewPrivileges=true
PrivateTmp=true

StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

Adjust: - Replace <username> with your system username. - Replace <group> with your group name (often same as username). - Replace <TG-FileStream Clone Path> with the absolute path to your cloned TG-FileStream directory. - Replace <virtual-env-dir> with the name of your virtual environment directory (usually venv).

[Unit]
Description=TG-FileStream Worker
After=network.target
Requires=tgfs.service

[Service]
Type=simple
User=ubuntu
Group=ubuntu

WorkingDirectory=/home/ubuntu/tg-filestream

ExecStart=/home/ubuntu/tg-filestream/venv/bin/python -m tgfs --port %i --no-update --session %i

Restart=always
RestartSec=3

NoNewPrivileges=true
PrivateTmp=true

StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

How the Worker Template Works¶

%i is replaced by the instance name.

Example:

sudo systemctl start tgfs-worker@8081

This runs:

python -m tgfs --port 8081 --no-update --session 8081

Reload systemd¶

sudo systemctl daemon-reload

Start Worker Instances¶

Example:

sudo systemctl start tgfs-worker@8081
sudo systemctl start tgfs-worker@8082
sudo systemctl start tgfs-worker@8083

Enable at boot:

sudo systemctl enable tgfs-worker@8081
sudo systemctl enable tgfs-worker@8082
sudo systemctl enable tgfs-worker@8083

Check Status¶

sudo systemctl status tgfs-worker@8081

View Logs¶

sudo journalctl -u tgfs-worker@8081 -f

Restart & Stop Workers¶

Restart worker:

sudo systemctl restart tgfs-worker@<PORT>

or

sudo systemctl restart "tgfs-worker@*.service" --all

Stop worker:

sudo systemctl stop tgfs-worker@<PORT>

or

sudo systemctl stop "tgfs-worker@*.service" --all

2. Nginx Setup for Workers¶

Modify existing Nginx configuration:

sudo nano /etc/nginx/sites-available/tgfs

Update the upstream block:

upstream aiohttp_backend {
    least_conn;
    keepalive 32;

    server <Bind Address>:<PORT> max_fails=3 fail_timeout=30s;
    server <Bind Address>:<PORT> max_fails=3 fail_timeout=30s;
    server <Bind Address>:<PORT> max_fails=3 fail_timeout=30s;
}

Replace:

• <Bind Address> with HOST
• <PORT> with worker ports (e.g., 8080, 8081, 8082)

upstream aiohttp_backend {
    least_conn;
    keepalive 32;

    server 127.0.0.1:8080 max_fails=3 fail_timeout=30s;
    server 127.0.0.1:8081 max_fails=3 fail_timeout=30s;
    server 127.0.0.1:8082 max_fails=3 fail_timeout=30s;
    server 127.0.0.1:8083 max_fails=3 fail_timeout=30s;
}

Test Configuration¶

sudo nginx -t
sudo systemctl reload nginx

How Load Balancing Works¶

User → Nginx (Port 80) → aiohttp_backend (least_conn) → Workers → Telegram

Nginx distributes traffic based on active connections.

3. Scaling Workers¶

To add a new worker:

1. Start it:

sudo systemctl start tgfs-worker@<PORT>

sudo systemctl start tgfs-worker@8084

1. Add it to the Nginx upstream block:

server <Bind Address>:<PORT> max_fails=3 fail_timeout=30s;

server 127.0.0.1:8084 max_fails=3 fail_timeout=30s;

1. Reload Nginx:

sudo systemctl reload nginx