DOCSight - Get your rightful internet service

Estimated reading time: 13 minutes

We all know this frustrating scenario: you come home after a long day at work, just want to stream your favorite series or play a game online, and nothing works. The picture buffers, the ping skyrockets or the connection drops out completely. You call the hotline of your provider - whether Vodafone, PYUR or others - and are put on hold forever, only to be told the standard answer: „Well, everything looks fine on our end. Have you ever restarted the router?“ As the customer, you are usually the one who is left out in the cold. The provider has the data, you just have the hassle. But that's over now. Today I'm going to introduce you to a real secret weapon that reverses the balance of power between you and your Internet provider: DOCSight.

This ingenious open source tool, developed by the German IT professional Dennis Braun (on GitHub as itsDNNS was born out of this very frustration. DOCSight monitors your cable connection around the clock, relentlessly collects evidence of every failure, no matter how small, and generates an official complaint PDF at the touch of a button that no support employee can ignore.

In this ultimate guide, you will learn everything you need to know about DOCSight: how it works, what the technical values mean and how you can install it as a Docker container directly at home in just a few minutes.

For detailed instructions and explanations of all configuration options, I recommend watching the YouTube video linked below. This video goes into detail about each individual setting, providing you with comprehensive instructions on how to set everything up correctly. Any code from the video can be found in this article, so you can use it directly without having to type it out.

This blog post, including video, is part of a series in which we build and set up our own home server. We start with the basics, such as installing Ubuntu VM with Docker, and then move on to configuring our own domain, security measures, and, above all, lots of cool and useful self-hosted services. Whether it's media servers like Plex or Jellyfin or document management like Paperless-NGX, we'll work together to build the setup you want to see. We'll even tackle topics like single sign-on (SSO) together.

What exactly is DOCSight?

DOCSight is a web-based monitoring solution designed specifically for DOCSIS cable modems (such as the AVM FRITZ!Box Cable series, Vodafone Station or the Arris TC4400). It automatically logs into your router in the background and reads out all relevant line values at regular intervals.

While your provider only ever takes a snapshot when you make a call (and the error naturally occurs at that exact second) not occurs), DOCSight builds up a complete history. It recognizes patterns, documents interruptions with a precise time stamp and visualizes the quality of your line over days, weeks and months.

But DOCSight is not just a dashboard for technology nerds. The absolute killer feature is the Preservation of evidence. The tool bundles all collected incidents in a so-called Incident Journal (incident log) and generates official, watertight complaint letters as PDF files. You can send these directly to your provider or - even better - to the Federal Network Agency.

What if I don't have cable Internet at all?

Do you have fiber optics, VDSL or Starlink? No problem! Although DOCSight was primarily built for the in-depth analysis of DOCSIS networks, it offers a Generic Router Mode. In this mode, the specific signal level measurements are omitted, but you still benefit from the core functions:

• Speedtest tracking
• Incident journal (failure logging)
• Generation of the complaint PDF

This means that you finally have a tool for professionally documenting interruptions for other connection types.

The core functions: The arsenal of your new secret weapon

DOCSight offers a wealth of functions that are constantly being expanded by the community and the developer. Here are the most important features in detail:

• 24/7 signal monitoring: DOCSight records every DOCSIS metric value around the clock. This includes downstream power, upstream power, SNR (signal-to-noise ratio), modulations, error rates, latencies and the actual speed.
• The complaint generator: You can create a structured PDF with just one click. A complaint without structure is just noise for providers. However, a document with named incidents, automated measurements over weeks and graphical before/after comparisons is legally solid proof.
• Incident journal & before/after comparisons: You can mark specific periods when the Internet was extremely poor and compare them with periods when it worked. DOCSight creates visual overlays that clearly show the drop in quality („degradation“).
• Speedtest tracking: DOCSight integrates speed tests (including the recognition of server IDs and names) so that you can document whether you are actually receiving the contractually agreed service.
• Home Assistant Integration: DOCSight transmits all modem values directly to your smart home via the MQTT protocol. This means you can have alerts pushed to your cell phone or have smart lamps light up red when the upstream drops.
• BQM (Broadband Quality Monitor) Import: Do you have old pings graphs from ThinkBroadband? DOCSight allows you to seamlessly import these historical images via drag-and-drop to place them alongside your local DOCSIS data.
• 100% Local & Private: DOCSight runs entirely on your own hardware (self-hosted). No data leaves your network, nothing is uploaded to a dubious cloud. Your network data belongs to you.

