Install DOCSight with Docker for Internet Monitoring

What DOCSight does and where it fits

DOCSight is not simply an uptime page or a general-purpose charting dashboard. It is a self-hosted evidence system for investigating recurring internet connection problems. It brings signal history, speed measurements, latency observations, packet loss, modem events, incident notes, and report generation into one workflow. That combination is useful when a problem is intermittent and a single speed test or modem screenshot does not show the broader pattern.

The application is particularly focused on DOCSIS cable connections. With a supported cable modem, DOCSight can retain observations such as signal power, signal-to-noise measurements, channel information, and modulation data. It can then place those observations alongside speed, latency, packet-loss, outage, and incident information. This helps reveal whether several symptoms occurred during the same time window.

DOCSight also includes a Generic Router mode for connections or routers that do not provide supported DOCSIS signal data. That mode can still support workflows involving speed tests, latency monitoring, notes, and reports, but it does not manufacture unavailable cable signal measurements. If DOCSIS analysis is your primary reason for installing the application, confirm that your current modem family is supported before relying on it for long-term collection.

Choose real monitoring or demo mode

The project documents two straightforward container launches. The persistent deployment is intended for connecting your own supported modem or selecting Generic Router mode. It gives the container a restart policy and stores configuration and history in a named Docker volume. The demo deployment generates synthetic data and is intended for evaluating the interface without connecting a router.

Prerequisites and deployment decisions

The installation command is short, but a reliable monitoring deployment needs several decisions before the container starts. Complete these checks first so that a networking, storage, or port conflict does not look like a DOCSight application problem.

A running Docker engine

You need a machine with Docker installed and its engine running. The machine must be able to download the image from GitHub Container Registry at ghcr.io. On Windows 10 or Windows 11, the project identifies Docker Desktop as the normal supported path for continuous monitoring. An unsigned portable Windows Desktop Preview also exists, but the project describes that as a tryout build rather than the normal always-on collection path.

This guide deliberately follows the documented Docker path. A native Python installation has additional requirements, including compiled ICMP and traceroute helpers for complete probing behavior. Those native details are not needed when following the container workflow here.

Confirm that Docker responds before proceeding:

docker version

A successful response should show that the Docker client can communicate with the engine. If only client information appears followed by an engine connection error, start or repair the Docker service before installing DOCSight.

A stable host for continuous collection

Choose a host that can remain powered on when you want measurements collected. A laptop that sleeps, changes networks, or leaves the premises will create gaps. A home server, NAS with a supported container environment, or another continuously running Docker host is generally a better operational fit.

The host must also be able to reach the modem or router that DOCSight will monitor. Remote browser access to the dashboard does not fix local reachability between the container host and that network device. If client isolation, VLAN rules, guest Wi-Fi, or host firewall rules prevent access, complete monitoring setup may fail even while the web dashboard itself opens normally.

TCP port 8765 must be available

The documented command publishes container port 8765 as host port 8765. Another process or container cannot already be using the same host port. You can review currently running containers and their published ports with:

docker ps

If port 8765 is occupied, do not stop an unknown service blindly. Identify the owner and decide whether to move that service, remove an obsolete container, or deliberately choose another host-side port. The project’s documented endpoint and the instructions in this article use port 8765, so any intentional change must also be reflected in your browser URL and Localtonet local target.

Persistent storage

For real monitoring, the official command mounts the named Docker volume docsight_data at /data inside the container. DOCSight stores its configuration and history there. This separation is important because containers are replaceable, while monitoring history should survive normal container recreation.

Treat that volume as valuable data. Include it in your normal local backup plan and test the restoration process appropriate to your Docker host. The evidence provided for this guide does not establish one universal backup command for every operating system, Docker installation, NAS, or storage driver, so we do not present an unverified copy-and-restore recipe.

Modem or router selection

For full DOCSIS monitoring, use a modem family supported by the current DOCSight release. Hardware support changes as drivers are added or corrected, so use the project’s current supported-hardware information rather than assuming that a similar model or firmware exposes the same interface.

