Deployment Guide

Deploy FilesLink to cloud platforms for free or low-cost hosting.

Note: For large file support (>20MB), see FastTelethon Setup or Render Deployment for integrated setup.

Quick Comparison

Platform	Free Tier	Setup Time	Keep-Alive Needed	Best For
Render (Blueprint)	Yes	5 min	Yes	Multi-service + FastTelethon ⭐
Railway	500 hrs/mo	5 min	No	Simple deployment
Render (Single)	Yes (sleeps)	5 min	Yes	Bot-only (no large files)
Fly.io	3 VMs free	10 min	No	Global edge
VPS	Varies	15 min	No	Full control

Render with FastTelethon (Recommended) ⭐

Deploy both FilesLink and FastTelethon service for full large file support (up to 2GB).

See: Render Deployment Guide for complete setup with session persistence.

Render (Bot Only - No Large Files)

Render offers a generous free tier, but instances sleep after 15 minutes of inactivity. Use Cloudflare Workers to prevent sleep!

Why Render + Keep-Alive?

✅ Completely free (without persistent disk)
✅ No sleep with keep-alive solution
✅ Automatic HTTPS
✅ Git-based deployment
⚠️ Ephemeral storage (maybe settings,links lost on restart)

Deploy to Render

Fork the Repository

# Fork https://github.com/bytetrix/fileslink

Create Web Service
- Go to render.com
- Click "New +" → "Web Service"
- Connect your GitHub repository
- Select your forked FilesLink repo
Configure Build

Render auto-detects Docker. Use these settings:
- Name: fileslink
- Region: Choose closest to you
- Branch: main
- Runtime: Docker
- Instance Type: Free

Add Environment Variables

BOT_TOKEN=your_telegram_bot_token
STORAGE_CHANNEL_ID=-1001234567890
APP_FILE_DOMAIN=https://yourapp.onrender.com/files
TELEGRAM_API_URL=https://api.telegram.org
TELEGRAM_LOCAL=false
SERVER_PORT=8080
RUST_LOG=warn

Deploy

Click "Create Web Service". First build takes ~5-10 minutes.

🔥 Prevent Sleep with Cloudflare Workers

Problem: Render free tier sleeps after 15 minutes of inactivity, causing 30-50 second cold starts.

Solution: Use Cloudflare Render Ping to keep your instance alive 24/7!

Quick Setup

Deploy Keep-Alive Worker

Click here to deploy instantly:

Or follow the setup guide.
Configure Your Render URL

Add your Render app URL to the worker:
```
const RENDER_SERVICE_URL = "https://yourapp.onrender.com";
```
Done!

The worker pings your app every 5 minutes, preventing sleep. Completely free!

How It Works

Cloudflare Worker runs on their edge network (100% free, 100k requests/day)
Pings your Render service every 5 minutes via HTTP health check
Keeps instance warm 24/7
No cold starts for your users!

Repository: ByteTrix/cloudflare-render-ping

🌐 Custom Domain Setup on Render

Want to use your own domain (e.g., files.yourdomain.com) instead of yourapp.onrender.com? Here's how:

Step 1: Add Custom Domain in Render

Open Your Service
- Go to your Render dashboard
- Select your FilesLink service
Navigate to Settings
- Click on the "Settings" tab
- Scroll down to "Custom Domains" section
Add Your Domain
- Click "Add Custom Domain"
- Enter your domain: files.yourdomain.com (or yourdomain.com)
- Click "Save"
Get DNS Records

Render will show you the DNS records to add. You'll see something like:

For subdomain (files.yourdomain.com):
```
Type: CNAME
Name: files (or files.yourdomain.com)
Value: yourapp.onrender.com
```
For root domain (yourdomain.com):
```
Type: A
Name: @ (or yourdomain.com)
Value: 216.24.57.1
```
Keep this page open - you'll need these values!

Step 2: Configure DNS at Your Domain Provider

The steps vary by provider, but here are instructions for popular ones:

Cloudflare DNS (Recommended)

Login to Cloudflare
- Go to dash.cloudflare.com
- Select your domain
Add DNS Record
- Click "DNS" → "Records"
- Click "Add record"
- Fill in:
  - Type: CNAME
  - Name: files (for files.yourdomain.com)
  - Target: yourapp.onrender.com
  - Proxy status: ⚠️ DNS only (gray cloud, not orange)
  - TTL: Auto