This is all up to date and is currently still being developed very diligently! For some features you will need to set up additional tools.

Technical excursion: Understanding DOCSIS

So that you can interpret the graphs in DOCSight correctly and stand up to the support on the phone, we need to take a quick dive into the technology. DOCSIS (Data Over Cable Service Interface Specification) is the standard that enables fast Internet via coaxial cable (the old TV cable).

The DOCSight dashboard shows you various metrics. Here is the translation into understandable German:

1. downstream (receive direction)

This is the signal that comes into your house from the distributor on the street.

• Power Level (signal level): This value is measured in dBmV. Ideally, it should be close to $0$ dBmV. A range of $-6$ to $+6$ dBmV is often tolerable (depending on the modulation and provider specification). If the value is too low, the signal is too weak. If it is too high, the signal is „overdriven“ and the router only understands noise.
• SNR / MER (signal-to-noise ratio): This is probably the most important value! It indicates how well the actual data signal stands out from the background noise of the line. The higher this value in dB, the better. Values above $33$ dB (for QAM256) are good, but if the SNR falls below $30$ dB, there will be massive packet loss and disconnections. DOCSight alerts you immediately if this value drops.

2. upstream (transmission direction)

This is the signal that your router „shouts back“ in the direction of the distribution box.

• Power Level: In contrast to the downstream, this value must be high. Your modem must transmit loud enough to overcome the attenuation of the cable and the return path interferers. Values between $40$ and $50$ dBmV are usually optimal. If the value rises above $50$ dBmV (or even to $58$ dBmV), your router has to literally „scream“ to be heard. This is a clear sign of a massive problem on the line or in the house amplifier.

3. error counter (Correctable vs. Uncorrectable)

Errors always occur on the line.

• Correctables: These are errors that the modem was able to repair itself thanks to built-in error correction. A few of them are completely normal.
• Uncorrectables: This is where it becomes critical. These are destroyed data packets that can no longer be recovered and have to be requested again. A rapid increase in uncorrectables means: your Internet stutters, pings skyrocket, streams break off. DOCSight tracks these values on every single channel.

Pro tip: At the request of the community, DOCSight recently introduced a feature that allows you to overlay several DOCSIS channels (Multi-Channel Comparison) in a graph. This allows you to see immediately whether only one frequency is disrupted or whether the entire frequency block is down!

Installation of DOCSight via Docker

DOCSight is designed as a Docker container. This means it is extremely lightweight and runs on almost anything: a small Raspberry Pi, a mini PC, an Unraid server or on a NAS system (such as Synology or QNAP).

Prerequisites:

• A running Docker environment (Docker Engine & Docker Compose).
• A supported cable modem with web interface (e.g. a FRITZ!Box Cable).
• (Optional) An MQTT broker for the Home Assistant connection.

Step 1: Create the docker-compose.yml Create a new folder for DOCSight on your server and create a file called docker-compose.yml. Paste the following code:

services:
  docsight:
    image: ghcr.io/itsdnns/docsight:latest
    container_name: docsight
    restart: unless-stopped
    ports:
      - "8765:8765"
    volumes:
      - /mnt/cache/appdata/monitoring/docsight:/data
    environment:
      - TZ=Europe/Berlin

Step 2: Start container Open the terminal in the same folder and start the container with a simple command:

docker-compose up -d

