Skip to content

Commit cab0896

Browse files
bigsk1bigsk1
committed
update read me with navigation
1 parent b11253f commit cab0896

File tree

2 files changed

+190
-47
lines changed

2 files changed

+190
-47
lines changed

‎README.md

+188-45
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,90 @@
55

66
A real-time NVIDIA GPU monitoring dashboard built with Docker for easy deployment and cross-platform compatibility.
77

8+
## Quick Navigation 🔍
9+
10+
<details open >
11+
<summary>Features</summary>
12+
13+
- [Features](#features)
14+
15+
</details>
16+
17+
<details open>
18+
<summary>Prerequisites</summary>
19+
20+
- [Prerequisites](#prerequisites)
21+
22+
</details>
23+
24+
<details open>
25+
<summary>Quick Start</summary>
26+
27+
- [Using Pre-built Image](#using-pre-built-image)
28+
- [Using Docker Compose](#using-docker-compose)
29+
30+
</details>
31+
32+
<details>
33+
<summary>Installation Prerequisites</summary>
34+
35+
- [Ubuntu / Debian / WSL](#1-ubuntu--debian--wsl)
36+
- [Install NVIDIA Container Toolkit](#2-install-nvidia-container-toolkit)
37+
- [Configure Docker with Toolkit](#3-configure-docker-with-toolkit)
38+
- [Restart Docker Daemon](#4-restart-docker-daemon)
39+
- [Test Installation](#5-test-to-see-if-installed-correctly)
40+
41+
</details>
42+
43+
<details>
44+
<summary>Building gpu-monitor from Source</summary>
45+
46+
- [Clone and Build the Repository](#building-gpu-monitor-from-source)
47+
48+
</details>
49+
50+
<details>
51+
<summary>Configuration</summary>
52+
53+
- [Access the Dashboard](#configuration)
54+
55+
</details>
56+
57+
<details open>
58+
<summary>Alternative Setup Method</summary>
59+
60+
- [Setup Script Instructions](#alternative-setup-method)
61+
62+
</details>
63+
64+
<details>
65+
<summary>Data Persistence</summary>
66+
67+
- [Managing Data Persistence](#data-persistence)
68+
69+
</details>
70+
71+
<details>
72+
<summary>Alerts</summary>
73+
74+
- [Configuring Alerts](#alerts)
75+
76+
</details>
77+
78+
<details>
79+
<summary>Troubleshooting</summary>
80+
81+
- [Common Issues](#common-issues)
82+
83+
</details>
84+
85+
<details>
86+
<summary>License</summary>
87+
88+
- [License](#license)
89+
90+
</details>
91+
892
![GPU Monitor Dashboard](images/gpu.png)
993

1094
## Features
@@ -19,27 +103,38 @@ A real-time NVIDIA GPU monitoring dashboard built with Docker for easy deploymen
19103
- Real time alerts - sound and notification
20104
- Responsive theme for any size screen
21105

22-
23106
## Prerequisites
24107

25108
- Docker
26109
- NVIDIA GPU with drivers installed
27110
- NVIDIA Container Toolkit
28111
- Python 3.10+
29112

113+
30114
## Quick Start
31115

32-
### Using Pre-built Image Docker Run
116+
Test to see if you already have the requirements and ready to use.
117+
118+
```bash
119+
sudo docker run --rm --runtime=nvidia --gpus all ubuntu nvidia-smi
120+
```
121+
If this failed proceed to [Installation Prerequisites](#installation-prerequisites)
122+
123+
124+
125+
### Using Pre-built Image
33126

34127
```bash
35128
docker run -d \
36129
--name gpu-monitor \
37-
--restart unless-stopped \
38-
--gpus all \
39130
-p 8081:8081 \
40131
-e TZ=America/Los_Angeles \
41132
-v /etc/localtime:/etc/localtime:ro \
42-
ghcr.io/bigsk1/gpu-monitor:latest
133+
-v ./history:/app/history \
134+
-v ./logs:/app/logs \
135+
--gpus all \
136+
--restart unless-stopped \
137+
bigsk1/gpu-monitor:latest
43138
```
44139
Note: Update your timezone to use the correct time
45140
### Using Docker Compose
@@ -55,32 +150,59 @@ cd gpu-monitor
55150
docker-compose up -d
56151
```
57152

58-
3. Access the dashboard at: `http://localhost:8081/gpu-stats.html`
153+
3. Access the dashboard at: [http://localhost:8081/gpu-stats.html](http://localhost:8081/gpu-stats.html)
154+
59155

60156

61157
## Installation Prerequisites
62158

63-
### 1. Install NVIDIA Container Toolkit
64159

65-
For Ubuntu/Debian:
160+
### 1. Ubuntu / Debian / WSL
161+
Windows users make sure you have wsl with docker an easy way is [Docker Desktop Installation for Windows](https://docs.docker.com/desktop/setup/install/windows-install/)
162+
163+
Installing with apt add NVIDIA package repositories
164+
66165
```bash
67-
# Add NVIDIA package repositories
68-
distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
69-
curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add -
70-
curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | sudo tee /etc/apt/sources.list.d/nvidia-docker.list
166+
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg \
167+
&& curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | \
168+
sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \
169+
sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
170+
```
171+
172+
### 2. Install nvidia container toolkit
71173

72-
# Install nvidia-docker2
174+
```bash
73175
sudo apt-get update
74-
sudo apt-get install -y nvidia-docker2
176+
```
177+
```bash
178+
sudo apt-get install -y nvidia-container-toolkit
179+
```
180+
181+
### 3. Configure Docker with toolkit
182+
183+
```bash
184+
sudo nvidia-ctk runtime configure --runtime=docker
185+
```
186+
The nvidia-ctk command modifies the /etc/docker/daemon.json file on the host. The file is updated so that Docker can use the NVIDIA Container Runtime.
187+
75188

76-
# Restart Docker daemon
189+
### 4. Restart Docker daemon
190+
191+
```bash
77192
sudo systemctl restart docker
78193
```
79194

195+
### 5. Test to see if installed correctly
196+
197+
```bash
198+
sudo docker run --rm --runtime=nvidia --gpus all ubuntu nvidia-smi
199+
```
200+
201+
80202
For other distributions, check the [official documentation](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html).
81203

82204

83-
## Building from Source
205+
## Building gpu-monitor from source
84206

85207
1. Clone the repository:
86208
```bash
@@ -97,47 +219,65 @@ docker build -t gpu-monitor .
97219
```bash
98220
docker run -d \
99221
--name gpu-monitor \
100-
--restart unless-stopped \
101-
--gpus all \
102222
-p 8081:8081 \
103223
-e TZ=America/Los_Angeles \
104224
-v /etc/localtime:/etc/localtime:ro \
225+
-v ./history:/app/history \
226+
-v ./logs:/app/logs \
227+
--gpus all \
228+
--restart unless-stopped \
105229
gpu-monitor
106230
```
107231

108232
## Configuration
109233

110-
The dashboard is accessible at `http://localhost:8081/gpu-stats.html` by default. To change the port, modify the `docker-compose.yml` file or the `-p` parameter in the docker run command.
234+
The dashboard is accessible at Access the dashboard at: [http://localhost:8081/gpu-stats.html](http://localhost:8081/gpu-stats.html)
235+
by default. To change the port, modify the `docker-compose.yml` file or the `-p` parameter in the docker run command.
111236

112237
---
113238

114239
![GPU Monitor Dashboard](images/gpu2.jpg)
115240

116241

117-
## Alternative Setup Method (linux)
242+
## Alternative Setup Method
118243

119244
A setup script is provided for convenience. It checks prerequisites and manages the service:
120245

246+
- If you have issues then make sure `setup.sh` is executable
247+
121248
```bash
122-
# Check prerequisites and start the service
123-
./setup.sh start
249+
chmod +x ./setup.sh
250+
```
124251

125-
# Stop the service
252+
---
253+
- Check prerequisites and start the service
254+
```bash
255+
./setup.sh start
256+
```
257+
---
258+
- Stop the service
259+
```bash
126260
./setup.sh stop
127-
128-
# Restart the service
261+
```
262+
---
263+
- Restart the service
264+
```bash
129265
./setup.sh restart
130-
131-
# Check service status
266+
```
267+
---
268+
- Check service status
269+
```bash
132270
./setup.sh status
133-
134-
# View logs
271+
```
272+
---
273+
- View logs
274+
```bash
135275
./setup.sh logs
136276
```
137277

138-
Example of starting and building a container
278+
Example of script running
139279
```bash
140-
user@ai:~/gpu-monitor$ ./setup.sh start
280+
~/gpu-monitor ./setup.sh start
141281
[+] Checking prerequisites...
142282
[+] Docker: Found
143283
[+] Docker Compose: Found
@@ -154,24 +294,24 @@ Creating gpu-monitor ... done
154294

155295
## Data Persistence
156296

157-
By default, all data is stored within the container for optimal performance and cleanup. If you need to persist data between container rebuilds, modify the docker-compose.yml:
297+
By default, all data is stored within the container will persist between container rebuilds, if you don't want that then remove volumes, modify the docker run or docker-compose.yml:
158298

159299
```yaml
160300
services:
161301
gpu-monitor:
162302
# ... other settings ...
163303
volumes:
164-
- ./history:/app/history # Persist historical data
165-
- ./logs:/app/logs # Persist logs
304+
- ./history:/app/history # Remove Persist historical data
305+
- ./logs:/app/logs # Remove Persist logs
166306
```
167307
168308
## Alerts
169309
170-
You can enable or disable alerts in ui, you can set thresholds for gpu temp, gpu utilization % and watts. Setting are saved in browser.
310+
You can enable or disable alerts in ui, you can set thresholds for gpu temp, gpu utilization % and watts. Setting are saved in your browser if you make changes you only need to do it once, however you can always modify the code and rebuild the container to make it permanent.
311+
171312
The defaults are:
172313
173314
```bash
174-
this.thresholds = {
175315
temperature: 80,
176316
utilization: 100,
177317
power: 300
@@ -188,6 +328,12 @@ In windows you can disable native alert notifications sound or disable gpu-monit
188328
1. **NVIDIA SMI not found**
189329
- Ensure NVIDIA drivers are installed
190330
- Verify NVIDIA Container Toolkit installation
331+
- make sure you can run
332+
333+
```bash
334+
sudo docker run --rm --runtime=nvidia --gpus all ubuntu nvidia-smi
335+
```
336+
If this failed proceed to [Installation Prerequisites](#installation-prerequisites)
191337

192338
2. **Container fails to start**
193339
- Check Docker logs: `docker logs gpu-monitor`
@@ -198,17 +344,14 @@ In windows you can disable native alert notifications sound or disable gpu-monit
198344
- Verify container is running: `docker ps`
199345
- Check container logs: `docker logs gpu-monitor`
200346
- Ensure port 8081 is not in use
201-
4. **Timezone is off**
202-
203-
Note: Replace America/Los_Angeles with your timezone if different. Common timezones:
204-
205-
US Eastern: America/New_York
206-
207-
US Central: America/Chicago
347+
4. **TimeStamps don't match your local time**
208348

209-
US Mountain: America/Denver
349+
- Replace `America/Los_Angeles` with your timezone
350+
[List of tz database time zones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)
210351

211-
US Pacific: America/Los_Angeles
352+
5. **I don't like the alert sound**
353+
- Replace the .mp3 in the `sounds` folder and name it alert.mp3
354+
- Getting double sounds from notifications disable one of them
212355

213356

214357
## License

‎docker-compose.yml

+2-2
Original file line numberDiff line numberDiff line change
@@ -10,8 +10,8 @@ services:
1010
- TZ=America/Los_Angeles # update your timezone
1111
volumes:
1212
- /etc/localtime:/etc/localtime:ro # Share host timezone
13-
- ./history:/app/history # Persist historical data on host (optional)
14-
- ./logs:/app/logs # Persist logs (optional)
13+
- ./history:/app/history # Persist historical data on host
14+
- ./logs:/app/logs # Persist logs
1515
deploy:
1616
resources:
1717
reservations:

0 commit comments

Comments
 (0)