Securely Access Tube Archivist with Localtonet

Understand the connection and authentication boundaries

Tube Archivist is a self-hosted YouTube media server. Its documented core functions include subscribing to channels, downloading videos, indexing metadata, searching an archive, playing videos, and tracking viewed and unviewed items. The browser interface is the part remote users need to reach. They do not need direct connections to the databases, container runtime, or storage administration tools underneath it.

A private LAN address is not normally routable from the internet. Conventional publishing may require router port forwarding, a public IP address, and a reverse proxy. Carrier-grade NAT can prevent that approach even when you control your router. With Localtonet, our client establishes an outbound connection to a relay server, and an HTTP tunnel supplies a public HTTPS address pointing to your chosen local web target.

The selected client must remain connected, the tunnel must be running, and the application must remain reachable from the client. No inbound router rule, public IP address, or VPN setup is required for this workflow. Existing organizational network policies still apply; use the tunnel only where remote publication is authorized.

These distinctions explain why a tunnel can successfully deliver a login page while login submission, logout, or media playback still fails. Browser origin checks, cookies, generated URLs, and authorization are separate from transport. Do not disable those protections to make a connectivity test pass.

Scope, prerequisites, and version boundaries

This guide assumes a working Tube Archivist deployment managed with Docker Compose v2 on a Linux host, plus shell access to that host. It is not a fresh-installation recipe. The commands below use standard Docker and Compose operations; adapt the project directory, service name, Compose file names, and port to the installation you already run. Keep the same project name, override files, and environment-file arguments used by your normal deployment.

The deployment path described here is an existing Compose project with a published web port and our client running directly on the Docker host. A client on a separate trusted LAN machine also works if it can reach that port. A containerized Localtonet client has its own network namespace, so its loopback address is not the Docker host's loopback address.

Before starting, collect the application version, image reference and image ID, Compose service name, active web-port mapping, current TA_HOST value, and all persistent storage locations. Record a working local browser URL and the addresses you intend to preserve after the change. Also prepare a separate external connection, such as mobile data, for the final test.

Do not resize the machine or change dependencies solely to add a tunnel. Memory, CPU, Elasticsearch compatibility, required variables, password-file conventions, update intervals, and recommended download selectors need confirmation against the documentation for your actual release. The supplied repository extract does not substantiate precise values for those items. The Tube Archivist repository and project documentation are the appropriate places to resolve those version-specific prerequisites.

You also need a Localtonet account, a trusted client device, and a device-specific token. Keep that token private. It is not a Tube Archivist login password, and the tunnel does not need your application or database credentials to select its local target.

Inspect the running deployment before making changes

Identify the service and published port

Run these commands from the existing Compose project directory. If your deployment uses options such as -f, --env-file, or -p, include those same options in every Compose command in this guide. Running against a different project can create a second stack instead of updating the existing one.

docker compose version
docker compose config --services
docker compose ps
docker compose images

# Replace this with the actual web service name.
WEB_SERVICE=tubearchivist
CID="$(docker compose ps -q "$WEB_SERVICE")"

# Stop here if CID is empty.
docker port "$CID"
docker inspect --format '{{.Config.Image}} {{.Image}}' "$CID"
docker inspect --format '{{json .State}}' "$CID"

docker port shows published container-port mappings. For example, a mapping ending in 127.0.0.1:8000 means a host-local client can contact port 8000 on loopback. A mapping on 0.0.0.0 listens on all host IPv4 interfaces, subject to network controls. Do not assume that the first listed port is the user-facing application port. Confirm it against the working browser URL and your Compose configuration.

For a separate client device, use the server's reachable private address instead of 127.0.0.1. If the application is bound only to loopback, that separate device cannot reach it directly. Running our client on the Docker host may avoid widening the application's LAN exposure.

Inspect only the configuration you need

# Show only TA_HOST, not the complete environment.
docker inspect --format '{{range .Config.Env}}{{println .}}{{end}}' "$CID" \
  | grep '^TA_HOST='

# Review recent application output locally.
docker compose logs --since=10m --tail=200 "$WEB_SERVICE"

