Writing a service unit file

A unit file has three sections. Knowing which key goes in which section removes most of the confusion. Place the file in /etc/systemd/system/myapp.service:

[Unit]
Description=My Python API
After=network.target

[Service]
ExecStart=/usr/bin/python3 /opt/myapp/server.py
Restart=on-failure
User=myapp
WorkingDirectory=/opt/myapp

[Install]
WantedBy=multi-user.target

[Unit] contains metadata and dependency declarations — everything that is true regardless of what type of unit this is. [Service] contains the process-specific configuration — how to start it, what user to run as, restart behaviour. [Install] contains the wiring for systemctl enable — which target should pull this service in when enabled.

Type= tells systemd how your process signals that it is ready. Getting this wrong causes silent bugs — systemd may declare the service “active” before it is actually serving requests, or may time out waiting for readiness.

# A modern foreground daemon (Node.js, Python uvicorn, Go http.ListenAndServe)
[Service]
Type=simple
ExecStart=/usr/bin/node /opt/app/index.js

# Legacy nginx that double-forks
[Service]
Type=forking
PIDFile=/run/nginx.pid
ExecStart=/usr/sbin/nginx

If you set Type=forking for a process that does not fork, systemd will wait for the parent to exit — which it never will — and timeout after 90 seconds, marking the service failed.

Restart= controls what happens when your process exits unexpectedly. This is one of the most important directives — it is the difference between “paged at 3am” and “service recovered automatically”:

[Service]
Restart=on-failure
RestartSec=5s          # Wait 5 seconds before restarting (avoids tight loops)
StartLimitIntervalSec=60s  # Window for counting restart attempts
StartLimitBurst=3      # If it restarts 3 times in 60s, give up and enter failed state

Without RestartSec, a crashing service will restart immediately and may spam logs or cause CPU load from a tight restart loop. The StartLimitBurst / StartLimitIntervalSec pair prevents the service from restarting forever if there is a hard configuration error.

User=, Group=, and WorkingDirectory= are non-negotiable for production services. Running as root is a security risk — a compromised process gets the keys to the kingdom:

[Service]
User=myapp
Group=myapp
WorkingDirectory=/opt/myapp
RuntimeDirectory=myapp        # Creates /run/myapp owned by User= at start
StateDirectory=myapp          # Creates /var/lib/myapp owned by User= at start
LogsDirectory=myapp           # Creates /var/log/myapp owned by User= at start

RuntimeDirectory, StateDirectory, and LogsDirectory are the clean systemd way to create and own directories at service start — no ExecStartPre=mkdir hacks needed, and the directories are created with the right ownership automatically.

The myapp user should be a system user created at deployment time:

sudo useradd --system --no-create-home --shell /usr/sbin/nologin myapp

After writing or editing a unit file, you must tell systemd to re-read it with daemon-reload. systemd caches the unit files it reads. If you skip daemon-reload, it will continue running the old definition even if you restart the service:

# After creating or editing /etc/systemd/system/myapp.service
sudo systemctl daemon-reload

# Now the new definition is active — start or restart
sudo systemctl enable --now myapp.service

# Verify it is running as expected
systemctl status myapp.service

# Watch live logs for this service
journalctl -u myapp.service -f

The most common support question: “I updated the unit file but nothing changed.” Nine times out of ten, daemon-reload was skipped.