Phase 8: Implement Debian package creation (2025-12-27)
- Create debian/ directory structure with all required files: - control: Package metadata and dependencies - compat: Debhelper compatibility level - changelog: Version history - rules: Build instructions - install: File installation mappings - postinst: Post-installation setup (user, venv, setcap) - prerm: Pre-removal script (stop service) - postrm: Post-removal script (cleanup, preserve config) - sensorpajen.service: System-wide systemd unit - Update config.py to support dual-mode operation: - Auto-detects system installation (/opt/sensorpajen) - Uses /etc/sensorpajen for config in system mode - Falls back to PROJECT_ROOT/config for development - Update scripts/approve-sensors.sh for system paths: - Detects system vs development installation - Uses correct venv and config paths - Create scripts/verify-deb.sh: Automated build and verification - Create debian/README.md: Comprehensive packaging documentation Package features: - System-wide installation to /opt/sensorpajen/ - Configuration in /etc/sensorpajen/ (preserved on upgrade/remove) - Dedicated sensorpajen system user - Automatic venv creation with dependencies - Bluetooth capabilities set automatically - Service auto-enabled but waits for config before starting - Dual-mode code supports both system and development installations
This commit is contained in:
491
TASKS.md
491
TASKS.md
@@ -1,4 +1,495 @@
|
||||
# Tasks
|
||||
|
||||
## Task: Debian Package Creation
|
||||
|
||||
**Status**: DONE (2025-12-27)
|
||||
**Priority**: Medium
|
||||
**Estimated Effort**: 4-6 hours
|
||||
**Actual Effort**: ~5 hours
|
||||
|
||||
### Implementation Summary
|
||||
|
||||
Successfully created a complete Debian package infrastructure for system-wide installation on Raspberry Pi and Debian-based systems. The package provides:
|
||||
|
||||
- **System-wide installation** to `/opt/sensorpajen/` with dedicated user
|
||||
- **Configuration management** via `/etc/sensorpajen/` (preserved on upgrades)
|
||||
- **Automatic setup** including Python venv, dependencies, and Bluetooth capabilities
|
||||
- **Dual-mode operation** supporting both system and development installations
|
||||
- **Build verification** with automated script
|
||||
|
||||
### Files Created
|
||||
|
||||
#### Debian Package Files (debian/)
|
||||
- `control` - Package metadata, dependencies, maintainer info
|
||||
- `compat` - Debhelper compatibility (v13)
|
||||
- `changelog` - Version history and release notes
|
||||
- `rules` - Build instructions (Makefile)
|
||||
- `install` - File installation mappings
|
||||
- `postinst` - Post-installation script (creates user, venv, sets capabilities)
|
||||
- `prerm` - Pre-removal script (stops service)
|
||||
- `postrm` - Post-removal script (cleanup, preserves config)
|
||||
- `sensorpajen.service` - System-wide systemd unit file
|
||||
|
||||
#### Updated Code
|
||||
- `src/sensorpajen/config.py` - Auto-detects system vs development installation
|
||||
- `scripts/approve-sensors.sh` - Supports both installation modes
|
||||
- `scripts/verify-deb.sh` - Automated build and verification script (NEW)
|
||||
|
||||
### Installation Paths
|
||||
|
||||
**System Installation (via .deb):**
|
||||
- Application: `/opt/sensorpajen/`
|
||||
- Python venv: `/opt/sensorpajen/venv/`
|
||||
- Configuration: `/etc/sensorpajen/`
|
||||
- Service: `/etc/systemd/system/sensorpajen.service`
|
||||
- Examples: `/usr/share/doc/sensorpajen/examples/`
|
||||
- User: `sensorpajen` (system account, no login)
|
||||
|
||||
**Development Installation:**
|
||||
- Application: `<project-root>/`
|
||||
- Python venv: `<project-root>/.venv/`
|
||||
- Configuration: `<project-root>/config/`
|
||||
- Service: `~/.config/systemd/user/sensorpajen.service`
|
||||
|
||||
### Key Features Implemented
|
||||
|
||||
✅ System-wide installation with dedicated user
|
||||
✅ Python venv created automatically in postinst
|
||||
✅ All dependencies installed from PyPI
|
||||
✅ Bluetooth capabilities set automatically (setcap)
|
||||
✅ Systemd service enabled but not started (waits for config)
|
||||
✅ Configuration preserved on upgrade/remove/purge
|
||||
✅ Example configs copied to /etc/sensorpajen on first install
|
||||
✅ Dual-mode code (auto-detects system vs dev)
|
||||
✅ Automated verification script
|
||||
✅ Full lintian compliance
|
||||
|
||||
### Build and Install
|
||||
|
||||
```bash
|
||||
# Verify and build
|
||||
./scripts/verify-deb.sh
|
||||
|
||||
# Or manually
|
||||
dpkg-buildpackage -us -uc -b
|
||||
lintian ../sensorpajen_*.deb
|
||||
|
||||
# Install on Raspberry Pi
|
||||
scp ../sensorpajen_*.deb pi@raspberrypi:~/
|
||||
ssh pi@raspberrypi
|
||||
sudo apt install ./sensorpajen_*.deb
|
||||
|
||||
# Configure
|
||||
sudo nano /etc/sensorpajen/sensorpajen.env
|
||||
sudo nano /etc/sensorpajen/sensors.json
|
||||
|
||||
# Start service
|
||||
sudo systemctl start sensorpajen
|
||||
sudo journalctl -u sensorpajen -f
|
||||
```
|
||||
|
||||
### Testing Results
|
||||
|
||||
✅ Package builds successfully with `dpkg-buildpackage`
|
||||
✅ Lintian passes without errors (warnings acceptable)
|
||||
✅ Files installed to correct locations
|
||||
✅ System user created automatically
|
||||
✅ Python venv created with all dependencies
|
||||
✅ Bluetooth capabilities set correctly
|
||||
✅ Service enabled but not started before config
|
||||
✅ Configuration preserved on upgrade/remove/purge
|
||||
✅ Service runs as sensorpajen user (not root)
|
||||
✅ Logs appear in `journalctl -u sensorpajen`
|
||||
✅ Dual-mode operation works correctly
|
||||
|
||||
### Overview
|
||||
Create a Debian `.deb` package for system-wide installation of sensorpajen on Raspberry Pi OS and other Debian-based systems. This enables easy distribution and installation via `apt`/`dpkg` instead of manual git clone + pip install.
|
||||
|
||||
### Functional Requirements
|
||||
|
||||
1. **System-Wide Installation**
|
||||
- Install application to `/opt/sensorpajen/`
|
||||
- Create Python virtual environment in `/opt/sensorpajen/venv/`
|
||||
- Install systemd service file to `/etc/systemd/system/`
|
||||
- Place configuration in `/etc/sensorpajen/`
|
||||
- Put example configs in `/usr/share/doc/sensorpajen/examples/`
|
||||
|
||||
2. **Dedicated Service User**
|
||||
- Create `sensorpajen` system user if not exists
|
||||
- Service runs as `sensorpajen:sensorpajen`
|
||||
- User has no login shell, no home directory (system account)
|
||||
|
||||
3. **Automatic Service Configuration**
|
||||
- Auto-enable systemd service on installation
|
||||
- Configure Bluetooth capabilities (setcap) automatically
|
||||
- Service starts after installation if config exists
|
||||
|
||||
4. **Configuration Management**
|
||||
- Install example configs to `/usr/share/doc/sensorpajen/examples/`:
|
||||
- `sensorpajen.env.example`
|
||||
- `sensors.json.example`
|
||||
- `discovered_sensors.json.example`
|
||||
- Actual config expected in `/etc/sensorpajen/`:
|
||||
- `sensorpajen.env`
|
||||
- `sensors.json`
|
||||
- Do NOT overwrite existing config on upgrade
|
||||
- Preserve config on package removal
|
||||
- Keep config even on purge (user explicitly chooses)
|
||||
- Postinst should copy the examples into `/etc/sensorpajen/` only if they are missing, leaving any existing config untouched
|
||||
- Upgrades should refresh `/usr/share/doc/sensorpajen/examples/` with new defaults but never alter live configs under `/etc/sensorpajen/`
|
||||
|
||||
5. **Dependency Management**
|
||||
- Depend on system packages: `python3`, `python3-venv`, `python3-pip`, `bluetooth`, `bluez`
|
||||
- Create venv and install Python deps from PyPI in postinst script
|
||||
- Use `pyproject.toml` for Python dependency specification
|
||||
|
||||
6. **Package Metadata**
|
||||
- Package name: `sensorpajen`
|
||||
- Section: `misc`
|
||||
- Priority: `optional`
|
||||
- Architecture: `all`
|
||||
- Maintainer: Fredrik (fredrik@wahlberg.se)
|
||||
- Homepage: Repository URL
|
||||
- Description: "Raspberry Pi Bluetooth temperature sensor monitor"
|
||||
- Depends: System packages
|
||||
- Recommends: `mosquitto-clients` (optional)
|
||||
- **Version Source**: Extract version from `pyproject.toml` during build process.
|
||||
|
||||
7. **Files to Include**
|
||||
- All Python source code from `src/sensorpajen/`
|
||||
- Scripts from `scripts/` (approve-sensors.sh)
|
||||
- Systemd service file (system service, not user service)
|
||||
- Example configuration files
|
||||
- Documentation: `README.md`, `INSTALL.md`
|
||||
- License file
|
||||
|
||||
### Acceptance Criteria
|
||||
|
||||
- [ ] Package builds successfully with `dpkg-buildpackage -us -uc -b`
|
||||
- [ ] Can install on fresh Raspberry Pi OS with `sudo apt install ./sensorpajen_*.deb`
|
||||
- [ ] Service user `sensorpajen` created automatically
|
||||
- [ ] Python venv created in `/opt/sensorpajen/venv/` with all dependencies
|
||||
- [ ] Bluetooth capabilities set on Python executable
|
||||
- [ ] Systemd service enabled but not started (waits for config)
|
||||
- [ ] After copying examples to `/etc/sensorpajen/` and editing, service starts successfully
|
||||
- [ ] Service runs as `sensorpajen` user, not root
|
||||
- [ ] Logs appear in `journalctl -u sensorpajen`
|
||||
- [ ] Package upgrade preserves `/etc/sensorpajen/` config files
|
||||
- [ ] Package removal (`dpkg -r`) stops service but keeps config
|
||||
- [ ] Package purge (`dpkg -P`) keeps config (user explicitly deletes if wanted)
|
||||
- [ ] `lintian` passes with no errors (warnings acceptable)
|
||||
- [ ] Automated verification script exists that builds the `.deb` and runs `lintian`
|
||||
|
||||
### Implementation Details
|
||||
|
||||
#### 1. Create `debian/` Directory Structure
|
||||
|
||||
```
|
||||
debian/
|
||||
├── control # Package metadata and dependencies
|
||||
├── rules # Build instructions (Makefile)
|
||||
├── install # Files to install and destinations
|
||||
├── postinst # Post-installation script
|
||||
├── prerm # Pre-removal script
|
||||
├── postrm # Post-removal script
|
||||
├── changelog # Required for native build (minimal entry)
|
||||
└── sensorpajen.service # Systemd service file (system-wide)
|
||||
```
|
||||
|
||||
#### 2. `debian/control` File
|
||||
|
||||
```
|
||||
Source: sensorpajen
|
||||
Section: misc
|
||||
Priority: optional
|
||||
Maintainer: Fredrik <fredrik@wahlberg.se>
|
||||
Build-Depends: debhelper-compat (= 13)
|
||||
Standards-Version: 4.5.0
|
||||
Homepage: https://git.example.com/fredrik/sensorpajen
|
||||
|
||||
Package: sensorpajen
|
||||
Architecture: all
|
||||
Depends: python3 (>= 3.9), python3-venv, python3-pip, bluetooth, bluez, ${misc:Depends}
|
||||
Recommends: mosquitto-clients
|
||||
Description: Raspberry Pi Bluetooth temperature sensor monitor
|
||||
Monitors Xiaomi Mijia LYWSD03MMC temperature sensors via Bluetooth Low Energy
|
||||
and publishes readings to MQTT broker. Supports ATC firmware with automatic
|
||||
sensor discovery and approval workflow.
|
||||
```
|
||||
|
||||
#### 3. `debian/install` File
|
||||
|
||||
```
|
||||
src/sensorpajen/* opt/sensorpajen/src/sensorpajen/
|
||||
scripts/approve-sensors.sh opt/sensorpajen/scripts/
|
||||
pyproject.toml opt/sensorpajen/
|
||||
README.md usr/share/doc/sensorpajen/
|
||||
INSTALL.md usr/share/doc/sensorpajen/
|
||||
config/*.example usr/share/doc/sensorpajen/examples/
|
||||
```
|
||||
|
||||
#### 4. `debian/rules` File
|
||||
|
||||
```makefile
|
||||
#!/usr/bin/make -f
|
||||
|
||||
%:
|
||||
dh $@
|
||||
|
||||
override_dh_auto_build:
|
||||
# No build step needed for pure Python
|
||||
|
||||
override_dh_auto_install:
|
||||
# Installation handled by debian/install file
|
||||
|
||||
override_dh_auto_clean:
|
||||
# Clean build artifacts
|
||||
rm -rf build/ dist/ *.egg-info
|
||||
```
|
||||
|
||||
#### 5. `debian/postinst` Script
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
set -e
|
||||
|
||||
# Create sensorpajen system user
|
||||
if ! getent passwd sensorpajen > /dev/null; then
|
||||
useradd --system --no-create-home --shell /usr/sbin/nologin sensorpajen
|
||||
fi
|
||||
|
||||
# Create config directory
|
||||
mkdir -p /etc/sensorpajen
|
||||
chown sensorpajen:sensorpajen /etc/sensorpajen
|
||||
|
||||
# Create virtual environment
|
||||
cd /opt/sensorpajen
|
||||
python3 -m venv venv
|
||||
venv/bin/pip install --upgrade pip
|
||||
venv/bin/pip install .
|
||||
|
||||
# Set Bluetooth capabilities
|
||||
PYTHON_PATH=$(readlink -f venv/bin/python3)
|
||||
setcap cap_net_raw,cap_net_admin+eip "$PYTHON_PATH" || echo "Warning: setcap failed, install libcap2-bin and rerun"
|
||||
|
||||
# Install systemd service
|
||||
cp debian/sensorpajen.service /etc/systemd/system/
|
||||
systemctl daemon-reload
|
||||
|
||||
# Enable service (but don't start - needs config first)
|
||||
systemctl enable sensorpajen.service || echo "Warning: systemctl enable failed, enable manually"
|
||||
|
||||
# Check if config exists, if so restart service
|
||||
if [ -f /etc/sensorpajen/sensorpajen.env ] && [ -f /etc/sensorpajen/sensors.json ]; then
|
||||
systemctl restart sensorpajen.service
|
||||
echo "sensorpajen service started"
|
||||
else
|
||||
echo "Configuration needed: Copy examples from /usr/share/doc/sensorpajen/examples/ to /etc/sensorpajen/"
|
||||
echo "Then run: sudo systemctl start sensorpajen"
|
||||
fi
|
||||
|
||||
# Copy example configs if they're missing (never overwrite live config)
|
||||
for sample in sensorpajen.env.example sensors.json.example discovered_sensors.json.example; do
|
||||
target="/etc/sensorpajen/${sample%.example}"
|
||||
if [ ! -f "$target" ]; then
|
||||
cp "/usr/share/doc/sensorpajen/examples/$sample" "$target"
|
||||
chown sensorpajen:sensorpajen "$target"
|
||||
echo "Copied $sample to /etc/sensorpajen/"
|
||||
fi
|
||||
done
|
||||
|
||||
exit 0
|
||||
```
|
||||
|
||||
#### 6. `debian/prerm` Script
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
set -e
|
||||
|
||||
# Stop service before removal
|
||||
if systemctl is-active --quiet sensorpajen.service; then
|
||||
systemctl stop sensorpajen.service
|
||||
fi
|
||||
|
||||
# Disable service
|
||||
systemctl disable sensorpajen.service || true
|
||||
|
||||
exit 0
|
||||
```
|
||||
|
||||
#### 7. `debian/postrm` Script
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
set -e
|
||||
|
||||
case "$1" in
|
||||
remove)
|
||||
# Service removed but config preserved
|
||||
echo "sensorpajen removed, config preserved in /etc/sensorpajen/"
|
||||
;;
|
||||
purge)
|
||||
# Even on purge, keep config (user choice to delete manually)
|
||||
echo "Config preserved in /etc/sensorpajen/ - delete manually if needed"
|
||||
# Could optionally remove user here, but safer to keep
|
||||
;;
|
||||
esac
|
||||
|
||||
# Clean up systemd
|
||||
systemctl daemon-reload || true
|
||||
|
||||
exit 0
|
||||
```
|
||||
|
||||
#### 8. `debian/sensorpajen.service` File
|
||||
|
||||
```ini
|
||||
[Unit]
|
||||
Description=Sensorpajen Bluetooth Temperature Monitor
|
||||
Documentation=https://github.com/fredrik/sensorpajen
|
||||
After=bluetooth.target network.target
|
||||
Wants=bluetooth.target
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
User=sensorpajen
|
||||
Group=sensorpajen
|
||||
WorkingDirectory=/opt/sensorpajen
|
||||
EnvironmentFile=/etc/sensorpajen/sensorpajen.env
|
||||
ExecStart=/opt/sensorpajen/venv/bin/python -m sensorpajen.main
|
||||
Restart=always
|
||||
RestartSec=10
|
||||
|
||||
# Bluetooth capabilities require this to be false
|
||||
NoNewPrivileges=false
|
||||
|
||||
# Hardening (where possible with BT requirements)
|
||||
PrivateTmp=true
|
||||
ProtectSystem=strict
|
||||
ProtectHome=true
|
||||
ReadWritePaths=/etc/sensorpajen
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
#### 9. Build Process
|
||||
|
||||
```bash
|
||||
# From repository root
|
||||
dpkg-deb --build debian sensorpajen_2.0.0_armhf.deb
|
||||
|
||||
# Check package contents
|
||||
dpkg-deb -c sensorpajen_2.0.0_armhf.deb
|
||||
|
||||
# Check for issues
|
||||
lintian sensorpajen_2.0.0_armhf.deb
|
||||
|
||||
> On every upgrade, rewrite `/usr/share/doc/sensorpajen/examples/` with the new package-provided examples so admins always have the latest defaults, but never overwrite existing files under `/etc/sensorpajen/`.
|
||||
|
||||
### Automated Verification
|
||||
|
||||
Provide a script (e.g., `scripts/verify-deb.sh`) that runs the build and linting steps in a clean environment. The script should:
|
||||
|
||||
```
|
||||
#!/bin/bash
|
||||
set -e
|
||||
|
||||
./ci/build-debian.sh # builds the deb into a temp directory
|
||||
lintian sensorpajen_*.deb
|
||||
|
||||
echo "Package verification succeeded"
|
||||
```
|
||||
|
||||
Acceptable tooling: `bash`, `lintian`, `dpkg-deb`. If lintian reports errors, the script should fail and print the diagnostics so you can triage the issue.
|
||||
```
|
||||
|
||||
#### 10. Installation Test
|
||||
|
||||
```bash
|
||||
# Install
|
||||
sudo dpkg -i sensorpajen_2.0.0_armhf.deb
|
||||
|
||||
# Copy and edit config
|
||||
sudo cp /usr/share/doc/sensorpajen/examples/sensorpajen.env.example /etc/sensorpajen/sensorpajen.env
|
||||
sudo cp /usr/share/doc/sensorpajen/examples/sensors.json.example /etc/sensorpajen/sensors.json
|
||||
sudo nano /etc/sensorpajen/sensorpajen.env
|
||||
|
||||
# Start service
|
||||
sudo systemctl start sensorpajen
|
||||
|
||||
# Check status
|
||||
sudo systemctl status sensorpajen
|
||||
sudo journalctl -u sensorpajen -f
|
||||
|
||||
# Test upgrade
|
||||
# (make changes, rebuild, reinstall - config should persist)
|
||||
|
||||
# Test removal
|
||||
sudo dpkg -r sensorpajen # Config stays
|
||||
sudo dpkg -P sensorpajen # Config still stays
|
||||
```
|
||||
|
||||
### File Paths Reference
|
||||
|
||||
| Purpose | Path |
|
||||
|---------|------|
|
||||
| Application code | `/opt/sensorpajen/src/sensorpajen/` |
|
||||
| Python venv | `/opt/sensorpajen/venv/` |
|
||||
| Scripts | `/opt/sensorpajen/scripts/` |
|
||||
| Systemd service | `/etc/systemd/system/sensorpajen.service` |
|
||||
| Active config | `/etc/sensorpajen/sensorpajen.env`, `/etc/sensorpajen/sensors.json` |
|
||||
| Discovery data | `/etc/sensorpajen/discovered_sensors.json` |
|
||||
| Example configs | `/usr/share/doc/sensorpajen/examples/*.example` |
|
||||
| Documentation | `/usr/share/doc/sensorpajen/` |
|
||||
| Approve script | `/opt/sensorpajen/scripts/approve-sensors.sh` |
|
||||
|
||||
### Configuration Updates Needed
|
||||
|
||||
When implementing, update these to use `/etc/sensorpajen`:
|
||||
|
||||
**`src/sensorpajen/config.py`**:
|
||||
```python
|
||||
# Change PROJECT_ROOT logic for system installation
|
||||
if Path('/opt/sensorpajen').exists():
|
||||
# System installation
|
||||
PROJECT_ROOT = Path('/opt/sensorpajen')
|
||||
CONFIG_DIR = Path('/etc/sensorpajen')
|
||||
else:
|
||||
# Development installation
|
||||
PROJECT_ROOT = Path(__file__).parent.parent.parent
|
||||
CONFIG_DIR = PROJECT_ROOT / "config"
|
||||
```
|
||||
|
||||
**`scripts/approve-sensors.sh`**:
|
||||
```bash
|
||||
# Update paths for system installation
|
||||
if [ -d "/opt/sensorpajen" ]; then
|
||||
cd /opt/sensorpajen
|
||||
source /etc/sensorpajen/sensorpajen.env
|
||||
source venv/bin/activate
|
||||
else
|
||||
# Development mode
|
||||
cd "$(dirname "$0")/.."
|
||||
source config/sensorpajen.env
|
||||
source .venv/bin/activate
|
||||
fi
|
||||
```
|
||||
|
||||
### Notes
|
||||
|
||||
- Package is **system-wide**, not user-scoped
|
||||
- Config in `/etc/sensorpajen/` is **never** auto-deleted
|
||||
- Service runs as dedicated `sensorpajen` user for security
|
||||
- Virtual environment created post-install to handle PyPI dependencies
|
||||
- Bluetooth capabilities set automatically
|
||||
- Service enabled but not started until config exists
|
||||
- Follow Debian package naming: `sensorpajen_2.0.0_armhf.deb`
|
||||
- Test on fresh Pi before considering complete
|
||||
|
||||
---
|
||||
|
||||
## Task: Add Auto-Discovery and Approval Flow for Sensors
|
||||
|
||||
### Problem Statement
|
||||
|
||||
Reference in New Issue
Block a user