Skip to content

Commit 12401e1

Browse files
guiyuminguiyumin
committed
feat: add installation details documentation for NodePulse agent
1 parent 5f4e5cf commit 12401e1

1 file changed

Lines changed: 212 additions & 0 deletions

File tree

‎INSTALLATION.md‎

Lines changed: 212 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,212 @@
1+
# NodePulse Agent - Installation Details
2+
3+
This document lists all files and directories created by the NodePulse agent installation.
4+
5+
## Installed Files and Directories
6+
7+
### Binary
8+
- `/usr/local/bin/pulse` - Main agent executable (~15 MB)
9+
10+
### Configuration
11+
- `/etc/node-pulse/` - Configuration directory
12+
- `/etc/node-pulse/nodepulse.yml` - Agent configuration file (permissions: 0644)
13+
14+
### Data/State
15+
- `/var/lib/node-pulse/` - Data directory
16+
- `/var/lib/node-pulse/server_id` - Persisted server UUID (permissions: 0600)
17+
- `/var/lib/node-pulse/buffer/` - Failed metrics buffer directory
18+
- `/var/lib/node-pulse/buffer/*.jsonl` - Hourly JSONL buffer files (auto-cleaned after 48h)
19+
20+
### Logs (Optional)
21+
- `/var/log/node-pulse/` - Log directory (created if logging to file is enabled)
22+
- `/var/log/node-pulse/agent.log` - Main log file
23+
- `/var/log/node-pulse/agent.log.*.gz` - Rotated compressed logs
24+
25+
### Runtime (Daemon Mode)
26+
- `/tmp/nodepulse.pid` - PID file for daemon mode (auto-removed on stop)
27+
28+
### Systemd Service (Production Mode)
29+
- `/etc/systemd/system/node-pulse.service` - Main systemd service unit
30+
- `/etc/systemd/system/node-pulse-updater.service` - Auto-updater service unit
31+
- `/etc/systemd/system/node-pulse-updater.timer` - Auto-updater timer (runs every 10 minutes)
32+
33+
## Installation Modes
34+
35+
### Quick Install (Recommended)
36+
```bash
37+
curl -fsSL https://get.nodepulse.sh | sudo bash
38+
sudo pulse setup
39+
sudo pulse service install
40+
sudo pulse service start
41+
```
42+
43+
**Creates:**
44+
- Binary: `/usr/local/bin/pulse`
45+
- Config: `/etc/node-pulse/nodepulse.yml`
46+
- State: `/var/lib/node-pulse/server_id`
47+
- State: `/var/lib/node-pulse/buffer/`
48+
- Service: `/etc/systemd/system/node-pulse.service`
49+
- Timer: `/etc/systemd/system/node-pulse-updater.{service,timer}`
50+
51+
### Manual Installation
52+
```bash
53+
# Download and install binary
54+
wget https://github.com/node-pulse/agent/releases/latest/download/pulse-linux-amd64.tar.gz
55+
tar -xzf pulse-linux-amd64.tar.gz
56+
sudo mv pulse /usr/local/bin/
57+
sudo chmod +x /usr/local/bin/pulse
58+
59+
# Setup configuration
60+
sudo pulse setup
61+
```
62+
63+
**Creates:**
64+
- Binary: `/usr/local/bin/pulse`
65+
- Config: `/etc/node-pulse/nodepulse.yml`
66+
- State: `/var/lib/node-pulse/server_id`
67+
- State: `/var/lib/node-pulse/buffer/`
68+
69+
## Uninstallation
70+
71+
### Complete Uninstall (All Files)
72+
73+
```bash
74+
# Stop and disable service
75+
sudo pulse service stop
76+
sudo pulse service uninstall
77+
78+
# Remove binary
79+
sudo rm -f /usr/local/bin/pulse
80+
81+
# Remove configuration
82+
sudo rm -rf /etc/node-pulse
83+
84+
# Remove data and buffer
85+
sudo rm -rf /var/lib/node-pulse
86+
87+
# Remove logs (optional)
88+
sudo rm -rf /var/log/node-pulse
89+
90+
# Remove PID file (if exists)
91+
sudo rm -f /tmp/nodepulse.pid
92+
```
93+
94+
### Partial Uninstall (Keep Configuration)
95+
96+
If you want to preserve configuration for later reinstallation:
97+
98+
```bash
99+
# Stop and disable service
100+
sudo pulse service stop
101+
sudo pulse service uninstall
102+
103+
# Remove binary only
104+
sudo rm -f /usr/local/bin/pulse
105+
106+
# Keep: /etc/node-pulse and /var/lib/node-pulse
107+
```
108+
109+
### Uninstall Service Only
110+
111+
To switch from systemd service to daemon mode:
112+
113+
```bash
114+
# Stop and uninstall service
115+
sudo pulse service stop
116+
sudo pulse service uninstall
117+
118+
# Binary and config remain for daemon mode
119+
pulse start -d
120+
```
121+
122+
## File Permissions
123+
124+
| Path | Type | Permissions | Owner |
125+
|------|------|-------------|-------|
126+
| `/usr/local/bin/pulse` | Binary | 0755 | root |
127+
| `/etc/node-pulse/` | Directory | 0755 | root |
128+
| `/etc/node-pulse/nodepulse.yml` | File | 0644 | root |
129+
| `/var/lib/node-pulse/` | Directory | 0755 | root |
130+
| `/var/lib/node-pulse/server_id` | File | 0600 | root |
131+
| `/var/lib/node-pulse/buffer/` | Directory | 0755 | root |
132+
| `/var/log/node-pulse/` | Directory | 0755 | root |
133+
| `/var/log/node-pulse/agent.log` | File | 0644 | root |
134+
| `/etc/systemd/system/*.service` | File | 0644 | root |
135+
| `/etc/systemd/system/*.timer` | File | 0644 | root |
136+
137+
## Disk Usage
138+
139+
Typical disk usage:
140+
- Binary: ~15 MB
141+
- Config: <1 KB
142+
- Server ID: <100 bytes
143+
- Buffer: 0-50 MB (depends on connection failures, auto-cleaned after 48h)
144+
- Logs: 0-30 MB (auto-rotated, keeps 3 backups)
145+
146+
**Total:** ~15-95 MB
147+
148+
## Network Usage
149+
150+
- **Normal operation:** ~1 KB every 5 seconds (configurable interval)
151+
- **Buffer flush:** Variable (depends on buffered data)
152+
- **Auto-updater:** ~15 MB every 10 minutes (only if update available)
153+
154+
## Process Information
155+
156+
- **Process name:** `pulse`
157+
- **Memory usage:** <40 MB RAM
158+
- **CPU usage:** <1% (spikes briefly during metric collection)
159+
- **Service name:** `node-pulse`
160+
- **Timer name:** `node-pulse-updater.timer`
161+
162+
## Automated Maintenance
163+
164+
The agent performs automatic maintenance:
165+
166+
1. **Buffer cleanup:** Deletes JSONL files older than 48 hours
167+
2. **Log rotation:** Rotates logs when they exceed 10 MB (keeps 3 backups, 7 days retention)
168+
3. **Auto-updates:** Checks for updates every 10 minutes via systemd timer
169+
170+
## Troubleshooting
171+
172+
### Check installation status
173+
```bash
174+
pulse status
175+
```
176+
177+
### Verify files exist
178+
```bash
179+
ls -lh /usr/local/bin/pulse
180+
ls -lh /etc/node-pulse/nodepulse.yml
181+
ls -lh /var/lib/node-pulse/server_id
182+
systemctl list-unit-files | grep node-pulse
183+
```
184+
185+
### Check service status
186+
```bash
187+
sudo pulse service status
188+
systemctl status node-pulse
189+
systemctl status node-pulse-updater.timer
190+
```
191+
192+
### View logs
193+
```bash
194+
# If logging to file
195+
sudo tail -f /var/log/node-pulse/agent.log
196+
197+
# If using systemd (default: stdout)
198+
sudo journalctl -u node-pulse -f
199+
```
200+
201+
## Security Considerations
202+
203+
1. **Server ID file** (`/var/lib/node-pulse/server_id`) has restrictive permissions (0600) to prevent unauthorized access
204+
2. **Config file** can contain sensitive endpoint URLs - ensure proper file permissions
205+
3. **Binary** runs as root when using systemd service (required for system metrics collection)
206+
4. **Auto-updater** runs as root - only downloads from official GitHub releases with signature verification
207+
208+
## See Also
209+
210+
- [README.md](README.md) - Main documentation
211+
- [Agent Configuration](https://docs.nodepulse.io/agent/configuration)
212+
- [Systemd Service Management](https://docs.nodepulse.io/agent/systemd)

0 commit comments

Comments
 (0)