docs: add comprehensive PRIVACY.md, link from README

- New docs/PRIVACY.md with full telemetry documentation: consent model, what's collected (per type), what's NOT collected, data processing, GDPR legal basis, how to opt out - README: link to PRIVACY.md, ROPA.md, TOMS.md in Privacy section
2026-06-29 21:33:24 -04:00 · 2026-02-17 17:10:43 +01:00
parent 5dbcabdd94
commit 345c5d8180
2 changed files with 160 additions and 0 deletions
@@ -98,6 +98,11 @@ This service is designed with privacy in mind and is **GDPR/DSGVO compliant**:
 - ✅ **No tracking** - Session IDs are randomly generated and cannot be linked to users
 - ✅ **No third parties** - Data is only stored in our self-hosted PocketBase instance

+For full details, see:
+- **[Privacy & Telemetry Documentation](docs/PRIVACY.md)** — What we collect, how, and why
+- **[Records of Processing Activities (ROPA)](docs/ROPA.md)** — GDPR Art. 30
+- **[Technical & Organizational Measures (TOMS)](docs/TOMS.md)** — GDPR Art. 32
+
 ## License

 MIT License - see [LICENSE](LICENSE) file.
@@ -0,0 +1,155 @@
+# Privacy & Telemetry Documentation
+
+**Community-Scripts Telemetry Service**
+
+---
+
+## Overview
+
+The [Community-Scripts](https://github.com/community-scripts/ProxmoxVE) project includes an **opt-in** telemetry system that collects anonymous technical data when users install applications via Proxmox VE Helper-Scripts. This document explains what is collected, how it is processed, and how users can control it.
+
+**Dashboard:** [https://telemetry.community-scripts.org](https://telemetry.community-scripts.org)
+
+---
+
+## Consent & Opt-In
+
+Telemetry is **strictly opt-in**. On first use, a dialog asks users whether they want to share anonymous data:
+
+- **No option is pre-selected** — users must actively choose
+- Pressing Exit/Cancel defaults to **opt-out**
+- The choice is persisted in `/usr/local/community-scripts/diagnostics`
+- Users can change their preference at any time via the **Settings menu** during installation or by editing the config file directly
+
+### Changing Your Preference
+
+**Via Settings menu:** During any script installation, navigate to the Settings menu and select "Telemetry".
+
+**Via command line (on PVE host):**
+```bash
+# Opt out
+sed -i 's/^DIAGNOSTICS=.*/DIAGNOSTICS=no/' /usr/local/community-scripts/diagnostics
+
+# Opt in
+sed -i 's/^DIAGNOSTICS=.*/DIAGNOSTICS=yes/' /usr/local/community-scripts/diagnostics
+```
+
+**Inside a container (for addon scripts):**
+```bash
+# The same file exists inside containers created after opting in
+sed -i 's/^DIAGNOSTICS=.*/DIAGNOSTICS=no/' /usr/local/community-scripts/diagnostics
+```
+
+> **Note:** Changing the setting on the host affects all **new** containers. Existing containers retain the preference set at creation time.
+
+---
+
+## What We Collect
+
+All data is **purely technical** and **anonymous**. No field can identify a natural person.
+
+### Container & VM Installations (type: `lxc`, `vm`)
+
+| Field | Example | Purpose |
+|-------|---------|---------|
+| `nsapp` | `docker`, `homeassistant` | Which application was installed |
+| `status` | `success`, `failed` | Whether the installation succeeded |
+| `exit_code` | `0`, `1`, `130` | Exit code for error categorization |
+| `error` | `dpkg: error ...` | Truncated error message (failed installs only) |
+| `ct_type` | `1` (unprivileged) | Container privilege type |
+| `disk_size` | `8` | Disk size in GB |
+| `core_count` | `2` | Number of CPU cores |
+| `ram_size` | `2048` | RAM in MiB |
+| `os_type` | `debian` | Operating system |
+| `os_version` | `12` | OS version |
+| `pve_version` | `8.3` | Proxmox VE version |
+| `method` | `default`, `advanced` | Installation method used |
+| `install_duration` | `45` | Duration in seconds |
+| `random_id` | `a1b2c3d4-...` | Random UUID (not linked to user/system) |
+| `execution_id` | `a1b2c3d4-...` | Unique execution identifier |
+
+### PVE Tools (type: `pve`)
+
+| Field | Example | Purpose |
+|-------|---------|---------|
+| `nsapp` | `post-pve-install`, `microcode` | Which tool was executed |
+| `status` | `success`, `failed` | Execution result |
+| `exit_code` | `0` | Exit code |
+| `pve_version` | `8.3` | Proxmox VE version |
+| `install_duration` | `12` | Duration in seconds |
+
+### Addon Scripts (type: `addon`)
+
+| Field | Example | Purpose |
+|-------|---------|---------|
+| `nsapp` | `filebrowser`, `netdata` | Which addon was installed |
+| `status` | `success`, `failed` | Installation result |
+| `exit_code` | `0` | Exit code |
+| `os_type` | `debian` | Container OS |
+| `os_version` | `12` | Container OS version |
+| `install_duration` | `30` | Duration in seconds |
+
+---
+
+## What We Do NOT Collect
+
+- **No IP addresses** — not logged, not stored, not forwarded
+- **No hostnames** or domain names
+- **No MAC addresses** or hardware serial numbers
+- **No user credentials**, passwords, or API tokens
+- **No network configuration** or internal IP addresses
+- **No file paths**, directory listings, or file contents
+- **No personal data** of any kind (GDPR Art. 4 Nr. 1)
+
+---
+
+## How Data Is Used
+
+The collected data serves the following purposes **exclusively**:
+
+1. **Script Quality** — Identify scripts with high failure rates and fix them
+2. **Popularity Ranking** — Understand which scripts are most used to prioritize maintenance
+3. **Resource Trends** — Analyze typical CPU, RAM, and disk allocations
+4. **OS Compatibility** — Track which OS versions are in use
+5. **Error Analysis** — Categorize common failure patterns for faster debugging
+
+All aggregated statistics are publicly visible on the [dashboard](https://telemetry.community-scripts.org).
+
+---
+
+## Data Processing & Storage
+
+| Aspect | Details |
+|--------|---------|
+| **Processor** | Self-hosted on IONOS VPS in Germany (Frankfurt/Berlin) |
+| **Database** | PocketBase (SQLite-based, self-hosted) |
+| **Retention** | Data is stored indefinitely for trend analysis |
+| **Encryption** | TLS 1.3 in transit, encrypted storage at rest |
+| **Access** | Write: telemetry service only. Read: aggregated dashboard (public) |
+| **Third parties** | None — no data is shared with or sold to third parties |
+| **Backups** | Automated, encrypted, same data center |
+
+---
+
+## Legal Basis (GDPR)
+
+**Art. 6(1)(f) GDPR — Legitimate Interest**
+
+The legitimate interest lies in improving open-source software for the community. Since:
+- No personal data is collected (Art. 4 Nr. 1 GDPR)
+- Data collection is opt-in with active consent
+- Users can withdraw at any time
+- All data is anonymous and cannot identify individuals
+
+the processing is GDPR-compliant. For detailed documentation, see:
+- [Records of Processing Activities (ROPA)](ROPA.md) — Art. 30 GDPR
+- [Technical & Organizational Measures (TOMS)](TOMS.md) — Art. 32 GDPR
+
+---
+
+## Contact & Issues
+
+- **Questions:** Open an issue at [telemetry-service](https://github.com/community-scripts/telemetry-service/issues)
+- **Privacy concerns:** Open an issue with the `privacy` label
+- **Source code:** Fully open source — review the [service implementation](../service.go)
+- **Discussion:** [ProxmoxVE Discussions](https://github.com/community-scripts/ProxmoxVE/discussions)