# Inventory persistent mounts before planning backups.
docker inspect --format '{{range .Mounts}}{{println .Type .Source .Destination}}{{end}}' "$CID"

The active container environment and the configuration files on disk can differ. An edited .env file is not proof that the running container uses its new value. Conversely, an entry in .env only affects the container when the Compose definition actually references or loads it.

Logs and mount paths can reveal usernames, private addresses, video titles, query strings, and other sensitive details. Review them locally and redact before sharing. Avoid posting full docker inspect or rendered Compose output because it can include credentials.

Establish a local baseline

# Example only: replace with the verified local web endpoint.
LOCAL_URL='http://127.0.0.1:8000'
curl --silent --show-error --max-time 15 \
  --output /dev/null --write-out 'HTTP %{http_code}\n' "$LOCAL_URL/"

A returned status proves an HTTP response, not full application health. Open the same endpoint in a browser from the intended client environment. Sign in, search for an archived item, open a video, check thumbnails, play and seek through representative media, then sign out. Record any existing redirects or failures before adding remote access. If local behavior is already broken, fix it first.

Configure the Localtonet HTTP tunnel

Our platform uses a device-specific token to identify the client that will carry traffic. Install and run the client on the device that passed the reachability test, authenticate that device, then select its token in the tunnel configuration. Selecting a token in the dashboard does not install or authenticate a client process on the machine.

The supplied product context establishes this workflow but does not include current OS-specific installer commands, executable paths, or authentication prompts. Use the installation path presented by our current Localtonet documentation for your OS and architecture. Complete its device-token authentication step locally and verify that the intended device appears connected before proceeding. Do not substitute an unverified shell installer or guessed CLI flag.

The following sequence preserves the existing HTTP workflow. The current HTTP tunnel documentation remains the UI reference; no live revalidation of its screen labels or numbered steps is claimed here.

If the public address is assigned during this process, record it and stop the tunnel while changing the application configuration. Do not leave an unverified archive exposed while troubleshooting. Check that the same public address remains assigned before each retest; an address change may require another application configuration change.

Reconcile the public origin with TA_HOST

The local target and the browser-facing origin serve different purposes. Suppose our client connects to http://127.0.0.1:8000, while users open an assigned HTTPS hostname. The local port 8000 belongs to the client-to-application connection. It must not be copied into the public URL unless that public endpoint actually uses it.

An origin consists of scheme, hostname, and effective port. For an ordinary HTTPS URL without an explicit port, the effective port is 443. https://archive.example.invalid:443 below is a deliberately nonworking example, not an assigned Localtonet domain. Replace it with the origin of your actual endpoint.

What the release evidence establishes

The Tube Archivist v0.5.11 release notes report unexpected logout redirects for some users and direct them to specify protocol and port in TA_HOST exactly as documented. That is release-specific evidence. It does not establish that every newer release has the same validation behavior, nor does it define a supported syntax for several local and public hosts.

For an installation whose version-specific documentation confirms a single full-origin TA_HOST value, the intended public-origin change has this form. Edit the existing entry in the web service's environment configuration rather than adding a second conflicting definition:

# Fragment only, not a complete Compose deployment.
# Apply only after confirming this format for your installed release.
environment:
  TA_HOST: "https://archive.example.invalid:443"

If your Compose file instead contains TA_HOST: ${TA_HOST}, edit the existing TA_HOST entry in the interpolation environment used by that project. If the application environment comes from an env_file, edit that file. Keep one authoritative definition and check for overrides. Do not change login credentials, dependency versions, or database configuration as part of this host-only change.

Preserve local access deliberately

Do not append a LAN URL using guessed commas, spaces, or a JSON list. Supported multi-host syntax is not established by the available evidence. If direct LAN browser access must continue, verify the installed release's supported host handling before applying the change. Test each intended local hostname separately afterward.

Using the same public HTTPS address from both home and remote browsers can avoid needing two browser origins, provided it works from both networks. However, that is still tunnel-dependent access, not independent offline LAN access. If direct local access fails after the change and is a requirement, restore the previous configuration and keep the tunnel stopped until a documented dual-access arrangement is available.

