Self-Host PencariMovie with Docker and Stremio

How PencariMovie Server fits into the streaming path

PencariMovie Server is a self-hosted utility and protocol bridge. It connects client applications to Telegram's MTProto API and converts user-authorized Telegram file references into HTTP streams that media players can consume. Its documented streaming behavior includes HTTP range-request support, including HTTP 206 partial responses, which allows compatible players to seek within media rather than downloading an entire file before playback begins.

The server runs on hardware under your control. Docker publishes its web service on port 8088 in the documented default configuration. A browser can open the dashboard at http://127.0.0.1:8088 from the Docker host, while another device on the same network can normally use http://<LAN-IP>:8088 if the host firewall and network permit that connection.

Stremio does not connect to the container through a special Docker protocol. It receives an HTTP manifest URL and then uses the endpoints described by that manifest. This distinction is useful when troubleshooting: Docker must be healthy, the HTTP service must answer, the manifest must be reachable from the Stremio device, and any referenced streaming URL must remain reachable for playback to work.

Prerequisites and deployment decisions

The Docker workflow is appropriate for a computer, server, NAS, or VPS that can run the published Linux container and make port 8088 available to the required clients. Docker Desktop is sufficient on supported desktop systems, while server and NAS deployments generally use Docker Engine. Docker Compose is recommended for this guide because it keeps environment variables, persistent storage, restart behavior, and port mapping in a reproducible configuration.

Before starting, prepare the following:

• A working Docker installation with the docker command available.
• The Docker Compose plugin if you intend to use the recommended Compose configuration.
• Permission to create containers, networks, images, and either a bind-mounted directory or Docker volume.
• Enough local storage for PencariMovie's persistent application data and your expected workload.
• A browser for opening the dashboard at http://127.0.0.1:8088.
• A Stremio client on the Docker host or on a device that can reach the host over the LAN.
• User-authorized Telegram access and media references required by your intended PencariMovie workflow.
• A strong, unique dashboard password and a random 32-character server token before public exposure.
• The Localtonet client on the machine that can reach PencariMovie if remote access is required.

Choose who should reach port 8088

A port mapping such as 8088:8088 publishes the container port through the Docker host. The exact interfaces and firewall reachability depend on the host's Docker and operating-system configuration. That mapping is useful when televisions, phones, or other computers on the LAN need to contact PencariMovie directly.

If only programs on the Docker host and the Localtonet client need access, limiting the published port to loopback can reduce unnecessary LAN exposure. Docker supports a host-address-qualified mapping such as 127.0.0.1:8088:8088. This is a general Docker networking option rather than a PencariMovie-specific requirement. Do not use a loopback-only mapping when direct LAN clients must connect to the server.

Decide between a Docker volume and a bind mount

The project's quick Docker command uses the named volume pencarimovie-data. Its Compose example uses ./storage:/app/storage, which stores persistent files in a visible storage directory beside the Compose file. Both approaches preserve application data outside the disposable container layer.

Install PencariMovie Server with Docker

The fastest documented installation uses the published container image, maps host port 8088 to container port 8088, and creates a named volume for persistent storage. This is useful for confirming that the image starts correctly before creating a longer-lived Compose deployment.

docker run -d \
  --name pencarimovie-server \
  --restart unless-stopped \
  -p 8088:8088 \
  -v pencarimovie-data:/app/storage \
  ghcr.io/aiskendi/pencarimovie-server:latest

The line continuation character above is suitable for common Unix-like shells. In a shell that does not accept backslash continuation, enter the command on one line or adapt only the line formatting for that shell. Do not change the image name, container port, or storage target unless you understand the effect.

Check the container state with:

docker ps --filter name=pencarimovie-server

If it does not remain running, inspect its output:

docker logs pencarimovie-server

The quick command is an effective local smoke test, but it does not explicitly supply custom SERVER_PASSWORD and SERVER_TOKEN values. For a reproducible installation intended for remote access, stop and remove the test container, preserve the named volume if its data is needed, and continue with the Compose configuration below.

docker stop pencarimovie-server
docker rm pencarimovie-server

Removing the container does not by itself remove the separately named pencarimovie-data volume. Do not delete that volume if it contains application state you intend to retain.

Configure Docker Compose, authentication, and persistence

Create a dedicated project directory and place two files inside it: compose.yaml and .env. The Compose definition below follows the project's documented service configuration, including the published image, restart policy, environment file, port mapping, and persistent ./storage bind mount.

services:
  pencarimovie:
    image: ghcr.io/aiskendi/pencarimovie-server:latest
    container_name: pencarimovie-server
    restart: unless-stopped
    ports:
      - "${PORT:-8088}:8088"
    env_file:
      - .env
    volumes:
      - ./storage:/app/storage

Create .env in the same directory. The following example deliberately uses replacement markers rather than working credentials. Replace both security values before launching the service.

PORT=8088
SERVER_PASSWORD=REPLACE_WITH_A_STRONG_UNIQUE_PASSWORD
SERVER_TOKEN=REPLACE_WITH_A_RANDOM_32_CHARACTER_TOKEN
DEBUG=0