If your connection is not DOCSIS, or your router cannot supply supported DOCSIS information, select Generic Router in the setup wizard. This preserves the useful non-DOCSIS portions of the workflow without pretending that cable signal data exists.

Install DOCSight with Docker

The following sequence installs the persistent deployment documented by the DOCSight project. Run the command from a terminal that can communicate with your Docker engine. Do not add modem credentials, account secrets, Localtonet tokens, or other private values to the command.

Run the persistent deployment command:

docker run -d \
  --name docsight \
  --restart unless-stopped \
  -p 8765:8765 \
  -v docsight_data:/data \
  ghcr.io/itsdnns/docsight:latest

Each option has a specific operational role:

• -d runs the container in the background.
• --name docsight gives it the predictable name used by later status, log, and diagnostic commands.
• --restart unless-stopped allows Docker to restart the container unless an operator intentionally stops it.
• -p 8765:8765 maps host TCP port 8765 to the application’s container port 8765.
• -v docsight_data:/data stores configuration and history in the named docsight_data volume.
• ghcr.io/itsdnns/docsight:latest selects the current image associated with the mutable latest tag at pull time.

Optional: try the synthetic demo first

If you want to inspect DOCSight before connecting real equipment, start the documented demo container instead:

docker run -d --name docsight-demo -p 8765:8765 -e DEMO_MODE=true ghcr.io/itsdnns/docsight:latest

Demo mode produces synthetic DOCSIS history inside the real product interface. It does not require a router and should not be interpreted as measurements from your connection. The documented demo command and persistent command both publish host port 8765, so they cannot run concurrently on the same host with those unchanged mappings.

To stop and remove the demo before creating the persistent deployment:

docker stop docsight-demo
docker rm docsight-demo

Then run the persistent command. Removing the demo container does not remove the persistent docsight_data volume because the documented demo command does not create or mount that volume.

Complete the DOCSight setup wizard

Open http://localhost:8765 after the container starts. The setup wizard is where you choose the type of network device DOCSight will monitor. The exact fields depend on the selected modem or router driver and may change between application releases, so enter only values requested by the wizard you are actually running.

For a supported cable modem

Select the matching supported modem family. Do not choose a model only because its product name looks similar. Firmware families can expose different local APIs, authentication behavior, and status formats. The current DOCSight project information is the correct place to confirm compatibility for a particular model and firmware.

The Docker host must be able to reach the modem’s local management interface. If the wizard cannot communicate with the modem, test reachability from the host and review segmentation between the host, container network, and modem. Avoid opening the modem management interface to the public internet as a troubleshooting shortcut.

For fiber, DSL, satellite, or an unsupported device

Select Generic Router. This mode omits DOCSIS signal collection but can still provide applicable speed testing, latency monitoring, incident notes, and reporting. It is better to retain accurate partial evidence than to configure an incorrect cable driver and misinterpret missing or invalid measurements.

Authentication and optional integrations

The project lists optional authentication, API tokens, notifications, Home Assistant, BQM, Smokeping, speed-test integrations, backup and restore, and browser or app push capabilities among its broader features. These are not prerequisites for opening the first dashboard. Configure only the integrations you need, and review what information each one sends to another service.

In particular, self-hosting does not automatically mean that every optional integration remains local. DOCSight’s core history and reports stay on your hardware, while integrations communicate with services you choose to configure. Keep tokens and credentials out of shell history, screenshots, support posts, and tunnel configuration descriptions.

Verify the installation locally

Do not create a public tunnel until DOCSight works locally. Local verification separates application or Docker failures from tunnel configuration problems and gives you a clear baseline for troubleshooting.

Check the container state

docker ps --filter name=docsight

Look for the docsight container and confirm that it is running. Also inspect the displayed port mapping. If the container is absent, include stopped containers in the search:

docker ps -a --filter name=docsight

A stopped container usually requires log inspection rather than repeatedly issuing the original docker run command. Running that command again with the same name will produce a name-conflict error while the existing container remains present.

Open the dashboard in a browser

From the Docker host, navigate to:

http://localhost:8765