Similarly, this guide does not prescribe Host rewriting, forwarded-header trust, authentication-proxy variables, or CSRF overrides. Their required behavior is not established here. If an existing reverse proxy is part of your deployment, compare its configuration with your release's proxy instructions. Do not trust arbitrary identity headers or assume the tunnel supplies application authentication.

Apply the change through container recreation

First save the exact configuration files you will edit. The example assumes compose.yaml; substitute your real filename and also copy every relevant override or environment file. Backups may contain secrets, so store them with restricted access.

umask 077
BACKUP_DIR="$HOME/ta-config-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$BACKUP_DIR"
cp -p compose.yaml "$BACKUP_DIR/"
# If used by this project, also copy .env and other relevant files.
test ! -f .env || cp -p .env "$BACKUP_DIR/"

# Edit the existing TA_HOST definition, then validate.
docker compose config --quiet

# Recreate only the web service for this host-only change.
docker compose up -d --no-deps --force-recreate "$WEB_SERVICE"
docker compose ps
docker compose logs --since=5m --tail=200 "$WEB_SERVICE"

# Container recreation changes the container ID.
CID="$(docker compose ps -q "$WEB_SERVICE")"
docker inspect --format '{{range .Config.Env}}{{println .}}{{end}}' "$CID" \
  | grep '^TA_HOST='

Stop if validation fails. A plain docker compose restart does not load changed container environment values. Recreation does. Confirm the active TA_HOST, web-port mapping, and startup logs before restarting the tunnel. This procedure assumes dependencies are already healthy and only the web configuration changed; it is not a database upgrade procedure.

Verify public and intended local access

Use a fresh browser profile on an external network. A private window helps separate sessions, but close all private windows before repeating a logged-out test because they may share the same temporary cookie store. Keep browser developer tools open on the Network panel and preserve redirects during the test.

Check more than the login page

While authenticated, identify actual application, API, thumbnail, and media request paths in browser developer tools. Then request representative protected paths without cookies or authorization headers. Do not invent route names or assume that protecting the home page protects every media URL.

# Replace both values with your actual endpoint and an observed route.
PUBLIC_URL='https://archive.example.invalid'
CHECK_PATH='/replace-with-an-observed-protected-path'

# No cookie jar, Authorization header, or redirect following.
curl --silent --show-error --max-time 15 \
  --range 0-1023 --output /dev/null \
  --write-out 'HTTP %{http_code}; type %{content_type}; redirect %{redirect_url}\n' \
  "$PUBLIC_URL$CHECK_PATH"

A range request can limit a media test, although a server may ignore it. Use the timeout and avoid downloading a large archive file unnecessarily. A redirect to login or a documented unauthorized response can be appropriate. A 200 might be a login page rather than protected content, so inspect the response type and browser behavior. A 206 containing private media bytes without authorization is a serious finding.

Public scripts and stylesheets may legitimately be accessible without login. Judge API metadata, thumbnails, and media according to your intended privacy policy and the application's documented behavior. Signed URLs, if present in your deployment, can themselves grant access; do not share them or mistake them for ordinary anonymous paths.

After successful tests, repeat them after a controlled application restart and a separate client restart. Confirm the client reconnects and the tunnel is running rather than assuming startup persistence. Record the tested application image, Localtonet client version, public origin, local target, and test date in your private operations notes. That creates a tested baseline for your deployment without treating one result as a universal compatibility guarantee.

Keep the exposed surface small

Keep Tube Archivist authentication enabled, use strong unique credentials, and restrict account distribution. Publish only content you are authorized to make remotely accessible. Do not share an administrative account when a less-privileged account supported by your installation is sufficient.

Elasticsearch, Redis, Docker APIs, SSH, container dashboards, and storage management should remain private. The HTTP tunnel target should be the browser-facing application listener, not an internal backend port. Review existing host-published ports as well: choosing a narrow tunnel does not repair unrelated services already exposed on the host.