- Click "Save"
Important: Disable Cloudflare Proxy
- The cloud icon must be gray (DNS only)
- Orange cloud (proxied) will NOT work with Render!

Namecheap

Login to Namecheap
- Go to namecheap.com
- Go to Domain List → Manage
Add CNAME Record
- Go to "Advanced DNS" tab
- Click "Add New Record"
- Fill in:
  - Type: CNAME Record
  - Host: files
  - Value: yourapp.onrender.com
  - TTL: Automatic
- Click the checkmark to save

GoDaddy

Login to GoDaddy
- Go to godaddy.com
- My Products → DNS
Add CNAME Record
- Click "Add" under DNS Records
- Fill in:
  - Type: CNAME
  - Name: files
  - Value: yourapp.onrender.com
  - TTL: 600 seconds
- Click "Save"

Google Domains (now Squarespace)

Login to Your Registrar
- Go to your domain management
Add CNAME Record
- Go to DNS settings
- Click "Manage custom records"
- Add:
  - Host name: files
  - Type: CNAME
  - Data: yourapp.onrender.com
- Click "Save"

Step 3: Update Environment Variables

Once DNS is configured, update your APP_FILE_DOMAIN:

Go to Render Dashboard
- Select your service
- Click "Environment"

Update APP_FILE_DOMAIN

Change from:

APP_FILE_DOMAIN=https://yourapp.onrender.com/files

To your custom domain:

APP_FILE_DOMAIN=https://files.yourdomain.com/files

Save Changes

Render will automatically redeploy with the new domain.

Step 4: Wait for DNS Propagation

DNS changes can take 5 minutes to 48 hours to propagate
Usually takes 15-30 minutes
Check status: whatsmydns.net

Step 5: Verify HTTPS

Check Certificate

Render automatically provisions SSL certificate via Let's Encrypt.

Visit: https://files.yourdomain.com

You should see a valid SSL certificate (green lock icon).
Test Your Bot

Send a file to your Telegram bot and verify the download link uses your custom domain:
```
https://files.yourdomain.com/files/abc12345
```

Troubleshooting Custom Domain

Domain not working after 1 hour?

Verify DNS Records

# Windows PowerShell
Resolve-DnsName files.yourdomain.com

# Should show: yourapp.onrender.com

# Linux/Mac
dig files.yourdomain.com

# Should show CNAME pointing to yourapp.onrender.com

Check Cloudflare Proxy

If using Cloudflare, ensure proxy is disabled (gray cloud):
- Go to DNS settings
- Click the orange cloud to turn it gray
- Wait 5 minutes
Verify in Render

In Render dashboard → Settings → Custom Domains:
- Status should show "Verified" with green checkmark
- SSL status should show "Active"
Check APP_FILE_DOMAIN

Ensure environment variable is correct:
- Must use HTTPS
- Must end with /files
- Example: https://files.yourdomain.com/files
Redeploy if Needed

If domain is verified but not working:
- Go to "Manual Deploy"
- Click "Deploy latest commit"

SSL Certificate Issues?

Render automatically provisions SSL via Let's Encrypt
Can take up to 15 minutes after DNS verification
If stuck, try removing and re-adding the custom domain

Getting "Service Unavailable"?

Check if your service is running (not sleeping)
Deploy the Cloudflare keep-alive worker
Update the worker with your custom domain

Update Keep-Alive Worker

If you're using the Cloudflare keep-alive solution, update it with your custom domain:

// In your Cloudflare Worker
const RENDER_SERVICE_URL = "https://files.yourdomain.com"; // Update this

This ensures the worker pings your custom domain to keep the service alive.

Railway

Railway is the easiest and most reliable option for FilesLink.

Why Railway?

✅ No sleep on free tier (500 hours/month)
✅ Automatic HTTPS
✅ One-click deployment from GitHub
✅ Environment variables in UI
✅ Free PostgreSQL if needed

Deploy to Railway

Fork the Repository

# Fork https://github.com/bytetrix/fileslink to your account

Create New Project
- Go to railway.app
- Click "New Project"
- Select "Deploy from GitHub repo"
- Choose your forked repository

Configure Environment Variables

In Railway dashboard, add these variables:

BOT_TOKEN=your_telegram_bot_token
STORAGE_CHANNEL_ID=-1001234567890
APP_FILE_DOMAIN=https://yourapp.up.railway.app/files
TELEGRAM_API_URL=https://api.telegram.org
TELEGRAM_LOCAL=false
SERVER_PORT=8080
RUST_LOG=warn

