Skip to main content

Linux and servers · Intermediate · 12 min

How to Run Your App as a systemd Service on Ubuntu 26.04

By Padding · Updated 15 Nov 2026
Ubuntu 26.04.1 LTS · systemd

You will write a systemd unit file that starts your app at boot, restarts it when it crashes, runs it as an unprivileged user, and sends its logs to the journal.

On this page

If you start your app by typing a command in an SSH session, it stops when you log out, and it does not come back after a reboot or a crash. systemd is the service manager on Ubuntu. Give it a short unit file and it starts the app at boot, restarts it on failure, controls the account it runs under, and collects its output.

In this tutorial you will create a service account, write a unit file for a small web app, start and enable the service, and read its logs. Ubuntu 26.04 ships systemd 259.

Step 1 · Create an account for the app

Do not run an app as root. If it is compromised, the attacker has the machine. Make a system user that has no password, no login shell and its own group.

Bash
sudo apt update
sudo apt install -y python3
sudo adduser --system --group --no-create-home --home /srv/myapp myapp
sudo mkdir -p /srv/myapp
echo '<h1>It runs</h1>' | sudo tee /srv/myapp/index.html
sudo chown -R myapp:myapp /srv/myapp

--system creates a user with a low ID and no expiry. --group creates a group with the same name. Replace myapp and /srv/myapp with your own app's name and folder.

Check it worked

Bash
getent passwd myapp

The line ends with /srv/myapp:/usr/sbin/nologin. The user cannot start a login session.

Step 2 · Run the app by hand first

Always run the command yourself before putting it in a unit. An error is far easier to read in a terminal. This app serves the folder over HTTP on the local port 8080.

Bash
sudo -u myapp /usr/bin/python3 -m http.server 8080 --bind 127.0.0.1 --directory /srv/myapp &
app_pid=$!
sleep 2
python3 -c 'import urllib.request; print(urllib.request.urlopen("http://127.0.0.1:8080/").read().decode())'
kill "$app_pid"

The page prints <h1>It runs</h1>. Two things to take from this for the unit file: systemd needs the full path to the program (/usr/bin/python3, not python3), and the app must run in the foreground. A program that forks itself into the background confuses Type=simple, which is the default and the right choice for most apps.

Step 3 · Write the unit file

Unit files for your own services go in /etc/systemd/system/. The file name sets the service name.

Bash
sudo tee /etc/systemd/system/myapp.service > /dev/null <<'UNIT'
[Unit]
Description=My app (static site on port 8080)
After=network.target

[Service]
Type=simple
User=myapp
Group=myapp
WorkingDirectory=/srv/myapp
ExecStart=/usr/bin/python3 -m http.server 8080 --bind 127.0.0.1
Restart=on-failure
RestartSec=5
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=true
PrivateTmp=true

[Install]
WantedBy=multi-user.target
UNIT

What each line does:

  • After=network.target starts the app after networking is up.
  • User and Group run it as the account from step 1.
  • WorkingDirectory is where the process starts. It is also the folder relative paths use.
  • ExecStart is the command. Use absolute paths. systemd does not use a shell, so &&, pipes and ~ do not work here.
  • Restart=on-failure restarts the app after a crash or non-zero exit, but not after you stop it on purpose. RestartSec=5 waits five seconds between attempts.
  • NoNewPrivileges, ProtectSystem=strict, ProtectHome and PrivateTmp limit what the process can touch. With ProtectSystem=strict the whole file system is read-only for the app, apart from /dev, /proc and /sys. If your app must write somewhere, add ReadWritePaths=/srv/myapp/data.
  • WantedBy=multi-user.target is what enable hooks into so the service starts at boot.

Check it worked

Ask systemd to read the file and report problems:

Bash
systemd-analyze verify /etc/systemd/system/myapp.service

No output means no errors. A mistyped option is reported, for example Failed to parse Restart=sometimes, ignoring: Invalid argument. Read warnings as faults: systemd ignores the bad line and carries on, so the service would not behave as you meant.

Step 4 · Start the service and enable it at boot

systemd reads unit files at start and when told to reload. After you create or change one, reload it:

Bash
sudo systemctl daemon-reload

Start the service now, and enable it to start at every boot. enable --now does both.

Bash
sudo systemctl enable --now myapp

systemd answers with a line that starts Created symlink and names the multi-user.target.wants entry for myapp.service.

Check it worked

Bash
systemctl status myapp

The output includes Active: active (running), the main process ID and the last few log lines. Then request the page:

Bash
curl http://127.0.0.1:8080/

You should see <h1>It runs</h1>.

Troubleshooting

When the status shows failed or the service restarts in a loop, read the reason in the journal:

Bash
journalctl -u myapp -n 50 --no-pager

Typical causes:

  • status=203/EXEC: systemd could not run the ExecStart program. The path is wrong, the file is not executable, or the user cannot read it. Run ls -l on the path.
  • status=200/CHDIR: the WorkingDirectory does not exist or the user cannot enter it.
  • status=217/USER: the account in User= does not exist. Check getent passwd myapp.
  • Port already in use in the log: another process holds port 8080. Find it with sudo ss -ltnp 'sport = :8080'.
  • Read-only file system errors in the app: ProtectSystem=strict is blocking a write. Add the folder to ReadWritePaths=.

Step 5 · Read logs and manage the service

Anything the app prints to standard output or standard error goes to the journal, with the service name and timestamps. No log file setup is needed.

Bash
journalctl -u myapp -f

-f follows new entries, like tail -f. Press Ctrl+C to stop. Add --since "1 hour ago" to limit the range.

The commands you will use most:

| Command | What it does |
|---|---|
| sudo systemctl restart myapp | Stop and start the service |
| sudo systemctl reload myapp | Ask the app to reread its config, if the unit defines ExecReload= |
| sudo systemctl stop myapp | Stop it. With Restart=on-failure it stays stopped |
| sudo systemctl disable myapp | Do not start it at boot |
| systemctl is-enabled myapp | Print enabled or disabled |
| systemctl list-units --type=service --state=failed | List services that failed |

After editing the unit file, run sudo systemctl daemon-reload and then sudo systemctl restart myapp. Without the reload, systemd keeps using the old file and warns that it changed on disk.

To test the crash restart, kill the process and watch it return after five seconds:

Bash
sudo kill -9 $(systemctl show -p MainPID --value myapp)
sleep 6
systemctl is-active myapp

Because the app was killed by a signal, systemd treats it as a failure, Restart=on-failure applies, and the last command prints active.

Next steps

  • Put the app behind a web server with /tutorials/nginx-reverse-proxy-for-a-node-app, which uses the same pattern for a Node.js app.
  • Run a task on a timetable instead of continuously: /tutorials/schedule-jobs-with-cron.
  • Check the file ownership your service needs in /tutorials/linux-file-permissions-chmod-chown.
  • Sources: systemd.service(5), systemd.exec(5) and systemctl(1) at freedesktop.org/software/systemd/man.

Need this done for you?

Padding does this work for growing companies, from the first diagnosis to a system that keeps working.

Platform Engineering

Get new tutorials

New tutorials, about twice a month.