Skip to content

Commit 43d17da

Browse files
itsDNNSclaude
itsDNNS
and
claude
committed
Add installation guide and generalize FRITZ_* to MODEM_*
Add beginner-friendly INSTALL.md with step-by-step instructions for Docker CLI, Docker Compose, Portainer, and Dockhand. Includes setup wizard walkthrough, updating, troubleshooting, and uninstalling. Rename all fritz_* config keys to modem_* and FRITZ_* env vars to MODEM_* for modem-agnostic naming. Old names are supported as backwards-compatible fallback: legacy config.json keys are auto-migrated on load, and deprecated FRITZ_* env vars are still checked. Also renames docker-compose.yml volume from docsis_data to docsight_data and removes the build: . directive (dev-only). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
1 parent d2cc26a commit 43d17da

File tree

13 files changed

+491
-92
lines changed

13 files changed

+491
-92
lines changed

‎.env.example‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,10 @@
22
# Copy to .env and edit. All values can also be set via the web UI setup wizard.
33
# Environment variables override config.json values.
44

5-
# FritzBox connection
6-
FRITZ_URL=http://192.168.178.1
7-
FRITZ_USER=
8-
FRITZ_PASSWORD=
5+
# Modem connection
6+
MODEM_URL=http://192.168.178.1
7+
MODEM_USER=
8+
MODEM_PASSWORD=
99

1010
# MQTT broker
1111
MQTT_HOST=localhost

‎INSTALL.md‎

