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:
353
debian/README.md
vendored
Normal file
353
debian/README.md
vendored
Normal file
@@ -0,0 +1,353 @@
|
||||
# Debian Package Build Guide
|
||||
|
||||
This directory contains the Debian packaging files for **sensorpajen**, a Bluetooth temperature sensor monitor for Raspberry Pi.
|
||||
|
||||
## Overview
|
||||
|
||||
The Debian package installs sensorpajen as a **system-wide service** with:
|
||||
|
||||
- Installation to `/opt/sensorpajen/`
|
||||
- Configuration in `/etc/sensorpajen/`
|
||||
- Dedicated `sensorpajen` system user
|
||||
- Systemd service integration
|
||||
- Automatic Python virtual environment setup
|
||||
- Bluetooth capability configuration
|
||||
|
||||
## Prerequisites
|
||||
|
||||
### Required Packages
|
||||
|
||||
```bash
|
||||
sudo apt install \
|
||||
debhelper \
|
||||
dpkg-dev \
|
||||
python3 \
|
||||
python3-venv \
|
||||
python3-pip
|
||||
```
|
||||
|
||||
### Optional (for verification)
|
||||
|
||||
```bash
|
||||
sudo apt install lintian
|
||||
```
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Automated Build and Verification
|
||||
|
||||
```bash
|
||||
# From project root
|
||||
./scripts/verify-deb.sh
|
||||
```
|
||||
|
||||
This script will:
|
||||
1. Check for required tools
|
||||
2. Build the package
|
||||
3. Show package contents
|
||||
4. Run lintian checks
|
||||
5. Display installation instructions
|
||||
|
||||
### Manual Build
|
||||
|
||||
```bash
|
||||
# From project root
|
||||
dpkg-buildpackage -us -uc -b
|
||||
```
|
||||
|
||||
The `.deb` file will be created in the parent directory:
|
||||
```bash
|
||||
ls -lh ../sensorpajen_*.deb
|
||||
```
|
||||
|
||||
## Build Output
|
||||
|
||||
```
|
||||
../sensorpajen_2.0.0-dev_all.deb # Installable package
|
||||
../sensorpajen_2.0.0-dev_armhf.build # Build log
|
||||
../sensorpajen_2.0.0-dev_armhf.buildinfo # Build metadata
|
||||
../sensorpajen_2.0.0-dev_armhf.changes # Changes file
|
||||
```
|
||||
|
||||
## Package Verification
|
||||
|
||||
### Check Package Contents
|
||||
|
||||
```bash
|
||||
dpkg-deb -c ../sensorpajen_*.deb
|
||||
```
|
||||
|
||||
### Check Package Metadata
|
||||
|
||||
```bash
|
||||
dpkg-deb -I ../sensorpajen_*.deb
|
||||
```
|
||||
|
||||
### Run Lintian
|
||||
|
||||
```bash
|
||||
lintian ../sensorpajen_*.deb
|
||||
```
|
||||
|
||||
**Note**: Warnings are acceptable. Focus on fixing errors.
|
||||
|
||||
## Installation
|
||||
|
||||
### On Raspberry Pi
|
||||
|
||||
```bash
|
||||
# Copy package to Pi
|
||||
scp ../sensorpajen_*.deb pi@raspberrypi:~/
|
||||
|
||||
# SSH to Pi and install
|
||||
ssh pi@raspberrypi
|
||||
sudo apt install ./sensorpajen_*.deb
|
||||
```
|
||||
|
||||
### Local Testing (Not Recommended)
|
||||
|
||||
Installing on your development machine will modify `/opt` and `/etc`:
|
||||
|
||||
```bash
|
||||
sudo apt install ../sensorpajen_*.deb
|
||||
```
|
||||
|
||||
**Warning**: This will create system directories and a system user on your dev machine.
|
||||
|
||||
## Post-Installation Configuration
|
||||
|
||||
After installing the package:
|
||||
|
||||
```bash
|
||||
# 1. Edit MQTT credentials
|
||||
sudo nano /etc/sensorpajen/sensorpajen.env
|
||||
|
||||
# 2. Configure sensors
|
||||
sudo nano /etc/sensorpajen/sensors.json
|
||||
|
||||
# 3. Start the service
|
||||
sudo systemctl start sensorpajen
|
||||
|
||||
# 4. Check status
|
||||
sudo systemctl status sensorpajen
|
||||
|
||||
# 5. View logs
|
||||
sudo journalctl -u sensorpajen -f
|
||||
```
|
||||
|
||||
## Package Structure
|
||||
|
||||
### Installed Files
|
||||
|
||||
| Source | Destination |
|
||||
|--------|-------------|
|
||||
| `src/sensorpajen/*.py` | `/opt/sensorpajen/src/sensorpajen/` |
|
||||
| `scripts/approve-sensors.sh` | `/opt/sensorpajen/scripts/` |
|
||||
| `pyproject.toml` | `/opt/sensorpajen/` |
|
||||
| `README.md`, `INSTALL.md`, `ROADMAP.md` | `/usr/share/doc/sensorpajen/` |
|
||||
| `config/*.example` | `/usr/share/doc/sensorpajen/examples/` |
|
||||
| `debian/sensorpajen.service` | `/etc/systemd/system/` |
|
||||
| *(created in postinst)* | `/opt/sensorpajen/venv/` |
|
||||
| *(created in postinst)* | `/etc/sensorpajen/` |
|
||||
|
||||
### Configuration Files
|
||||
|
||||
- **Active Config**: `/etc/sensorpajen/sensorpajen.env` (credentials)
|
||||
- **Active Config**: `/etc/sensorpajen/sensors.json` (sensor list)
|
||||
- **Discovery Data**: `/etc/sensorpajen/discovered_sensors.json`
|
||||
- **Examples**: `/usr/share/doc/sensorpajen/examples/*.example`
|
||||
|
||||
## Maintainer Scripts
|
||||
|
||||
### postinst (Post-Installation)
|
||||
|
||||
Runs after package installation:
|
||||
|
||||
1. Creates `sensorpajen` system user (if doesn't exist)
|
||||
2. Creates `/etc/sensorpajen/` directory
|
||||
3. Copies example configs to `/etc/sensorpajen/` (if missing)
|
||||
4. Creates Python virtual environment in `/opt/sensorpajen/venv/`
|
||||
5. Installs Python dependencies via pip
|
||||
6. Sets Bluetooth capabilities on Python executable
|
||||
7. Installs systemd service file
|
||||
8. Enables service (but doesn't start until configured)
|
||||
|
||||
### prerm (Pre-Removal)
|
||||
|
||||
Runs before package removal:
|
||||
|
||||
1. Stops the sensorpajen service
|
||||
2. Disables the service (on remove, not upgrade)
|
||||
|
||||
### postrm (Post-Removal)
|
||||
|
||||
Runs after package removal:
|
||||
|
||||
1. Removes systemd service file
|
||||
2. Reloads systemd daemon
|
||||
3. **Preserves** configuration in `/etc/sensorpajen/`
|
||||
4. **Preserves** `sensorpajen` user
|
||||
|
||||
**Note**: Configuration and user are intentionally preserved to prevent data loss.
|
||||
|
||||
## Upgrade Behavior
|
||||
|
||||
When upgrading to a new version:
|
||||
|
||||
```bash
|
||||
sudo apt install ./sensorpajen_2.1.0_all.deb
|
||||
```
|
||||
|
||||
- ✅ Service is stopped during upgrade
|
||||
- ✅ Old files are replaced
|
||||
- ✅ Configuration in `/etc/sensorpajen/` is **preserved**
|
||||
- ✅ Python dependencies are updated
|
||||
- ✅ Service is restarted after upgrade
|
||||
- ✅ Example files in `/usr/share/doc/` are updated
|
||||
|
||||
## Removal Behavior
|
||||
|
||||
### Remove (Keep Config)
|
||||
|
||||
```bash
|
||||
sudo apt remove sensorpajen
|
||||
```
|
||||
|
||||
- Service stopped and disabled
|
||||
- Application files removed from `/opt/sensorpajen/`
|
||||
- Configuration **preserved** in `/etc/sensorpajen/`
|
||||
- User **preserved**
|
||||
|
||||
### Purge (Still Keeps Config)
|
||||
|
||||
```bash
|
||||
sudo apt purge sensorpajen
|
||||
```
|
||||
|
||||
- Same as remove
|
||||
- Configuration still **preserved** (by design, for safety)
|
||||
- User still **preserved**
|
||||
|
||||
### Complete Removal
|
||||
|
||||
To completely remove everything:
|
||||
|
||||
```bash
|
||||
sudo apt purge sensorpajen
|
||||
sudo rm -rf /etc/sensorpajen
|
||||
sudo userdel sensorpajen
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Build Fails: "debhelper: command not found"
|
||||
|
||||
```bash
|
||||
sudo apt install debhelper
|
||||
```
|
||||
|
||||
### Build Fails: "dh_python3: command not found"
|
||||
|
||||
```bash
|
||||
sudo apt install dh-python
|
||||
```
|
||||
|
||||
### Lintian Warnings About Permissions
|
||||
|
||||
The postinst script runs as root and sets file permissions. This is expected and safe.
|
||||
|
||||
### Package Won't Install: Dependency Issues
|
||||
|
||||
```bash
|
||||
# Fix missing dependencies
|
||||
sudo apt install -f
|
||||
```
|
||||
|
||||
### Service Won't Start After Install
|
||||
|
||||
Check if configuration has been edited:
|
||||
|
||||
```bash
|
||||
sudo journalctl -u sensorpajen -n 50
|
||||
```
|
||||
|
||||
Common issues:
|
||||
- MQTT_HOST still has example value
|
||||
- sensors.json is empty
|
||||
- Bluetooth adapter not available
|
||||
|
||||
### Bluetooth Capability Not Set
|
||||
|
||||
```bash
|
||||
# Manually set capability
|
||||
sudo setcap cap_net_raw,cap_net_admin+eip $(readlink -f /opt/sensorpajen/venv/bin/python3)
|
||||
|
||||
# Verify
|
||||
getcap $(readlink -f /opt/sensorpajen/venv/bin/python3)
|
||||
```
|
||||
|
||||
## Development Workflow
|
||||
|
||||
### Making Changes
|
||||
|
||||
1. Edit source code in `src/sensorpajen/`
|
||||
2. Update version in `pyproject.toml`
|
||||
3. Update `debian/changelog` with new entry
|
||||
4. Rebuild package: `./scripts/verify-deb.sh`
|
||||
5. Test on Raspberry Pi
|
||||
|
||||
### Version Numbering
|
||||
|
||||
- Development: `2.0.0-dev`
|
||||
- Release: `2.0.0`
|
||||
- Patch: `2.0.1`
|
||||
|
||||
Update in both:
|
||||
- `pyproject.toml` (line 6: `version = "..."`)
|
||||
- `debian/changelog` (first line)
|
||||
|
||||
### Testing on Pi
|
||||
|
||||
```bash
|
||||
# Build
|
||||
./scripts/verify-deb.sh
|
||||
|
||||
# Copy to Pi
|
||||
scp ../sensorpajen_*.deb pi@raspberrypi:~/
|
||||
|
||||
# Install on Pi
|
||||
ssh pi@raspberrypi
|
||||
sudo systemctl stop sensorpajen # If upgrading
|
||||
sudo apt install ./sensorpajen_*.deb
|
||||
sudo systemctl status sensorpajen
|
||||
```
|
||||
|
||||
## Package Metadata
|
||||
|
||||
**Package Name**: sensorpajen
|
||||
**Section**: misc
|
||||
**Priority**: optional
|
||||
**Architecture**: all (pure Python)
|
||||
**Maintainer**: Fredrik <fredrik@wahlberg.se>
|
||||
**Depends**: python3 (>= 3.9), python3-venv, python3-pip, bluetooth, bluez, libcap2-bin
|
||||
**Recommends**: mosquitto-clients
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- **TASKS.md**: Detailed implementation notes
|
||||
- **ROADMAP.md**: Phase 8 section for APT package creation
|
||||
- **INSTALL.md**: User installation guide
|
||||
- **systemd/README.md**: Service management guide
|
||||
|
||||
## Support
|
||||
|
||||
For issues or questions:
|
||||
1. Check `sudo journalctl -u sensorpajen -n 100`
|
||||
2. Verify configuration files in `/etc/sensorpajen/`
|
||||
3. Check Bluetooth adapter: `hciconfig`
|
||||
4. Test MQTT connection: `mosquitto_pub -h <host> -t test -m "test"`
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: December 27, 2025
|
||||
**Package Version**: 2.0.0-dev
|
||||
Reference in New Issue
Block a user