adminSystemd Unit File Checklist for Custom Apps and Workers
Custom apps, Python scripts, Node.js services, queue workers and automation agents should not run only inside a terminal session. A systemd unit lets Linux manage startup, restart, logging and service lifecycle.
Core principle
A reliable background app needs a working directory, execution command, service user, restart policy, environment variables and logs. Without these, it may disappear after logout or reboot.
Checklist
- Define the exact command that starts the app.
- Define the working directory.
- Choose the service user.
- Set environment variables safely.
- Create a systemd unit file.
- Validate the unit configuration.
- Reload systemd.
- Start and enable the service.
- Check logs with journalctl.
- Test reboot survival if required.
Reusable lesson
This applies to API workers, crawlers, Telegram bots, AI agents, queue processors, monitoring scripts and internal automation tools.
When to Use This Checklist
Use this checklist when turning a script, API worker, AI agent, crawler or automation service into a managed Linux service.
Required Tools
SSH access, app command, app folder, environment variables, service user, systemd, journalctl
Before You Start
Test the app command manually before creating a systemd unit. Systemd cannot fix a command that does not run.
Structured Checklist Steps
- Test start command.
- Define working directory.
- Choose service user.
- Prepare environment variables.
- Create unit file.
- Validate unit.
- Reload systemd.
- Start service.
- Enable service.
- Check logs.
Verification Steps
- Service starts successfully.
- Logs are visible in journalctl.
- Service restarts if configured.
- Service survives reboot if enabled.
- Environment variables load correctly.
Rollback Plan
If the unit fails, disable the service, restore the previous unit file and run the start command manually to isolate the error.
Common Mistakes
- Using root when not needed.
- Wrong working directory.
- Missing environment variables.
- Forgetting daemon-reload.
- No restart policy for critical workers.
Related Commands
sudo nano /etc/systemd/system/my-worker.service
sudo systemctl daemon-reload
sudo systemctl start my-worker
sudo systemctl status my-worker
journalctl -u my-worker --since "30 minutes ago"
sudo systemctl enable my-worker