Lines changed: 326 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,326 @@
1+
# Installation Guide
2+
3+
Get DOCSight running in under 10 minutes.
4+
5+
## What You Need
6+
7+
- **A computer or NAS** with Docker installed
8+
- **An AVM FRITZ!Box Cable router** (e.g. FRITZ!Box 6690 Cable)
9+
- **Your FRITZ!Box login credentials** (the username and password you use to log into `http://fritz.box`)
10+
11+
> **New to Docker?** Docker runs applications in isolated containers. Install it from:
12+
> - **Windows/Mac**: [Docker Desktop](https://www.docker.com/products/docker-desktop/)
13+
> - **Synology NAS**: Search for "Container Manager" in Package Center
14+
> - **Linux**: [Docker Engine](https://docs.docker.com/engine/install/)
15+
16+
## Choose Your Installation Method
17+
18+
All four methods create the exact same container. Pick whichever fits your setup:
19+
20+
| Method | Best for |
21+
|---|---|
22+
| [Docker CLI](#docker-cli) | Quick terminal one-liner |
23+
| [Docker Compose](#docker-compose) | Reproducible config file |
24+
| [Portainer](#portainer) | NAS users with Portainer UI |
25+
| [Dockhand](#dockhand) | NAS users with Dockhand UI |
26+
27+
---
28+
29+
## Docker CLI
30+
31+
### Step 1: Open a terminal
32+
33+
- **Windows**: Search for "Command Prompt" or "PowerShell" in the Start menu
34+
- **Mac**: Open "Terminal" from Applications → Utilities
35+
- **Linux**: Open your terminal emulator
36+
- **Synology NAS**: SSH into your NAS or use the built-in terminal
37+
38+
### Step 2: Run this command
39+
40+
```bash
41+
docker run -d \
42+
--name docsight \
43+
--restart unless-stopped \
44+
-p 8765:8765 \
45+
-v docsight_data:/data \
46+
ghcr.io/itsdnns/docsight:latest
47+
```
48+
49+
| Flag | What it does |
50+
|---|---|
51+
| `-d` | Runs in the background |
52+
| `--name docsight` | Names the container "docsight" |
53+
| `--restart unless-stopped` | Auto-starts after reboot |
54+
| `-p 8765:8765` | Makes the web UI available on port 8765 |
55+
| `-v docsight_data:/data` | Stores config and history permanently |
56+
57+
### Step 3: Open DOCSight
58+
59+
Open your browser and go to **http://localhost:8765**
60+
61+
> On a NAS or remote machine, replace `localhost` with the machine's IP address, e.g. `http://192.168.178.15:8765`
62+
63+
Now continue with [First-Time Setup](#first-time-setup).
64+
65+
---
66+
67+
## Docker Compose
68+
69+
### Step 1: Create a `docker-compose.yml` file
70+
71+
Create a new folder (e.g. `docsight`) and save this file inside it as `docker-compose.yml`:
72+
73+
```yaml
74+
services:
75+
docsight:
76+
image: ghcr.io/itsdnns/docsight:latest
77+
container_name: docsight
78+
restart: unless-stopped
79+
ports:
80+
- "8765:8765"
81+
volumes:
82+
- docsight_data:/data
83+
84+
volumes:
85+
docsight_data:
86+
```
87+
88+
### Step 2: Start the container
89+
90+
Open a terminal in the folder with your `docker-compose.yml` and run:
91+
92+
```bash
93+
docker compose up -d
94+
```
95+
96+
### Step 3: Open DOCSight
97+
98+
Open your browser and go to **http://localhost:8765**
99+
100+
> On a NAS or remote machine, replace `localhost` with the machine's IP address, e.g. `http://192.168.178.15:8765`
101+
102+
Now continue with [First-Time Setup](#first-time-setup).
103+
104+
---
105+
106+
## Portainer
107+
108+
### Step 1: Open Portainer
109+
110+
Open your Portainer web UI (usually `https://your-nas-ip:9443`).
111+
112+
### Step 2: Create a new stack
113+
114+
1. Go to **Stacks** in the left menu
115+
2. Click **Add stack**
116+
3. Give it the name `docsight`
117+
4. In the **Web editor**, paste this YAML:
118+
119+
```yaml
120+
services:
121+
docsight:
122+
image: ghcr.io/itsdnns/docsight:latest
123+
container_name: docsight
124+
restart: unless-stopped
125+
ports:
126+
- "8765:8765"
127+
volumes:
128+
- docsight_data:/data
129+
130+
volumes:
131+
docsight_data:
132+
```
133+
134+
5. Click **Deploy the stack**
135+
136+
### Step 3: Open DOCSight
137+
138+
Open your browser and go to **http://your-nas-ip:8765**
139+
140+
Now continue with [First-Time Setup](#first-time-setup).
141+
142+
---
143+
144+
## Dockhand
145+
146+
### Step 1: Open Dockhand
147+
148+
Open your Dockhand web UI in your browser.
149+
150+
### Step 2: Create a new stack
151+
152+
1. Go to **Stacks** in the navigation
153+
2. Click **Create Stack**
154+
3. Give it the name `docsight`
155+
4. In the YAML editor, paste this:
156+
157+
```yaml
158+
services:
159+
docsight:
160+
image: ghcr.io/itsdnns/docsight:latest
161+
container_name: docsight
162+
restart: unless-stopped
163+
ports:
164+
- "8765:8765"
165+
volumes:
166+
- docsight_data:/data
167+
168+
volumes:
169+
docsight_data:
170+
```
171+
172+
5. Click **Deploy**
173+
174+
### Step 3: Open DOCSight
175+
176+
Open your browser and go to **http://your-nas-ip:8765**
177+
178+
Now continue with [First-Time Setup](#first-time-setup).
179+
180+
---
181+
182+
## First-Time Setup
183+
184+
When you open DOCSight for the first time, a setup wizard guides you through the configuration.
185+
186+
![Setup Wizard](docs/screenshots/setup.png)
187+
188+
### Step 1: Modem Connection
189+
190+
| Field | What to enter |
191+
|---|---|
192+
| **Modem URL** | `http://192.168.178.1` (default FRITZ!Box address) |
193+
| **Username** | Your FRITZ!Box username |
194+
| **Password** | Your FRITZ!Box password |
195+
196+
Click **Test Connection** to verify DOCSight can reach your router. If successful, continue to the next step.
197+
198+
### Step 2: General Settings
199+
200+
| Field | Description | Default |
201+
|---|---|---|
202+
| **ISP** | Your internet provider name (for reports) | - |
203+
| **Poll Interval** | How often to read channel data (seconds) | `300` (5 min) |
204+
| **History Days** | How many days of snapshots to keep | `7` |
205+
| **Snapshot Time** | When to save the daily snapshot | `03:00` |
206+
207+
### Advanced: MQTT for Home Assistant (optional)
208+
209+
If you use Home Assistant, you can enable MQTT to get per-channel sensors automatically:
210+
211+
| Field | Description |
212+
|---|---|
213+
| **MQTT Host** | Your MQTT broker address (e.g. `192.168.178.15`) |
214+
| **MQTT Port** | `1883` (default) |
215+
| **MQTT User** | Broker username (if required) |
216+
| **MQTT Password** | Broker password (if required) |
217+
218+
### Complete
219+
220+
Click **Complete Setup** - DOCSight starts monitoring immediately. Your dashboard will show channel data after the first poll.
221+
222+
---
223+
224+
## Updating DOCSight
225+
226+
Your configuration and history are stored in a Docker volume and survive updates.
227+
228+
### Docker CLI
229+
230+
```bash
231+
docker pull ghcr.io/itsdnns/docsight:latest
232+
docker stop docsight
233+
docker rm docsight
234+
docker run -d --name docsight --restart unless-stopped -p 8765:8765 -v docsight_data:/data ghcr.io/itsdnns/docsight:latest
235+
```
236+
237+
### Docker Compose
238+
239+
```bash
240+
docker compose pull
241+
docker compose up -d
242+
```
243+
244+
### Portainer
245+
246+
1. Open the **docsight** stack
247+
2. Click **Update the stack**
248+
3. Enable **Re-pull image**
249+
4. Click **Update**
250+
251+
### Dockhand
252+
253+
1. Open the **docsight** stack
254+
2. Click **Redeploy**
255+
256+
---
257+
258+
## Troubleshooting
259+
260+
### "Can't open http://localhost:8765"
261+
262+
- **Is the container running?** Check with `docker ps` - you should see a container named `docsight`
263+
- **On a NAS?** Use the NAS IP address instead of `localhost`, e.g. `http://192.168.178.15:8765`
264+
- **Firewall?** Make sure port 8765 is not blocked
265+
266+
### "Test Connection fails"
267+
268+
- **Is the URL correct?** The default FRITZ!Box address is `http://192.168.178.1`. Try opening it in your browser first.
269+
- **Are the credentials correct?** Use the same username and password you use to log into the FRITZ!Box web interface.
270+
- **Network access?** The Docker container must be able to reach your FRITZ!Box. If running on a remote server, ensure it's on the same network.
271+
272+
### "Port 8765 already in use"
273+
274+
Another application is using port 8765. Change the port mapping:
275+
276+
```bash
277+
# Docker CLI: change the first number to any free port
278+
docker run -d --name docsight --restart unless-stopped -p 9876:8765 -v docsight_data:/data ghcr.io/itsdnns/docsight:latest
279+
```
280+
281+
```yaml
282+
# Docker Compose / Portainer / Dockhand: change the first number
283+
ports:
284+
- "9876:8765"
285+
```
286+
287+
Then open `http://localhost:9876` instead.
288+
289+
### "Container keeps restarting"
290+
291+
Check the container logs:
292+
293+
```bash
294+
docker logs docsight
295+
```
296+
297+
The logs usually indicate the problem. Common causes:
298+
- Invalid configuration - delete the volume and start fresh: `docker volume rm docsight_data`
299+
- Network issues reaching the modem
300+
301+
### "How do I check if it's working?"
302+
303+
```bash
304+
docker logs docsight --tail 20
305+
```
306+
307+
You should see log entries about successful polls. If the dashboard shows channel data, everything is working.
308+
309+
---
310+
311+
## Uninstalling
312+
313+
### Docker CLI / Docker Compose
314+
315+
```bash
316+
docker stop docsight
317+
docker rm docsight
318+
docker volume rm docsight_data
319+
```
320+
321+
### Portainer / Dockhand
322+
323+
1. Open the **docsight** stack
324+
2. Delete the stack
325+
326+
This removes the container and all stored data.

‎README.md‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,8 @@ docker run -d --name docsight -p 8765:8765 -v docsight_data:/data ghcr.io/itsdnn
3232

3333
Open `http://localhost:8765` - the setup wizard guides you through configuration.
3434

35+
For detailed step-by-step instructions (including Portainer and Dockhand), see the **[Installation Guide](INSTALL.md)**.
36+
3537
### Using Docker Compose
3638

3739
```bash
@@ -60,9 +62,9 @@ Copy `.env.example` to `.env` and edit:
6062

6163
| Variable | Default | Description |
6264
|---|---|---|
63-
| `FRITZ_URL` | `http://192.168.178.1` | Modem URL |
64-
| `FRITZ_USER` | - | Modem username |
65-
| `FRITZ_PASSWORD` | - | Modem password |
65+
| `MODEM_URL` | `http://192.168.178.1` | Modem URL |
66+
| `MODEM_USER` | - | Modem username |
67+
| `MODEM_PASSWORD` | - | Modem password |
6668
| `MQTT_HOST` | - | MQTT broker host (optional) |
6769
| `MQTT_PORT` | `1883` | MQTT broker port |
6870
| `MQTT_USER` | - | MQTT username (optional) |

0 commit comments

Comments
 (0)