Understand the security variables

SERVER_PASSWORD is documented as the password for dashboard access on public VPS addresses and tunnel-based public access. The project's documentation describes LAN access as password-free, so the existence of a password should not be treated as a general LAN access-control boundary. Control LAN reachability separately through the Docker port binding, host firewall, and network design.

SERVER_TOKEN is the static token used in public remote addon URLs. Instead of publishing the unprotected path /manifest.json, the documented remote format places the token in the path as /<token>/manifest.json. Anyone who receives that complete URL may also receive the token, so treat manifest URLs as sensitive configuration.

Optional performance and network variables

PencariMovie exposes additional environment variables, but the defaults should normally remain unchanged until measurements show a reason to tune them. The documented initial FrankenPHP thread count is 8, the maximum thread ceiling is 16, and the default parallel download chunk count is 4. Increasing concurrency can also increase CPU, memory, network, and upstream demand.

External session storage can be configured through REDIS_URI, MYSQL_URI, or the documented PostgreSQL connection option where supported by the current project release. Those services are optional and are not required for this basic single-container workflow. Do not copy placeholder database credentials into a production configuration.

Start the Compose deployment from the directory containing both files:

docker compose up -d

Then review its state and initial logs:

docker compose ps
docker compose logs --tail=100 pencarimovie

The project also documents optional variables such as BOT_TOKEN and TUNNEL_TOKEN. They are not required for the Docker and Localtonet workflow in this article. In particular, Localtonet runs as a separate access layer, so do not place a Localtonet device auth token into PencariMovie's TUNNEL_TOKEN variable. These are unrelated credentials for different systems.

Verify the dashboard, manifest, and streaming behavior locally

Finish local verification before creating any public tunnel. This keeps Docker, application, client, and networking problems separate. If the dashboard does not work locally, a tunnel cannot repair the underlying application.

1. Confirm the container remains healthy enough to serve requests

Run docker compose ps and confirm the container is running rather than repeatedly restarting. If it restarts, use docker compose logs pencarimovie and look for port conflicts, storage permission failures, invalid environment values, or application startup errors.

2. Open the dashboard from the Docker host

Visit:

http://127.0.0.1:8088

If PORT was changed in .env, use that host port instead. The container side remains port 8088 in the supplied Compose configuration.

A command-line HTTP request can provide additional connection detail:

curl -v http://127.0.0.1:8088/

The exact status and authentication behavior can vary with the current release and access context. The key local checks are that a TCP connection succeeds, an HTTP response arrives, and the container does not terminate while serving the request.

3. Retrieve the standard manifest

Request the documented local manifest:

curl http://127.0.0.1:8088/manifest.json

The response should be a Stremio-compatible JSON manifest rather than a Docker gateway error or connection failure. Avoid publishing captured manifest output because it may reveal internal addresses or application details relevant to your deployment.

4. Test from a second LAN device

Determine the Docker host's LAN IPv4 address and open:

http://<LAN-IP>:8088/
http://<LAN-IP>:8088/manifest.json

Replace <LAN-IP> with the actual address of the Docker host. Do not use 127.0.0.1 on a television, phone, or separate computer because loopback always refers to the device making the request.

If local access works but LAN access does not, check whether Docker is bound only to 127.0.0.1, whether the host firewall allows the selected port, whether the devices are on networks permitted to communicate, and whether Wi-Fi client isolation is enabled.

5. Complete the application-specific setup in the dashboard

Follow the prompts displayed by the installed PencariMovie release to complete its Telegram and client configuration. The available setup screens can change between releases, and the supplied project evidence does not establish a stable sequence of dashboard fields that can be reproduced safely here. Do not enter Telegram credentials, bot tokens, session data, or server tokens into an untrusted page.

6. Verify playback and seeking

Once authorized media is available through the application, start a stream in a compatible client and seek to a later position. Successful seeking exercises the project's range-request support. For a deeper diagnostic, copy a temporary stream URL from your own session and request a small byte range:

curl -i -H "Range: bytes=0-1023" "YOUR_TEMPORARY_STREAM_URL"

A range-aware endpoint can respond with HTTP 206 Partial Content. Stream URLs and authorization data can be sensitive, so never publish the real URL in logs, screenshots, issue reports, or shell history shared with other people.

Configure the PencariMovie manifest in Stremio

The correct manifest URL depends on where Stremio runs. Select an address reachable from the Stremio device, not merely an address that works in a browser on the server.

In Stremio, use the client's addon installation mechanism to add the full manifest URL. The exact screen name and placement can differ across Stremio versions and platforms, so this guide does not invent a fixed menu sequence. Confirm that the client accepts the manifest and displays the resulting addon before testing media playback.

A manifest loading successfully does not prove that every stream is reachable. Start an authorized item, allow playback to begin, and test seeking. If the addon appears but playback fails, inspect PencariMovie's logs while reproducing the problem:

docker compose logs --follow pencarimovie

