Build a private Telegram-backed streaming service, verify it locally, and make its HTTP endpoint reachable when you need remote access
Telegram-Stremio is a self-hosted FastAPI application that connects Telegram media, MongoDB, and a Stremio or Nuvio addon. In this guide, we install the project with Docker, prepare its required configuration, start the application, and verify the HTTP service on port 8000. We then connect the working local service to a Localtonet HTTP tunnel so compatible remote clients can reach it without inbound router port forwarding, firewall changes, a VPN, or a public IP address. Because project configuration can change between releases, we also show where to rely on the checked-out repository instead of copying unverified values from older forks or tutorials.
📋 What's in this guide
How Telegram-Stremio works
Telegram-Stremio is not a conventional media server that scans video files from a local disk. It uses Telegram channels and messages as the source of media records, MongoDB as the persistent application database, PyroFork for Telegram interaction and streaming, and FastAPI for the HTTP interface consumed by Stremio or Nuvio. The project also includes a web-based management panel.
When an authorized media file is forwarded to a configured Telegram channel, the application can process information in the filename or caption, associate the file with metadata, and store the relevant record in MongoDB. Its Stremio addon interface then provides catalog, metadata, and stream operations through HTTP endpoints. A compatible client uses those operations to display titles and request playback.
The current repository describes Docker as an official deployment method and identifies a VPS deployment using Docker and MongoDB as the recommended full-server approach. The repository contains a Dockerfile, docker-compose.yaml, sample_config.env, and startup scripts. Its application metadata declares port 8000, which is the local HTTP port used throughout this guide.
Self-hosting software does not change copyright, licensing, Telegram, or platform rules. Configure channels and content only when you have the necessary rights and permission. Do not expose private catalogs or streams to unauthorized users.
Prerequisites and decisions to make first
Choose a host that can remain online while clients use the addon. This may be a Linux server, a VPS, or another Docker-capable computer. Remote access through Localtonet does not require the host to have a public IP address, but both Telegram-Stremio and the Localtonet client must remain running for the complete path to work.
The host needs Git to obtain the repository, Docker Engine, and the current Docker Compose plugin. Docker must be able to create containers, networks, and persistent storage. The application also needs outbound internet connectivity to communicate with Telegram and any metadata services configured through the project.
Prepare the Telegram resources required by the current project configuration. These can include Telegram application credentials, a bot token, channels, and an authenticated Telegram user session. The exact required fields and setup workflow can change between Telegram-Stremio releases. Use the sample_config.env file from the exact revision you check out and the first-run web settings page as the authoritative inventory. Never copy credentials from screenshots, public examples, old forks, or another user's environment file.
You also need MongoDB. The official project describes Docker with MongoDB, and its repository includes a Compose definition. Before starting containers, inspect the checked-out docker-compose.yaml to determine whether that revision starts MongoDB as a Compose service or expects an external MongoDB connection. This distinction matters because an external connection requires a reachable database URI, while a bundled service requires durable Docker storage.
| Requirement | Why it is needed | What to verify |
|---|---|---|
| Git | Downloads and later updates the project repository | git --version completes successfully |
| Docker Engine | Builds and runs the application and supporting containers | docker version can contact the Docker daemon |
| Docker Compose plugin | Interprets the supplied docker-compose.yaml |
docker compose version completes successfully |
| MongoDB | Persists indexed media and application records | The checked-out Compose file or external connection provides it |
| Telegram credentials and channels | Allow the application to authenticate and process authorized media | Required current values are available but have not been shared publicly |
| Local port 8000 | Publishes the FastAPI service on the host | No unrelated process is already occupying the intended host port |
| Localtonet client | Creates the outbound connection used for optional remote access | The client can run on a device that reaches the HTTP service |
Check Docker before downloading the project
Run the following checks on the intended host. These commands verify the tools, but they do not install Docker because the correct installation method depends on the operating system and distribution.
git --version
docker version
docker compose version
If docker version shows client information but reports that it cannot connect to the daemon, start Docker and confirm that your user is allowed to use it. Avoid solving a permissions problem by making application files or credential files globally writable.
Plan persistent storage and backups
Container replacement is normal during updates. MongoDB data must therefore be stored in the persistent volume or host path declared by the Compose definition. Review that mapping before launch. Back up the database using a MongoDB-compatible procedure and protect the backup as carefully as the live database, because it can contain catalog records, user information, and operational configuration.
The project has evolved from environment-heavy configuration toward a first-time configuration file and a web settings interface. Field names, required values, and defaults found in older forks may not match the current upstream revision. This guide deliberately does not invent a complete environment-variable list. Read every entry in the checked-out sample_config.env before starting the application.
Install Telegram-Stremio with Docker
The following workflow uses the upstream repository and its supplied Docker Compose definition. Run it from a dedicated directory on the Docker host. If you are deploying for long-term use, record the commit or release you selected so you can reproduce and review the installation later.
Clone the upstream repository
Download the official repository and enter its working directory. Confirm that the expected Docker and configuration files exist before continuing.
Create the local configuration file
Copy sample_config.env to config.env. Open the new file locally, review every field, and replace only the documented placeholders with your own private values.
Inspect and validate the Compose definition
Review docker-compose.yaml for its services, MongoDB arrangement, storage mappings, port publication, and reference to config.env. Use Docker Compose validation to detect syntax and substitution errors before launch.
Build and start the deployment
Ask Docker Compose to build images where required and start the declared services in detached mode. Do not add unverified service names or override files.
Inspect status and startup logs
Confirm that the declared containers remain running, then inspect their combined logs for configuration, database, Telegram authentication, or port-binding errors.
Clone and inspect the repository
git clone https://github.com/weebzone/Telegram-Stremio.git
cd Telegram-Stremio
git status
ls
On a Unix-like host, the listing should include files such as Dockerfile, docker-compose.yaml, sample_config.env, and the application source. On another operating system, use its normal directory-listing command. Stop if those files are absent, because you may be in the wrong directory or on an unexpected revision.
Create a private configuration file
cp sample_config.env config.env
Open config.env in a local text editor. The current sample file, not a copied blog snippet, defines the accepted names and formatting. Telegram application identifiers, API hashes, bot tokens, session material, database connection details, and administrator secrets are credentials. Do not paste them into shell history, issue trackers, chat rooms, screenshots, or public repositories.
After editing, restrict access using the permission controls available on your host. On a Unix-like system where the file is owned by the deployment user, the following is a common way to limit it to that owner:
chmod 600 config.env
Do not commit config.env. Check git status before every commit or push, especially if you make local operational notes inside the repository.
Inspect MongoDB and port publication
Open docker-compose.yaml and answer four questions before starting it:
- Does the file declare a MongoDB service, or does the application expect an external MongoDB URI?
- Where is MongoDB data persisted, and will that storage survive container recreation?
- Does the application publish container port 8000 to host port 8000?
- Does the application load
config.env, and have all referenced substitutions been supplied?
Validate the resulting Compose model:
docker compose configThe validation command can render resolved environment values. Inspect its output only in a trusted terminal, do not redirect it into an unprotected file, and do not share it when requesting support. Redact tokens, hashes, session strings, database credentials, private URLs, and channel identifiers from diagnostic material.
Build and start the containers
docker compose up -d --build
docker compose ps
docker compose logs
The first build and startup can take longer because Docker may need to download base images, install dependencies, initialize MongoDB, and start the application. A container that repeatedly restarts is not healthy even if it appears briefly in docker compose ps. Read the earliest relevant error in the logs rather than repeatedly restarting the stack.
Exact container and service names are defined by the checked-out Compose file, so this guide does not guess them. Once you know the actual service name, Docker Compose can follow only that service's logs:
docker compose logs -f SERVICE_NAME
Replace SERVICE_NAME with a name shown by docker compose config --services. Do not type the placeholder literally.
Complete the first-time Telegram-Stremio configuration
A running container does not necessarily mean Telegram-Stremio is ready. The application still needs valid Telegram access, MongoDB connectivity, channel roles, and addon settings. The current project describes a first-time config.env stage followed by a web settings page where many options can be managed without restarts.
Configure Telegram access carefully
Obtain Telegram API credentials and bot credentials only through Telegram's official account and bot-management workflows. Enter them into the exact fields named by the current sample configuration. If the web panel offers in-application user login, complete that flow only through your own deployment and verify its address before entering a phone number, login code, or two-factor authentication password.
A Telegram bot must have the permissions required by the channels it processes. The project's channel guidance states that the bot should be an administrator in each configured authorization channel. Grant only the permissions necessary for the intended role and avoid reusing a public community channel as a private application control channel.
Assign one role to each channel
Telegram-Stremio supports several channel purposes, including authorization channels containing indexed media, manual content, announcements, global search, and skipped files requiring review. A channel should have one role. An authorization channel can separately be marked for anime handling where applicable.
Separating movies, television, anime, combined season packs, split files, announcements, and failed imports is an organizational practice rather than a technical requirement for every installation. It can nevertheless make access control, troubleshooting, and backups easier. Start with the smallest structure that satisfies your use case, verify it, and add complexity later.
Configure MongoDB without exposing it publicly
If MongoDB runs inside the Compose network, the application should use the internal service relationship defined by the Compose file. There is normally no remote-access reason to publish the MongoDB port to the internet. If you use an external database, restrict it to the application host or trusted network and use the authentication and transport protections supported by that deployment.
Database connectivity errors often result from using localhost incorrectly. Inside a container, localhost refers to that container, not to another Compose service and not automatically to the Docker host. Follow the connection value and service arrangement supplied by the current project rather than substituting an assumed hostname.
Use the management panel to finish application settings
Once the local web interface responds, open it from a trusted browser and complete the settings required by your selected revision. Configure only features you understand. Record which channels are assigned to which roles, which database is active, and how administrator access is protected.
The current project includes capabilities such as automatic and custom catalogs, private or exclusive catalogs, access tokens, per-user addon settings, announcements, search, and administrative activity views. Availability and exact controls can vary by release. Do not enable a feature merely because it appears in an older screenshot or fork.
Complete administrator configuration and access controls locally first. If the current revision supplies a default credential, placeholder secret, or initial setup mode, replace or close it before creating a public tunnel. A public HTTPS address protects transport to the tunnel edge, but it does not replace application authentication or safe authorization.
Verify the service locally before remote access
Local verification isolates application problems from tunnel problems. Do not create a public endpoint until the containers are stable, MongoDB is connected, the panel opens, and the addon behavior works on the local network.
Confirm container health and stability
Run docker compose ps more than once and ensure the application and required database services are not restarting.
Request the local HTTP service
From the Docker host, request http://127.0.0.1:8000. An HTTP response confirms that something is listening, even if the application redirects to another page.
Open the panel in a browser
Use the local address or the host's trusted LAN address and confirm that the expected Telegram-Stremio interface appears.
Test a controlled media record
Add one authorized test item through the project's documented channel workflow, then confirm that it is indexed with the expected title and metadata.
Test the local addon flow
Use the addon URL generated by your running instance and verify catalog loading and playback from a compatible client that can reach the local host.
A simple host-side HTTP test is:
curl -i http://127.0.0.1:8000
The exact successful status code and page path can vary with the application revision and its authentication state. A response proves that the TCP and HTTP path is working, but a 404 on a guessed route does not prove that the whole application is broken. Open the root address in a browser and inspect container logs for the routes or startup messages emitted by the installed revision.
If the application is intentionally bound only to loopback, test it from the same device. If the Compose file publishes it on the host's network interfaces, you can also test http://HOST_LAN_IP:8000 from another trusted device. Replace HOST_LAN_IP with the actual address. Do not assume that a LAN test is safe over an untrusted wireless network.
Verify indexing with one controlled item
The project reads filenames and captions to identify media. Movie records generally need a recognizable title, year, and quality label. Television episodes need a recognizable title plus season and episode notation such as S01E04, together with a quality label. Exact parsing behavior can change, so begin with one clearly named file you are authorized to use.
Forward the test file to an authorization channel in which the bot has the required role. Watch the application logs and management panel. If the title is misidentified, use the correction mechanism available in the installed version rather than repeatedly forwarding ambiguous filenames.
Verify the addon address, not only the panel
The management panel and the addon can share the same FastAPI service while using different paths. Loading the panel therefore does not prove that catalog, metadata, and stream operations all work. Obtain the addon URL from the running application or its documented bot workflow, install it in a compatible client, load the catalog, open the test title, and request playback.
At this stage the generated addon address may contain a local hostname or private IP address. That is suitable only for clients that can reach the local network. Remote clients will need the public HTTPS address created later, and the application may need its advertised addon URL refreshed after that public address is known.
Routine operation, logs, backups, and updates
Treat the deployment as a stateful service. Docker makes application replacement easier, but it does not remove the need for backups, release review, secret rotation, or controlled updates.
Common Docker Compose operations
docker compose ps
docker compose logs -f
docker compose restart
docker compose stop
docker compose start
docker compose down
Use restart for a controlled restart of the declared services. Use stop and start when you want to preserve the existing containers. The down command removes Compose-managed containers and networks, but persistent data behavior depends on the storage declared by the Compose file. Do not add volume-removal options unless you intend to destroy associated data and have a verified backup.
Back up before changing versions
Back up MongoDB using a method compatible with the database deployment in your checked-out Compose file. Also back up config.env and any application-managed configuration that is not stored in MongoDB. Encrypt backups containing secrets and test restoration on an isolated system.
Before an update, note the current Git revision:
git rev-parse HEAD
git statusReview upstream changes and release notes before replacing a working deployment. If the working tree is clean and you have chosen to follow the current branch, the basic Docker update sequence is:
git pull
docker compose build
docker compose up -d
docker compose ps
docker compose logsThis sequence is not a substitute for release-specific migration instructions. If a release changes configuration fields, MongoDB data, volumes, ports, or startup behavior, follow that release's migration requirements. Avoid automatic unattended updates for a service that stores state and private credentials.
Monitor storage growth
Streaming applications can use temporary disk space for downloads, caching, logs, and container layers. Monitor both the MongoDB volume and Docker's general storage. A full disk can cause database failures, incomplete streams, container restarts, and failed updates. If a release includes cache controls, configure them through the current project interface and verify their behavior under your normal workload.
Expose the verified HTTP service with Localtonet
Complete this section only after http://127.0.0.1:8000 or the appropriate LAN address works. With Localtonet, the client on your device establishes an outbound connection to one of our relay servers. The HTTP tunnel then supplies a public HTTPS URL for the Telegram-Stremio service without inbound router port forwarding, firewall changes, VPN setup, or a public IP address.
The Localtonet client must run on the Docker host or another device that can reach the Docker host on port 8000. If it runs directly on the host, the local target can normally use 127.0.0.1 and port 8000. If it runs elsewhere on the LAN, use the Docker host's reachable LAN address rather than 127.0.0.1.
Install and run the Localtonet client
Install our client for the operating system on the device that can reach Telegram-Stremio. Keep the client running while remote access is required.
Authenticate or select the device
Use the device-specific Localtonet token through the supported client workflow, then select that connected device in the dashboard. Never publish or reuse another device's token.
Select an available relay server
Choose a currently available server or region from the Localtonet dashboard. Availability can vary, so this guide does not hardcode a server code.
Create an HTTP tunnel to port 8000
Create an HTTP tunnel and set its local target to the IP address that reaches Telegram-Stremio and local port 8000. Select the supported process type appropriate to your account and deployment.
Start the tunnel
Creating a tunnel does not start it. Press Start and wait until the selected device and tunnel are connected.
Test the assigned public HTTPS address
Open the assigned URL from a network outside the host's LAN. Confirm the expected application response, then update or refresh Telegram-Stremio's advertised addon URL if the installed release requires it.
HTTP tunnels can use a random subdomain, a custom subdomain where supported, or a custom domain. These process types serve the local HTTP content through a public HTTPS address. Custom-domain DNS requirements can change, so check the current dashboard and our HTTP tunnel documentation before changing DNS records. Do not invent CNAME targets or relay addresses.
For the maintained product workflow, see the Localtonet HTTP tunnel documentation. Keep the public URL separate from private Localtonet device tokens and Telegram credentials.
The public address can serve Telegram-Stremio only while the application is healthy, the selected Localtonet client is connected, and the tunnel is running. Creating the tunnel configuration alone does not make it active.
Refresh the advertised addon address
A Stremio addon manifest and its stream URLs must be reachable by the client using the address they advertise. If Telegram-Stremio generated its addon URL while it was using localhost or a private LAN address, remote clients may continue receiving unusable local URLs even though the public panel opens.
Use the installed Telegram-Stremio version's setting for its public or advertised URL, or use its provided refresh action where available. Enter the Localtonet HTTPS origin exactly as assigned, without exposing administrator credentials in the URL. Then obtain a newly generated addon URL and reinstall or refresh the addon in the remote client.
Test from outside the local network
Disable Wi-Fi on a test phone or use another genuinely external connection. Open the public HTTPS address, verify the panel or expected application response, install the refreshed addon URL, load the test catalog, and play the controlled item. This validates DNS, HTTPS reachability, addon URL generation, catalog requests, and streaming as one complete path.
Security checklist for a public media endpoint
Remote access changes the application's exposure boundary. A service previously reachable only from the host or LAN can now receive public internet traffic. Apply authentication and least privilege before sharing the public URL.
Do not assume that an obscure public URL is an authorization mechanism. If Telegram-Stremio supports user tokens, subscriptions, private catalogs, administrator authentication, or other access controls in your installed release, configure them intentionally. Test both an authorized and unauthorized request where practical.
Keep the host operating system, Docker, Telegram-Stremio, and MongoDB updated through controlled maintenance. Review release notes before upgrading and maintain recoverable backups. If a bot token, session string, database password, administrator secret, or Localtonet token is disclosed, revoke or rotate it through the system that issued it. Removing a leaked value from a public post does not make the old credential safe again.
Troubleshooting Telegram-Stremio, MongoDB, and Localtonet
The Docker command cannot contact the daemon
Confirm that Docker is running and that the current user can access it. Run docker version and read the daemon error. On Linux, verify the Docker service and the deployment user's group or socket permissions. Do not make the Docker socket publicly accessible, because control of that socket commonly provides extensive control over the host.
Compose reports missing variables or an invalid configuration
Confirm that config.env exists in the expected repository directory and that it was created from the sample belonging to the same revision. Compare field names without posting their values. Run docker compose config in a private terminal and address the first unresolved value or syntax error.
The application container repeatedly restarts
Run docker compose ps and docker compose logs. Common categories include malformed configuration, failed Telegram authentication, an unreachable MongoDB service, a port collision, insufficient disk space, or an application migration error. The earliest error is usually more useful than later connection failures caused by the original crash.
MongoDB cannot be reached
Determine whether MongoDB is a Compose service or external dependency in your revision. Confirm that its container is running, its persistent storage is writable, and the application uses the documented connection value. Remember that localhost inside the application container refers to that same container. Do not publish MongoDB publicly as a shortcut.
Port 8000 is already in use
Identify the existing listener before changing anything. Stop the unrelated service if it should not be running, or adjust the host-side port mapping using a deliberate local deployment change. If you change the host port, use that actual host port as the Localtonet target. Do not change Telegram-Stremio's internal port based only on an assumed value.
The browser cannot open the local service
Confirm that the application container remains up, that Compose publishes the expected port, and that curl -i http://127.0.0.1:8000 reaches it from the host. If it works on the host but not another LAN device, inspect the binding and host firewall. Localtonet can target loopback when its client runs on the same host, so LAN publication is not required for that arrangement.
The panel works but no catalog entries appear
Verify MongoDB connectivity, channel role assignment, bot administrator access, and the test filename or caption. Use one controlled item with an unambiguous title, year or episode notation, and quality. Inspect logs and any skipped-file area supplied by the current application. Do not test by forwarding a large unsorted library all at once.
The Localtonet URL returns an error
Test the local target from the device running the Localtonet client. If the client runs on the Docker host, confirm 127.0.0.1:8000. If it runs on another device, confirm that the Docker host's LAN address and port are reachable from that device. Then verify that the correct Localtonet device is connected, the tunnel has been started, and the target IP and port match the successful local test.
The public panel opens but Stremio still uses a private address
The application is probably still advertising the URL generated before the tunnel existed. Set or refresh the advertised public URL through the controls available in the installed Telegram-Stremio release. Generate a new addon URL, reinstall or refresh the addon, and inspect whether its requests now use the Localtonet HTTPS origin.
Catalogs load remotely but playback fails
Verify local playback first. Then inspect application logs during a remote playback request. Check whether the generated stream address uses the public HTTPS origin rather than localhost, a private IP, or an old hostname. Also check Telegram authentication, bot or user-session validity, channel access, available disk space, and temporary storage behavior.
The public URL stops working later
Check all three lifecycle layers: Telegram-Stremio and MongoDB must be healthy, the selected Localtonet client must be connected, and the Localtonet tunnel must be running. A Docker restart, host reboot, disconnected client, stopped tunnel, expired application session, or database failure can interrupt the path independently.
Frequently asked questions
Does Telegram-Stremio require MongoDB?
Yes. The project uses MongoDB for persistent application and indexed media records. Inspect the checked-out docker-compose.yaml to determine whether your revision starts MongoDB within the Compose deployment or expects an external MongoDB connection.
Which local port does Telegram-Stremio use?
The upstream repository metadata declares application port 8000. Confirm the actual host-side port mapping in your checked-out Compose file, especially if you have made local deployment changes.
Should I expose MongoDB through Localtonet?
No, not for this workflow. Create an HTTP tunnel only to the Telegram-Stremio FastAPI service. Keep MongoDB on its private Compose network or another restricted network reachable only by authorized systems.
Does Localtonet require router port forwarding?
No. Our client establishes an outbound connection to a Localtonet relay server, so this workflow does not require inbound router port forwarding, firewall changes, VPN setup, or a public IP address.
Can the Localtonet client run on a different device?
Yes, provided that device can reach the Telegram-Stremio host and its published HTTP port. In that arrangement, target the Docker host's reachable LAN IP address and port 8000 rather than 127.0.0.1.
Why does the addon still contain a localhost address?
The addon was probably generated before its public origin was configured. Use the installed Telegram-Stremio release's advertised-URL or refresh control, supply the Localtonet HTTPS origin where required, and regenerate the addon URL.
Does creating a Localtonet tunnel start it automatically?
No. Creating a tunnel stores its configuration. You must press Start, and the selected Localtonet client must remain connected. You can later stop or delete the tunnel when it is no longer needed.
Can I copy configuration values from an older Telegram-Stremio fork?
That is unsafe and may not work. Configuration fields and defaults can change. Use sample_config.env from the exact upstream revision you are deploying, then complete the settings exposed by that version's web panel.
Make your verified Telegram-Stremio service reachable with Localtonet
Once the Docker deployment works locally on port 8000, connect it to a Localtonet HTTP tunnel and use the assigned public HTTPS address for your authorized remote addon clients. Keep the application protected, start the tunnel only when needed, and never expose Telegram, database, or device credentials.
Get Started Free →