Step 3: The Setup Wizard Now open your web browser and call up the IP address of your server followed by port 8765 (e.g. http://192.168.178.50:8765). The DOCSight Setup Wizard will welcome you immediately. All you have to do now is enter the URL of your modem (e.g. for an AVM FRITZ! http://192.168.178.1), enter your user name and password. After a short connection test, you can specify the query interval (e.g. every 5 minutes) and your preferred language (available in 🇩🇪, 🇬🇧, 🇪🇸, 🇫🇷).

Tip: create a new user for the connection in your router.

That's it! From this moment on, DOCSight collects your data in the background.

The ultimate setup: The „Full Stack“ installation

If you have the simple Docker container running, you're already in a better position than 99 % of all cable customers. But for the real power users and those who want to collect legally watertight evidence for a special termination or reduction in monthly costs, there is also the „Full stack“ compose example (to be found here in the Wiki).

With this full-stack installation, you not only install DOCSight on the server, but also a complete armada of monitoring tools that interlock seamlessly.

What tools does the full stack consist of and what do they do?

Such an extended setup usually combines several specialized containers, which together form an unbeatable evidence package:

1. DOCSight (the centerpiece): As already described, this is the core of your setup. DOCSight is responsible for reading the physical line values of your modem (signal level, SNR, error counter) every second and generating the final complaint PDF. It monitors the „pipes“ through which your Internet flows.
2. Broadband measurement (The official authority): This is the absolute game changer. The official desktop app of the Federal Network Agency (broadband measurement) can also be operated as a container solution. While DOCSight looks, Why the line is bad, this container measures highly officially, how much speed actually reaches you. It carries out automated, legally recognized measurement campaigns (e.g. 30 measurements over 3 days).
3. MQTT Broker / Home Assistant (The message chain): A message broker such as Eclipse Mosquitto is often integrated into the full stack. It takes the data from DOCSight and pushes it to your smart home system in real time.

How everything works together brilliantly

The magic happens in the combination of tools. Let's assume you always have massive drops in download speed in the evening.

The Broadband measurement container starts its measurement campaign and records it in a highly official manner: „Customer only has 80 Mbit/s instead of the booked 1000 Mbit/s. This is a contractual undersupply.“ This report alone is often enough to reduce the bill. But the provider could still make excuses („It's because of your home network!“).

Here straddles DOCSight in: In exactly the same period, DOCSight shows that the modulation in the downstream has completely collapsed due to a defective amplifier on the street. So you tell the provider or the network agency both before: The official speed dip (broadband measurement) and the physical cause at the node (DOCSight). No support employee can get out of these pliers!

⚠️ Important note on the setup

As tempting as the full stack is, it requires a bit of craftsmanship! These additional tools do not simply run „out of the box“ with DOCSight.

Own configuration absolutely necessary: Each container in the full stack requires its own environment variables (.env files), volume shares and port assignments.

• The pitfalls of broadband measurement: The broadband measurement container in particular requires attention. As it is the official software of the BNetzA, you often have to access the container via VNC (virtual desktop in the browser) to initially agree to the terms and conditions, enter your tariff manually and start the measurement campaign manually. It is not a pure „install and forget“ process.

So take a quiet hour at the weekend for the full-stack setup, read the documentation of the respective container maintainer carefully and adapt the configurations to your own network. The effort is extremely worthwhile if you finally want to prove in black and white that the error is definitely not due to your WLAN!

YouTube video implementation

Conclusion

Fighting against large telecommunications companies often feels like tilting at windmills. As a customer, you are fobbed off on the phone with standardized phrases, while you pay good money month after month for a service that is not delivered.

DOCSight changes the rules of the game. It's not just a monitoring tool for your home network, it's your personal digital advocate. It transforms vague statements like „My internet is kind of slow“ into hard facts: „On May 12 between 18:00 and 21:30, the SNR on channel 4 dropped below 28 dB, resulting in 45,000 uncorrectable errors and massive packet loss. See attachment 1 in the PDF.“ This puts your provider under real pressure. Take network analysis into your own hands, install DOCSight and make sure you get what you pay for!

Useful links at a glance

• DOCSight GitHub Repository: https://github.com/itsDNNS/docsight
• Official wiki & documentary: https://github.com/itsDNNS/docsight/wiki
• Docker Installation Guide: https://docs.docker.com/get-docker/
• Broadband measurement (Federal Network Agency): https://www.breitbandmessung.de/

Interested, but lack time or knowledge?

No problem. Contact me and we will discuss your requirements. No matter if business or private.