sensorpajen/debian/README.md

# 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_3.0.0_all.deb              # Installable package
../sensorpajen_3.0.0_armhf.build          # Build log
../sensorpajen_3.0.0_armhf.buildinfo      # Build metadata
../sensorpajen_3.0.0_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
```

## Running the TUI

The package installs a `sensorpajen-tui` command in `/usr/bin/`.

```bash
sudo sensorpajen-tui
```

Internally this runs the application from `/opt/sensorpajen/venv/`.

## Package Structure

### Installed Files

| Source | Destination |
|--------|-------------|
| `src/sensorpajen/*.py` | `/opt/sensorpajen/src/sensorpajen/` |
| `src/sensorpajen/tui/*.py` | `/opt/sensorpajen/src/sensorpajen/tui/` |
| `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