You should receive the DOCSight interface or its setup wizard. From another device on the same LAN, localhost refers to that other device, not the Docker host. Use the Docker host’s LAN address only if the host firewall and your network design permit local access.

Test the HTTP endpoint from the terminal

If a browser error is ambiguous and your host has curl, make an ordinary HTTP request:

curl -sS -o /dev/null -w '%{http_code}\n' http://localhost:8765/

An HTTP response confirms that something is answering on the expected endpoint. The exact status code can depend on the application state and navigation behavior, so combine this result with the browser and container logs rather than treating one code as a complete health assessment.

Confirm persistent storage exists

docker volume inspect docsight_data

Docker should return metadata for the named volume. Do not edit files inside the volume manually unless the DOCSight documentation for your installed release explicitly directs you to do so. The purpose of this check is to confirm that Docker created the expected persistent storage.

Confirm real observations over time

A dashboard loading successfully proves that the web application is available, but it does not prove that modem polling, latency checks, speed measurements, or optional integrations are functioning. After completing the wizard, allow the application to collect data and review whether expected observations appear with plausible timestamps.

Missing data should be treated as unavailable, not as proof of a perfect connection. Recent DOCSight releases explicitly avoid interpreting absent measurements as healthy or perfect results in several analysis areas. Check the selected device driver, network reachability, logs, and diagnostic output if expected measurements remain absent.

Routine operation, diagnostics, and updates

Once monitoring begins, preserve the distinction between the replaceable application container and the persistent data volume. Most routine container actions should affect the docsight container without deleting docsight_data.

View logs

docker logs docsight

To continue following new log output:

docker logs -f docsight

Leave follow mode with Ctrl+C. This stops the local log viewer, not the container.

Stop, start, or restart DOCSight

docker stop docsight
docker start docsight
docker restart docsight

Use only the operation you need. An intentional stop remains significant because the configured restart policy is unless-stopped. Confirm the container state after host maintenance rather than assuming that collection resumed.

Run the built-in passive doctor

DOCSight documents a diagnostic module that checks the local runtime, configuration, storage, database, secret-file presence, and optional integration configuration. Its default checks do not contact third-party services.

docker exec docsight python -m app.doctor

For machine-readable output saved on the Docker host:

docker exec docsight python -m app.doctor --json > docsight-doctor.json

Review diagnostic output before sharing it. Although the doctor is intended for local troubleshooting, apply the same care you would use with any environment report and make sure it does not disclose details you do not intend to publish.

Approach updates conservatively

A container created from latest does not update merely because the registry tag later changes. Updating normally involves reviewing the target release, obtaining its image, and recreating the application container while preserving the existing volume. Exact update and rollback procedures can vary by Docker Run, Compose, Portainer, NAS, and other deployment environments.

Before updating, identify the currently deployed image, read compatibility notes for the target release, back up persistent data using a tested method appropriate to your host, and plan a rollback. Pinning a reviewed release tag improves reproducibility. Do not delete docsight_data as part of routine container replacement.

Expose the verified dashboard with Localtonet

After local verification and authentication setup, you can use a Localtonet HTTP tunnel to reach DOCSight from outside the home network. Our client establishes an outbound connection to a Localtonet relay server, so this workflow does not require inbound router port forwarding, firewall changes for an inbound public listener, VPN setup, or a public IP address.

The local target is the existing DOCSight HTTP service. If our client runs on the same machine as Docker, the target can use the local service address and port. If our client runs on another device, that device must already be able to reach the Docker host over the LAN. Localtonet cannot repair local routing, firewall, VLAN, or service-binding problems between the client device and DOCSight.

For the current dashboard workflow, see our Localtonet HTTP tunnel documentation. Exact dashboard fields, relay choices, domain requirements, and availability can change by deployment or plan, so use the values currently shown in your account rather than relying on copied examples.

Secure a remotely accessible monitoring dashboard

Publishing a private dashboard changes its risk profile. DOCSight may hold information about outages, router behavior, connection timing, report content, notes, and optional integrations. Use layered controls rather than treating an unguessable URL as authentication.

Enable application authentication first