Keep device tokens, application credentials, database passwords, and backups protected independently. Secret-file support must be checked per application variable and version; do not assume that adding _FILE to any environment variable works. Do not leave debug output enabled on an internet-facing application. Stop temporary tunnels when access is no longer needed, and delete configurations you no longer intend to reuse.

Operate, back up, update, and recover safely

Routine status and logs

Check application status and recent logs before investigating the tunnel. An “Up” container is not proof that its dependencies, authentication, search index, or media storage are healthy.

docker compose ps
docker compose logs --since=15m --tail=200 "$WEB_SERVICE"
docker compose images

Separately check the selected Localtonet device and tunnel state in the dashboard. If the local target changes, test its replacement from the client before updating the tunnel. Keep one change per test cycle where possible.

Configuration rollback

For the host-only change above, stop the tunnel, restore the saved configuration files, validate, and recreate the web service. Restore every file you changed, not just compose.yaml.

# BACKUP_DIR must point to the saved, known-good configuration.
cp -p "$BACKUP_DIR/compose.yaml" ./compose.yaml
# Restore .env or overrides only if they were changed and backed up.
docker compose config --quiet
docker compose up -d --no-deps --force-recreate "$WEB_SERVICE"
docker compose ps
docker compose logs --since=5m --tail=200 "$WEB_SERVICE"

Retest the old local URL before restarting remote access. Do not delete volumes to fix a host-validation error. Configuration rollback is distinct from recovery after a release has migrated stored data.

Back up data before updates

Configuration copies are not archive backups. Inventory persistent mounts for every service, including media storage, application state, and database data. Preserve your Compose files, environment files, secret files, ownership requirements, image references, and documented application backup outputs together with the recovery instructions.

Use the installed release's supported application and database backup procedures. Do not assume a filesystem copy of a running database is consistent. If your backup method requires an offline copy, schedule downtime, stop the tunnel, stop writers, and follow the database's requirements before copying or snapshotting storage. A full-stack stop can be performed from the existing project:

# Planned downtime only, after confirming the backup procedure.
docker compose stop

# Perform the verified backup or storage snapshot here.
# This guide does not invent a database backup command.

docker compose up -d
docker compose ps

Store backups outside the primary failure domain and protect them as sensitive data. Test restoration into an isolated environment with no public tunnel. Confirm that the restored application can authenticate, search, locate media, and play files. A backup that has never been restored is an unproven recovery plan.

Upgrade separately from tunnel configuration

Read the release notes for the installed and target versions, including intervening migrations. Confirm the dependency image versions and environment changes required by that upgrade. No universal Elasticsearch version, monthly update requirement, or supported version-skipping window is established by the supplied evidence.

After saving a recoverable backup and editing the project to the intended compatible image references, a normal Compose update uses:

docker compose config --quiet
docker compose pull
docker compose up -d
docker compose ps
docker compose logs --since=10m --tail=200

These commands pull and recreate the services defined by your configuration; they do not determine whether an upgrade is supported. Do not run them against floating image tags without understanding what will change. Preserve old image references and backups, but do not assume an older image can safely read data migrated by a newer release. Failed migrations may require restoring the matching pre-upgrade data as well as configuration.

Playback and capacity planning

Remote playback depends on source-network upload capacity, media bitrate, concurrent viewers, browser codec support, and device performance. A tunnel provides a route; it does not create upstream capacity. Compare the same file in the same browser locally and remotely before changing the network configuration.

The available evidence does not verify Tube Archivist's current default download selector or a universal browser-compatible format string. Check the download-format guidance for your release before changing future downloads. Changing a selector does not retroactively convert existing media, and container extension alone does not establish codec compatibility.

Diagnose observed responses, not assumptions

Start inside and work outward: container state, local listener, client reachability, connected device, running tunnel, then browser requests. Record the time of one failed request and compare it with redacted application logs. Change one layer at a time.

Status codes alone are not diagnoses. Preserve the meaningful error text and redirect destination while redacting credentials, cookies, authorization headers, signed URLs, and personal content. Browser HAR exports often contain secrets; do not upload one without reviewing it. Never “fix” an origin or cookie failure by disabling authentication or certificate validation.

Frequently asked questions