Skip to content

Commit ac11910

Browse files
claudeclaude
committed
add CLAUDE.md with codebase documentation for AI assistants
1 parent 185b5c8 commit ac11910

1 file changed

Lines changed: 201 additions & 0 deletions

File tree

‎CLAUDE.md‎

Lines changed: 201 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,201 @@
1+
# CLAUDE.md - AI Assistant Guide for docker-smokeping
2+
3+
## Project Overview
4+
5+
This repository contains the **LinuxServer.io Docker image for Smokeping**, a network latency monitoring and graphing application. Smokeping tracks network latency for various hosts and presents data visually through a web interface.
6+
7+
- **Application**: [Smokeping](http://oss.oetiker.ch/smokeping/)
8+
- **Maintainer**: LinuxServer.io
9+
- **Docker Hub**: [linuxserver/smokeping](https://hub.docker.com/r/linuxserver/smokeping/)
10+
- **Base Image**: `lsiobase/alpine:3.6`
11+
12+
## Repository Structure
13+
14+
```
15+
docker-smokeping/
16+
├── Dockerfile # Container image definition
17+
├── README.md # User documentation
18+
├── CLAUDE.md # This file - AI assistant guide
19+
├── .github/
20+
│ ├── ISSUE_TEMPLATE.md # Issue reporting template
21+
│ └── PULL_REQUEST_TEMPLATE.md # PR submission guidelines
22+
└── root/ # Files copied into container at build
23+
├── defaults/
24+
│ ├── smokeping.conf # Default Apache site configuration
25+
│ └── smoke-conf/ # Default Smokeping application configs
26+
│ ├── Alerts # Alert configuration for packet loss
27+
│ ├── Database # RRD database settings
28+
│ ├── General # Owner, contact, CGI URL settings
29+
│ ├── Presentation # Web UI templates and charts
30+
│ ├── Probes # Probe definitions (FPing)
31+
│ ├── Slaves # Distributed slave probe settings
32+
│ ├── Targets # Hosts/URLs to monitor
33+
│ ├── pathnames # File path configuration
34+
│ └── smtp.conf # SSMTP/sendmail configuration
35+
└── etc/
36+
├── apache2/httpd.conf # Apache web server configuration
37+
├── smokeping/config # Main config (includes from /config)
38+
├── cont-init.d/
39+
│ └── 30-config # Container initialization script
40+
└── services.d/
41+
├── apache/run # Apache service supervisor script
42+
└── smokeping/run # Smokeping daemon supervisor script
43+
```
44+
45+
## Key Architecture Concepts
46+
47+
### Container Runtime Flow
48+
49+
1. **Initialization** (`root/etc/cont-init.d/30-config`):
50+
- Creates required directories (`/config/site-confs`, `/run/apache2`, `/var/cache/smokeping`)
51+
- Copies default configs from `/defaults/smoke-conf/` to `/config/` (first run only)
52+
- Creates symlinks for web application and cache
53+
- Sets permissions for `abc` user
54+
55+
2. **Service Management** (s6 overlay):
56+
- **Apache**: Serves web UI on port 80 with CGI support
57+
- **Smokeping**: Runs as daemon under `abc` user
58+
59+
### LinuxServer.io Conventions
60+
61+
- **User `abc`**: Standard unprivileged user for running services
62+
- **PUID/PGID**: Environment variables for host permission mapping
63+
- **Volume separation**: `/config` for configuration, `/data` for persistent data
64+
- **First-run defaults**: Configs copied only if not present (preserves customizations)
65+
66+
## Dockerfile Anatomy
67+
68+
```dockerfile
69+
FROM lsiobase/alpine:3.6 # Alpine base with s6 overlay
70+
71+
# Packages: apache2, smokeping, ssmtp, curl, sudo, ttf-dejavu
72+
# Special: abc user gets sudo access to traceroute
73+
# Fix: cropper.js path correction in basepage.html
74+
75+
COPY root/ / # Copy all configs and scripts
76+
EXPOSE 80 # Web UI port
77+
VOLUME /config /data # Persistent storage
78+
```
79+
80+
## Development Guidelines
81+
82+
### Making Changes
83+
84+
1. **Dockerfile changes**: Keep minimal, consolidate RUN layers
85+
2. **Default configs** (`root/defaults/`): Update for new features
86+
3. **Init scripts** (`root/etc/cont-init.d/`): Use `#!/usr/bin/with-contenv bash`
87+
4. **Service scripts** (`root/etc/services.d/`): Run with `exec` for proper signal handling
88+
89+
### Testing Locally
90+
91+
```bash
92+
# Build the image
93+
docker build -t smokeping-test .
94+
95+
# Run for testing
96+
docker run -d \
97+
--name smokeping-test \
98+
-p 8080:80 \
99+
-e PUID=$(id -u) \
100+
-e PGID=$(id -g) \
101+
-e TZ=America/New_York \
102+
-v $(pwd)/test-config:/config \
103+
-v $(pwd)/test-data:/data \
104+
smokeping-test
105+
106+
# Access at http://localhost:8080/smokeping/smokeping.cgi
107+
```
108+
109+
### Configuration Files
110+
111+
| File | Purpose | User Editable |
112+
|------|---------|---------------|
113+
| `/config/Targets` | Hosts to monitor | Yes |
114+
| `/config/General` | Owner, contact info | Yes |
115+
| `/config/Alerts` | Alert rules | Yes |
116+
| `/config/Database` | RRD settings | Yes |
117+
| `/config/Presentation` | Web UI theming | Yes |
118+
| `/config/Probes` | Probe binaries | Rarely |
119+
| `/config/site-confs/smokeping.conf` | Apache config | Advanced |
120+
121+
### Image Tags
122+
123+
- **`latest`**: Standard version with IPv6 support
124+
- **`unraid`**: IPv6-disabled variant for older Unraid (pre-6.3x)
125+
126+
## Code Conventions
127+
128+
### Shell Scripts
129+
130+
- Use `#!/usr/bin/with-contenv bash` for s6 environment access
131+
- Service scripts must use `exec` to replace shell process
132+
- Check for existence before creating files/symlinks: `[[ ! -e path ]] && ...`
133+
134+
### Git Workflow
135+
136+
- Create feature branches for changes
137+
- Reference issues in PR descriptions: `closes #<issue number>`
138+
- Follow LinuxServer.io commit message style (lowercase, concise)
139+
140+
### Commit History Patterns
141+
142+
Recent commits show:
143+
- Base image updates: "Rebase to alpine X.X"
144+
- Feature additions: "Add <package> for <reason>"
145+
- Bug fixes: "Fix <issue>, thanks <contributor>"
146+
- Documentation: "Update README"
147+
148+
## Important Paths (Inside Container)
149+
150+
| Path | Purpose |
151+
|------|---------|
152+
| `/config` | User configuration (mounted volume) |
153+
| `/data` | RRD databases and graphs (mounted volume) |
154+
| `/etc/smokeping/config` | Main config that includes from /config |
155+
| `/usr/share/webapps/smokeping` | Web application files |
156+
| `/var/cache/smokeping` | Smokeping cache directory |
157+
| `/var/www/localhost/smokeping` | Symlink to web app |
158+
159+
## Environment Variables
160+
161+
| Variable | Purpose | Example |
162+
|----------|---------|---------|
163+
| `PUID` | User ID for file ownership | `1000` |
164+
| `PGID` | Group ID for file ownership | `1000` |
165+
| `TZ` | Timezone | `Europe/London` |
166+
167+
## Troubleshooting
168+
169+
### Common Issues
170+
171+
1. **Permission errors**: Check PUID/PGID match host user owning volumes
172+
2. **IPv6 failures**: Use `:unraid` tag on hosts without IPv6
173+
3. **Config not loading**: Ensure config files exist in `/config/`
174+
4. **Graphs not generating**: Wait 10+ minutes, check `/data` permissions
175+
176+
### Debugging Commands
177+
178+
```bash
179+
# View container logs
180+
docker logs -f smokeping
181+
182+
# Shell into running container
183+
docker exec -it smokeping /bin/bash
184+
185+
# Check version
186+
docker inspect -f '{{ index .Config.Labels "build_version" }}' smokeping
187+
```
188+
189+
## CI/CD
190+
191+
- Builds handled by LinuxServer.io CI pipeline
192+
- Images tagged with `build_version` label containing version and build date
193+
- Published to Docker Hub automatically
194+
195+
## Contributing
196+
197+
1. Fork the repository
198+
2. Create a feature branch (not from master)
199+
3. Make changes following conventions above
200+
4. Submit PR referencing any related issues
201+
5. Include links to patches/files used in PR description

0 commit comments

Comments
 (0)