DOCSight lists optional authentication as a supported platform capability. Configure it through the application’s current interface and verify it locally before starting the public tunnel. The supplied evidence does not establish the exact authentication fields or defaults for every release, so this guide does not invent a username, default password, environment variable, or configuration path.

Use least privilege for integrations

If you configure API tokens, Home Assistant, notifications, speed-test services, BQM, Smokeping, or another integration, grant only the access required for that workflow. Rotate exposed credentials and remove unused integrations. Do not use a public tunnel as a way to expose modem administration pages or unrelated management services.

Control when the service is public

Start the tunnel when remote dashboard access is needed and stop it when it is not. Deleting an obsolete tunnel is also appropriate when you no longer intend to use its configuration. Remember that creating a tunnel alone does not start it, and stopping DOCSight does not automatically remove the tunnel configuration from the dashboard.

Protect the Localtonet device token

A Localtonet auth token identifies the client device. Keep it out of source control, screenshots, container environment examples, chat messages, and public issue reports. If you believe a token has been disclosed, follow the current account workflow to replace or revoke it rather than continuing to use the exposed value.

Keep software and backups current

Review DOCSight releases, Docker host updates, and Localtonet client updates as part of routine maintenance. Back up the persistent volume before significant changes and test restoration. A backup that has never been restored is not yet a verified recovery plan.

Troubleshooting common installation and access problems

The Docker command reports a container-name conflict

A container named docsight already exists, even if it is stopped. Inspect it before taking action:

docker ps -a --filter name=docsight
docker logs docsight

If it is the intended installation, start or troubleshoot that container instead of creating a duplicate. Remove it only when you understand why it stopped and have protected any required persistent data.

Docker reports that port 8765 is already allocated

Another container or host process is using the port. Use docker ps to check container mappings, then identify any non-container process through the tools appropriate to your operating system. Do not terminate an unidentified process. If you intentionally select another host port, use that new host port consistently for local access and the Localtonet target while leaving the application’s container-side port aligned with the deployment.

The container exits immediately

Check its status and logs:

docker ps -a --filter name=docsight
docker logs docsight

Typical categories include image download problems, storage errors, port conflicts, or an application startup failure. Use the actual log message rather than guessing. If the container remains running long enough, run the built-in doctor for a structured check.

The dashboard works on the server but not from another LAN device

Confirm that the second device is using the Docker host’s LAN address rather than localhost. Then check the host firewall, client isolation, VLAN policy, and whether the published port is visible on the intended interface. Make the smallest necessary change consistent with your network policy. You do not need LAN-wide access when our client runs directly on the Docker host and can reach the local endpoint there.

The dashboard loads, but modem data is missing

A functioning web interface and functioning modem polling are separate conditions. Confirm that you selected the correct supported hardware family, that the Docker host can reach the modem, and that required values in the wizard are accurate. Review docker logs docsight and run python -m app.doctor inside the container using the documented command.

If your device is not supported, use Generic Router mode rather than expecting unsupported DOCSIS fields to populate. Missing measurements should not be interpreted as healthy values.

The Localtonet URL does not open

Work from the inside out:

1. Open http://localhost:8765 on the Docker host.
2. If our client runs elsewhere, verify that its device can open the Docker host’s LAN address on port 8765.
3. Confirm that the correct Localtonet device is connected.
4. Confirm that the HTTP tunnel points to the correct local IP address and port.
5. Confirm that the tunnel was started, not merely created.
6. Review the assigned public URL from a separate network.

This sequence identifies whether the failure belongs to DOCSight, local networking, client connectivity, tunnel state, or the public browser path.

The public URL loads the wrong service

Recheck the local target and host port. A port mapping changed during container recreation may cause the tunnel to point to another process or a stale endpoint. Stop the tunnel while correcting the target so that an unintended service is not left public.

Monitoring stopped after a host restart

Check whether Docker itself started, then inspect the DOCSight container:

docker ps -a --filter name=docsight

The unless-stopped policy does not replace verification. If an operator previously stopped the container, or if Docker cannot mount storage or start the application, collection may remain offline. Also confirm that the Localtonet client reconnected if remote access is expected.

Frequently asked questions