feat: Implement production-ready systemd service best practices

- Update systemd service file with Type=simple and comprehensive locking - Enhance D-Bus service and policy files for proper activation - Remove OSTree dependency for test mode compatibility - Implement automated service file installation and cleanup - Add comprehensive systemd usage documentation - Update changelog and TODO to reflect completed systemd improvements - Service now successfully running under systemd management This completes the systemd service integration with production-ready configuration and best practices for daemon lifecycle management.
2025-07-16 16:13:35 +00:00 · 2025-07-16 16:13:35 +00:00 · 8c470a56b5
commit 8c470a56b5
parent 3def8187a9
13 changed files with 1684 additions and 93 deletions
--- a/src/apt-ostree.py/SYSTEMD_USAGE.md
+++ b/src/apt-ostree.py/SYSTEMD_USAGE.md
@ -0,0 +1,203 @@
+# apt-ostree Systemd Service Usage
+
+## Overview
+
+The apt-ostree daemon is managed through systemd using the `apt-ostreed.service` unit. The service is configured with proper locking mechanisms to prevent multiple instances and ensure clean startup/shutdown.
+
+## Service Configuration
+
+### Type=simple
+The service uses `Type=simple` instead of `Type=dbus` because:
+- The daemon manages its own D-Bus interface registration
+- Provides better control over the daemon lifecycle
+- Allows for proper PID file management
+- Enables ExecStartPre/ExecStopPost hooks
+
+### Lock File Mechanism
+- **PID File**: `/var/run/apt-ostreed.pid` - Contains the daemon's process ID
+- **Lock File**: `/run/apt-ostreed/daemon.lock` - Prevents multiple instances
+- **Runtime Directory**: `/run/apt-ostreed/` - Managed by systemd
+
+### Instance Prevention
+The service includes ExecStartPre commands to:
+1. Remove stale PID files
+2. Remove stale lock files
+3. Create runtime directory
+4. Create fresh lock file
+
+## Proper Service Management
+
+### ⚠️ IMPORTANT: Use systemctl Only
+
+**DO NOT** run the daemon directly with `python3 apt_ostree.py --daemon`. Always use systemctl commands:
+
+```bash
+# ✅ CORRECT - Use systemctl
+sudo systemctl start apt-ostreed
+sudo systemctl stop apt-ostreed
+sudo systemctl restart apt-ostreed
+sudo systemctl status apt-ostreed
+
+# ❌ WRONG - Don't run directly
+sudo python3 apt_ostree.py --daemon  # This bypasses systemd management
+```
+
+### Why systemctl Only?
+
+1. **Lock File Management**: systemd handles PID and lock files automatically
+2. **Process Supervision**: systemd monitors the daemon and restarts on failure
+3. **Dependency Management**: Ensures proper startup order (after dbus, etc.)
+4. **Security**: Maintains security sandboxing and privilege restrictions
+5. **Logging**: Integrates with journald for centralized logging
+6. **Resource Management**: systemd can manage resource limits and cgroups
+
+## Service Commands
+
+### Basic Management
+```bash
+# Start the daemon
+sudo systemctl start apt-ostreed
+
+# Stop the daemon
+sudo systemctl stop apt-ostreed
+
+# Restart the daemon
+sudo systemctl restart apt-ostreed
+
+# Check status
+sudo systemctl status apt-ostreed
+
+# Enable auto-start on boot
+sudo systemctl enable apt-ostreed
+
+# Disable auto-start
+sudo systemctl disable apt-ostreed
+```
+
+### Monitoring and Debugging
+```bash
+# View real-time logs
+sudo journalctl -u apt-ostreed -f
+
+# View recent logs
+sudo journalctl -u apt-ostreed -n 50
+
+# View logs since boot
+sudo journalctl -u apt-ostreed -b
+
+# Check if service is active
+sudo systemctl is-active apt-ostreed
+
+# Check if service is enabled
+sudo systemctl is-enabled apt-ostreed
+```
+
+### Troubleshooting
+```bash
+# Check service configuration
+sudo systemctl cat apt-ostreed
+
+# Validate service file
+sudo systemd-analyze verify apt-ostreed.service
+
+# Check dependencies
+sudo systemctl list-dependencies apt-ostreed
+
+# Force reload configuration
+sudo systemctl daemon-reload
+sudo systemctl restart apt-ostreed
+```
+
+## Service States
+
+### Normal Operation
+- **Active**: Daemon is running and responding
+- **Inactive**: Daemon is stopped
+- **Failed**: Daemon failed to start or crashed
+
+### Transition States
+- **Activating**: Daemon is starting up
+- **Deactivating**: Daemon is shutting down
+- **Reloading**: Daemon is reloading configuration
+
+## Lock File Troubleshooting
+
+If the service fails to start due to lock files:
+
+```bash
+# Check for stale lock files
+ls -la /var/run/apt-ostreed.pid
+ls -la /run/apt-ostreed/daemon.lock
+
+# Remove stale files (if service is not running)
+sudo rm -f /var/run/apt-ostreed.pid
+sudo rm -f /run/apt-ostreed/daemon.lock
+
+# Restart service
+sudo systemctl restart apt-ostreed
+```
+
+## Integration with apt-ostree CLI
+
+The apt-ostree CLI automatically communicates with the daemon via D-Bus:
+
+```bash
+# These commands work through the daemon
+apt-ostree status
+apt-ostree upgrade
+apt-ostree install package-name
+apt-ostree rollback
+
+# The CLI will automatically start the daemon if needed
+# (when using systemctl, not direct execution)
+```
+
+## Security Considerations
+
+- The daemon runs as root (required for system operations)
+- Uses systemd security sandboxing (ProtectSystem, PrivateTmp, etc.)
+- D-Bus communication is restricted by policy files
+- Lock files prevent privilege escalation through multiple instances
+
+## Best Practices
+
+1. **Always use systemctl** for service management
+2. **Never run the daemon directly** with python3
+3. **Monitor logs** with journalctl for troubleshooting
+4. **Use proper service states** for automation scripts
+5. **Check lock files** if startup fails
+6. **Enable the service** for automatic startup on boot
+
+## Example Automation Script
+
+```bash
+#!/bin/bash
+# Example script for managing apt-ostree daemon
+
+SERVICE="apt-ostreed"
+
+case "$1" in
+    start)
+        echo "Starting apt-ostree daemon..."
+        sudo systemctl start $SERVICE
+        ;;
+    stop)
+        echo "Stopping apt-ostree daemon..."
+        sudo systemctl stop $SERVICE
+        ;;
+    restart)
+        echo "Restarting apt-ostree daemon..."
+        sudo systemctl restart $SERVICE
+        ;;
+    status)
+        sudo systemctl status $SERVICE
+        ;;
+    logs)
+        sudo journalctl -u $SERVICE -f
+        ;;
+    *)
+        echo "Usage: $0 {start|stop|restart|status|logs}"
+        exit 1
+        ;;
+esac
+```