Systemd Services & Unit Files
debt(d7/e3/b3/t5)
Closest to 'only careful code review or runtime testing' (d7). The detection_hints note automated=no, and the code pattern requires manually inspecting whether queue workers are running in screen/tmux with no unit files, no automatic restart, and no systemd supervision. Tools listed (systemd, journalctl) only help after the fact — there is no automated check that flags the absence of a unit file. A reviewer must notice the gap during a server audit or when a worker silently stays down after a crash.
Closest to 'simple parameterised fix' (e3). The quick_fix is to write a systemd unit file per worker — a small, self-contained task per service. Fixing common mistakes (adding Restart=on-failure, User=, WantedBy=) are single-file edits within one component. This is slightly more than a one-liner but well within one component and doesn't span multiple files across the codebase.
Closest to 'localised tax' (b3). The applies_to scope is cli and queue-worker contexts only, not the entire web application. Properly configured unit files are self-contained — once written they impose minimal ongoing maintenance tax. The burden is localised to the operations/server layer and does not shape every future development decision.
Closest to 'notable trap' (t5). The misconception field identifies a documented gotcha: developers assume Supervisor is required for PHP queue workers and overlook that systemd already handles process supervision natively. Common mistakes (omitting Restart=on-failure, missing WantedBy, forgetting daemon-reload) are documented pitfalls that most developers encounter at least once, but they are learnable and don't fundamentally contradict how similar concepts work.
Also Known As
TL;DR
Explanation
A systemd service unit file (.service) defines: ExecStart (command to run), Restart policy (on-failure, always), User/Group (run as specific user), Environment (environment variables), After/Requires (dependency ordering), and WantedBy (when to start). Key commands: systemctl start/stop/restart/status servicename, systemctl enable (start on boot), journalctl -u servicename (logs). PHP applications use systemd for PHP-FPM, queue workers (Horizon, custom workers), scheduled tasks (alternatives to cron), and WebSocket servers.
Common Misconception
Why It Matters
Common Mistakes
- Not setting Restart=on-failure — crashed services stay down until manually restarted.
- Running services as root — always specify User= and Group= for security.
- Not setting WantedBy=multi-user.target — the service doesn't start on boot after systemctl enable.
- Not reloading systemd after editing unit files: systemctl daemon-reload.
Code Examples
# No systemd — manual process management:
# Start worker: php artisan queue:work &
# Worker crashes: nobody notices until queue backs up
# Server restarts: worker never comes back
# Multiple workers: manual tracking of PIDs
# Logs: mixed into syslog or lost# /etc/systemd/system/queue-worker.service:
[Unit]
Description=Laravel Queue Worker
After=network.target
[Service]
User=www-data
Group=www-data
WorkingDirectory=/var/www/app
ExecStart=/usr/bin/php artisan queue:work --sleep=3 --tries=3
Restart=on-failure
RestartSec=5
StandardOutput=journal
StandardError=journal
[Install]
WantedBy=multi-user.target
# Enable and start:
# systemctl daemon-reload
# systemctl enable --now queue-worker
# journalctl -u queue-worker -f