If generated LAN URLs contain the wrong local address on a multi-interface host, PencariMovie documents LAN_IP as an override. Add the correct host LAN IPv4 address to .env, recreate the container, and retrieve a fresh manifest:

LAN_IP=192.168.1.100

The address above is only an example from the private address space. Replace it with the Docker host's real LAN address. Apply the changed environment:

docker compose up -d

Expose the verified service through a Localtonet HTTP tunnel

Remote access should be treated as a separate stage. PencariMovie supplies the local HTTP service and application-level password and token behavior. With Localtonet, our client establishes an outbound connection to a relay server and provides a public address for that local service. This avoids inbound router port forwarding, firewall rule changes for an inbound public port, VPN setup, and the requirement for a public IP address.

Use an HTTP tunnel because PencariMovie exposes an HTTP dashboard, manifest, and streaming endpoints. Do not configure a raw TCP tunnel unless there is a separate, verified requirement for raw TCP forwarding. HTTP process types can use a random subdomain, a custom subdomain where supported, or a custom domain, and each serves the same target content through a public HTTPS address.

For current dashboard details, consult our Localtonet HTTP tunnel documentation. Exact regions, hostname options, dashboard labels, and plan availability can change, so this article does not hardcode values that must be selected from your account.

Construct the remote manifest carefully

If Localtonet assigns a public address represented here as https://<PUBLIC-HOST>, the documented protected remote addon pattern is:

https://<PUBLIC-HOST>/<SERVER_TOKEN>/manifest.json

Replace both placeholders locally. Do not paste the completed URL into a public message because the path contains the server token. Test it from an external network, confirm that the response is the expected JSON manifest, and then enter the same protected URL into the remote Stremio client.

Keep the public hostname stable if a client is expected to retain the addon configuration. A new random public hostname would require updating the manifest URL in that client. Custom-domain DNS setup is not included here because exact records and verification requirements must be checked against the current Localtonet documentation rather than guessed.

Routine operation, backups, updates, and shutdown

A self-hosted streaming service needs basic operational care even when its container starts automatically. Keep the Compose file and non-secret configuration documented, protect the completed .env file, and back up persistent storage according to the recovery needs of your deployment.

View status and logs

docker compose ps
docker compose logs --tail=100 pencarimovie
docker compose logs --follow pencarimovie

Follow mode continues printing new events until interrupted. Debug logging should remain disabled during normal use unless detailed diagnosis is required. If you temporarily set DEBUG=1 or DEBUG=true, the project documents verbose output in storage/debug.log. Review that file for sensitive account, media, path, or request information before sharing any excerpt.

Restart or stop the service

docker compose restart pencarimovie
docker compose stop
docker compose start

The unless-stopped restart policy allows Docker to restart the container after ordinary daemon or host restarts, except when an administrator has explicitly stopped it. This does not replace monitoring, and it does not guarantee that the application is ready to serve a valid manifest.

Update the container image

The configuration uses the moving latest image tag documented by the project. A pull can therefore introduce a newer application release. Back up persistent data, review the project's release information, and schedule a maintenance window before updating.

docker compose pull
docker compose up -d
docker compose logs --tail=100 pencarimovie

After an update, repeat the local dashboard, manifest, playback, and seeking tests. Then verify the Localtonet public manifest separately. The available evidence confirms the published latest image but does not establish that every application release has a matching immutable container tag, so this guide does not invent a version-specific image name.

Back up persistent data

With the supplied Compose configuration, persistent data is in the project's storage directory. Stop the service or use a backup method that provides an application-consistent copy, then protect the backup according to the sensitivity of its contents. The exact files needed for a complete application-level restore can evolve with PencariMovie releases, so validate restoration in a separate test deployment rather than assuming that an untested file copy is sufficient.

Stop remote access independently

Stopping the Localtonet tunnel removes the public route but does not stop PencariMovie on the LAN. Stopping PencariMovie leaves the tunnel configuration present but without a working local target. For planned maintenance, stop the tunnel first, maintain and verify the local service, and start the tunnel again only after local checks pass.

Troubleshooting common Docker, manifest, and tunnel problems

Confirm which layer is failing

Test the same resource in a strict order: first through 127.0.0.1 on the host, then through the LAN address, and finally through the Localtonet public address. A failure at the first stage belongs to Docker or PencariMovie. A failure only on the LAN belongs to host or network reachability. A failure only through the public URL belongs to tunnel state, tunnel targeting, public-path construction, or application behavior for remote requests.

Confirm that changed environment variables were applied

Editing .env does not modify the environment inside an already-created container. Run:

docker compose up -d

Compose will reconcile the service and recreate it when required. Recheck the dashboard and manifest afterward. Never print the complete environment publicly because it contains the dashboard password and server token.

Avoid enabling several remote-access systems at once

PencariMovie documents its own optional tunnel token variable, while this guide uses Localtonet as a separate remote-access layer. Running multiple connectors can create several public routes, complicate troubleshooting, and unintentionally leave an older route active. Configure only the access method you intend to operate, and inventory every public hostname before declaring the service private again.

Frequently asked questions