Get Your Domain

Railway automatically assigns a domain like:
```
https://yourapp.up.railway.app
```
Copy this and update APP_FILE_DOMAIN to:
```
https://yourapp.up.railway.app/files
```
Deploy

Railway automatically builds and deploys! Monitor logs in the dashboard.

Custom Domain (Optional)

Go to project settings
Click "Generate Domain" or "Custom Domain"
Update APP_FILE_DOMAIN with your new domain

Fly.io (Global Edge)

Best for low-latency global deployment.

Why Fly.io?

✅ 3 VMs free (256MB RAM each)
✅ Global edge deployment
✅ Automatic HTTPS
✅ No sleep issues

Deploy to Fly.io

Install Fly CLI

# Windows (PowerShell)
iwr https://fly.io/install.ps1 -useb | iex

# macOS/Linux
curl -L https://fly.io/install.sh | sh

Login
```
flyctl auth login
```

Create fly.toml

Create fly.toml in your project root:

app = "your-app-name"
primary_region = "iad"  # Change to your region

[build]

[http_service]
  internal_port = 8080
  force_https = true
  auto_stop_machines = false
  auto_start_machines = true
  min_machines_running = 1

[[vm]]
  memory = '256mb'
  cpu_kind = 'shared'
  cpus = 1

Create App
```
flyctl apps create your-app-name
```

Set Environment Variables

flyctl secrets set BOT_TOKEN=your_token
flyctl secrets set STORAGE_CHANNEL_ID=-1001234567890
flyctl secrets set APP_FILE_DOMAIN=https://your-app-name.fly.dev/files
flyctl secrets set TELEGRAM_API_URL=https://api.telegram.org
flyctl secrets set TELEGRAM_LOCAL=false
flyctl secrets set SERVER_PORT=8080
flyctl secrets set RUST_LOG=warn

Deploy
```
flyctl deploy
```

Monitor

# View logs
flyctl logs

# Check status
flyctl status

# Scale regions
flyctl regions add lax syd  # Add Los Angeles, Sydney

VPS / Self-Hosted

For complete control and unlimited resources.

Requirements

Ubuntu 20.04+ or Debian 11+
Docker and Docker Compose installed
Domain name (optional)
SSH access

Setup

SSH into Server
```
ssh user@your-server-ip
```

Install Docker

# Update system
sudo apt update && sudo apt upgrade -y

# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# Install Docker Compose
sudo apt install docker-compose -y

# Add user to docker group
sudo usermod -aG docker $USER
newgrp docker

Clone Repository

git clone https://github.com/bytetrix/fileslink.git
cd fileslink

Configure Environment

cp .env.example .env
nano .env

Update these values:

BOT_TOKEN=your_token
STORAGE_CHANNEL_ID=-1001234567890
APP_FILE_DOMAIN=https://yourdomain.com/files
TELEGRAM_API_URL=https://api.telegram.org
TELEGRAM_LOCAL=false
SERVER_PORT=8080
RUST_LOG=warn

Start Services
```
docker compose up -d
```

Setup Reverse Proxy (Optional)

Install nginx for HTTPS:

sudo apt install nginx certbot python3-certbot-nginx -y

Create nginx config /etc/nginx/sites-available/fileslink:

server {
    listen 80;
    server_name yourdomain.com;
    
    location / {
        proxy_pass http://localhost:8080;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Enable and get SSL certificate:

sudo ln -s /etc/nginx/sites-available/fileslink /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx
sudo certbot --nginx -d yourdomain.com

Auto-Start on Boot

Create systemd service /etc/systemd/system/fileslink.service:

[Unit]
Description=FilesLink Bot
After=docker.service
Requires=docker.service

[Service]
Type=oneshot
RemainAfterExit=yes
WorkingDirectory=/home/user/fileslink
ExecStart=/usr/bin/docker compose up -d
ExecStop=/usr/bin/docker compose down

[Install]
WantedBy=multi-user.target

Enable service:

sudo systemctl daemon-reload
sudo systemctl enable fileslink
sudo systemctl start fileslink

Maintenance

# View logs
docker compose logs -f

# Restart services
docker compose restart

# Update to latest version
git pull
docker compose pull
docker compose up -d

# Backup file mappings
docker compose exec fileslink-app cat /app/file_mappings.json > backup.json

Environment Variables by Platform

Railway

BOT_TOKEN=your_token
STORAGE_CHANNEL_ID=-1001234567890
APP_FILE_DOMAIN=https://yourapp.up.railway.app/files
TELEGRAM_API_URL=https://api.telegram.org
TELEGRAM_LOCAL=false
SERVER_PORT=8080
RUST_LOG=warn

Render (+ Cloudflare Keep-Alive)

BOT_TOKEN=your_token
STORAGE_CHANNEL_ID=-1001234567890
APP_FILE_DOMAIN=https://yourapp.onrender.com/files
TELEGRAM_API_URL=https://api.telegram.org
TELEGRAM_LOCAL=false
SERVER_PORT=8080
RUST_LOG=warn

Fly.io

BOT_TOKEN=your_token
STORAGE_CHANNEL_ID=-1001234567890
APP_FILE_DOMAIN=https://your-app-name.fly.dev/files
TELEGRAM_API_URL=https://api.telegram.org
TELEGRAM_LOCAL=false
SERVER_PORT=8080
RUST_LOG=warn

VPS (with domain)

BOT_TOKEN=your_token
STORAGE_CHANNEL_ID=-1001234567890
APP_FILE_DOMAIN=https://yourdomain.com/files
TELEGRAM_API_URL=https://api.telegram.org
TELEGRAM_LOCAL=false
SERVER_PORT=8080
RUST_LOG=warn

Troubleshooting

Deployment Fails

Check logs:

# Railway: View in dashboard
# Render: View in dashboard
# Fly.io:
flyctl logs
# VPS:
docker compose logs

Common issues:

Missing environment variables
Wrong APP_FILE_DOMAIN format (must end with /files)
Invalid channel ID format (must start with -100)

Bot Not Responding

Verify BOT_TOKEN is correct
Check bot is admin in storage channel
Verify STORAGE_CHANNEL_ID is correct (use @userinfobot)
Check application logs

Download Links Don't Work

Verify APP_FILE_DOMAIN matches your actual domain
Must end with /files
Use HTTPS in production
Check application is accessible at the domain

Render Instance Sleeping

Solution: Deploy Cloudflare Render Ping

This keeps your Render instance awake 24/7 for free!

Cost Comparison

Platform	Monthly Cost	Storage	Bandwidth	Notes
Railway	Free (500hrs)	Unlimited	Unlimited	Best for hobby projects
Render	Free	Unlimited	100GB	Sleeps without keep-alive
Fly.io	Free (3 VMs)	3GB	160GB	Good for global deployment
VPS	$5-20/mo	Varies	Varies	Full control

Recommendation: Start with Railway for simplicity, or Render + Cloudflare Keep-Alive for completely free hosting.

Next Steps

Configuration Guide - Set up environment variables
Telegram Setup - Configure your storage channel
FAQ - Common issues and solutions
CLI Usage - Manage permissions from command line

Questions? Open an issue on GitHub.

FilesExpand file tree

DEPLOYMENT.md

Latest commit

History

DEPLOYMENT.md

File metadata and controls

Deployment Guide

Quick Comparison

Render with FastTelethon (Recommended) ⭐

Render (Bot Only - No Large Files)

Why Render + Keep-Alive?

Deploy to Render

🔥 Prevent Sleep with Cloudflare Workers

Quick Setup

How It Works

🌐 Custom Domain Setup on Render

Step 1: Add Custom Domain in Render

Step 2: Configure DNS at Your Domain Provider

Cloudflare DNS (Recommended)

Namecheap

GoDaddy

Google Domains (now Squarespace)

Step 3: Update Environment Variables

Step 4: Wait for DNS Propagation

Step 5: Verify HTTPS

Troubleshooting Custom Domain

Update Keep-Alive Worker

Railway

Why Railway?

Deploy to Railway

Custom Domain (Optional)

Fly.io (Global Edge)

Why Fly.io?

Deploy to Fly.io

Monitor

VPS / Self-Hosted

Requirements

Setup

Maintenance

Environment Variables by Platform

Railway

Render (+ Cloudflare Keep-Alive)

Fly.io

VPS (with domain)

Troubleshooting

Deployment Fails

Bot Not Responding

Download Links Don't Work

Render Instance Sleeping

Cost Comparison

Next Steps