Running without Docker

Running without Docker

DOCSight can be run directly on any system with Python 3.12+, without Docker or containers. This is useful for home servers, Raspberry Pis, or setups where Docker is not available or desired.

Note: The Docker-based installation is recommended for most users as it handles dependencies and updates automatically. This guide is for advanced users who prefer a native setup.

Prerequisites

• Python 3.12 or newer (python3 --version)
• pip (usually bundled with Python)
• git
• Network access to your modem (FritzBox, Vodafone Station, etc.)

---

Step 1: Clone the Repository

git clone https://github.com/itsDNNS/docsight.git
cd docsight

---

Step 2: Install Dependencies

It is strongly recommended to use a virtual environment to keep DOCSight's dependencies isolated from your system Python:

python3 -m venv .venv
source .venv/bin/activate       # Linux / macOS
# .venv\Scripts\activate        # Windows (PowerShell)

pip install -r requirements.txt

---

Step 2b: Compile Native Helpers (optional)

DOCSight ships two small C programs for ICMP-based features (traceroute, connection monitoring). In Docker these are compiled and installed automatically. For bare-metal installs you need to build them yourself.

Prerequisites: gcc (usually already installed on most Linux systems)

# Install build dependencies if needed (Debian/Ubuntu)
sudo apt install gcc

# Compile the helpers
sudo gcc -O2 -Wall -o /usr/local/bin/docsight-icmp-helper tools/icmp_probe_helper.c
sudo gcc -O2 -Wall -o /usr/local/bin/docsight-traceroute-helper tools/traceroute_helper.c

# Set ownership and setuid bit (required for raw socket access)
sudo chown root:root /usr/local/bin/docsight-icmp-helper /usr/local/bin/docsight-traceroute-helper
sudo chmod 4755 /usr/local/bin/docsight-icmp-helper /usr/local/bin/docsight-traceroute-helper

Why setuid? ICMP raw sockets require elevated privileges. The setuid bit allows DOCSight to run these specific binaries with the necessary permissions while the main process runs as a normal user.

Skip this step? DOCSight works fine without these binaries. Traceroute and ICMP probe features will be unavailable, but everything else (modem polling, speedtest, dashboard, etc.) works normally.

---

Step 3: Set Up a Data Directory

DOCSight stores its configuration and database in a data directory. By default it uses /data, but you can point it anywhere:

mkdir -p ~/docsight-data
export DATA_DIR=~/docsight-data

Tip: Add this export line to your shell profile (~/.bashrc, ~/.zshrc, etc.) to make it permanent.

---

Step 4: Start DOCSight

python3 -m app.main

Then open http://localhost:8765 in your browser and follow the setup wizard.

Port: DOCSight listens on port 8765 by default. You can change this in the setup wizard (Settings → Web Port).

---

Step 5: Run as a systemd Service (optional)

To have DOCSight start automatically on boot, create a systemd service unit.

Create /etc/systemd/system/docsight.service (adjust paths as needed):

[Unit]
Description=DOCSight DOCSIS Monitor
After=network.target

[Service]
Type=simple
User=YOUR_USERNAME
WorkingDirectory=/path/to/docsight
Environment="DATA_DIR=/home/YOUR_USERNAME/docsight-data"
ExecStart=/path/to/docsight/.venv/bin/python3 -m app.main
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

Then enable and start it:

sudo systemctl daemon-reload
sudo systemctl enable --now docsight
sudo systemctl status docsight

View logs with:

journalctl -u docsight -f

---

Updating

To update DOCSight to the latest version:

cd /path/to/docsight
source .venv/bin/activate
git pull
pip install -r requirements.txt
sudo systemctl restart docsight   # if running as a service

---

Troubleshooting

Problem	Solution
ModuleNotFoundError	Make sure the virtual environment is activated: source .venv/bin/activate
Port 8765 already in use	Change the web port in the setup wizard, or set a different port before first start by editing ~/docsight-data/config.json
Cannot reach modem	Ensure DOCSight runs on the same network as the modem; check firewall rules
PermissionError on data dir	Make sure the user running DOCSight has read/write access to DATA_DIR
Traceroute helper not found	Compile and install the native helpers, see Step 2b

---

Environment Variables

All settings can also be configured via environment variables instead of the setup wizard. Key variables:

Variable	Default	Description
DATA_DIR	/data	Directory for config and database
MODEM_TYPE	fritzbox	Modem driver (fritzbox, vodafone_station, ...)
MODEM_URL	http://192.168.178.1	URL of your modem's admin interface
MODEM_USER	(empty)	Modem login username
MODEM_PASSWORD	(empty)	Modem login password
POLL_INTERVAL	900	Polling interval in seconds

See Configuration for the full list.