Back to Blog

How to Create a systemd Service on Linux

Create a systemd service on Linux: write a unit file, start your app on boot, restart it on crashes, read logs with journalctl and fix 203/EXEC errors.

Nodesty Team8 min readServers
The words systemd Service with systemctl, journalctl and Restart on a dark Nodesty background

A systemd service is the standard way to keep an application running around the clock on a Linux server: systemd starts it on boot, restarts it if it crashes and collects its logs. Instead of leaving your app running in an SSH session or a screen window, you describe it once in a small unit file and let the system take care of it.

This guide covers writing a unit file, the most important options, examples for a Node.js and a Python app, reading logs, common errors such as 203/EXEC and a few light hardening settings. The commands are for Ubuntu and Debian, but they work the same on AlmaLinux and other systemd distributions.

What is a systemd service?

systemd is the init system and service manager on almost every modern Linux distribution. Each thing it manages is described in a unit file; services end in .service. Packages place their units under /usr/lib/systemd/system/ (on older Debian-based systems also /lib/systemd/system/), and your own services belong in /etc/systemd/system/, which takes precedence.

Compared with running node app.js by hand, a service:

  • starts automatically after a reboot,
  • comes back up when the app crashes,
  • runs as the user you choose, with the environment you define,
  • writes its output to the journal, where you can search it with journalctl.

Step 1: Create a user for the app

It is safer not to run your app as root. Create a system user with its own home folder and no login shell:

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

Copy your application into /opt/myapp (for example with git clone, see our Deploying with Git guide) and give the user ownership:

sudo chown -R myapp:myapp /opt/myapp

Step 2: Write the unit file

Create the file /etc/systemd/system/myapp.service:

sudo nano /etc/systemd/system/myapp.service

A complete example for a Node.js app:

[Unit]
Description=My Node.js app
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=myapp
Group=myapp
WorkingDirectory=/opt/myapp
ExecStart=/usr/bin/node /opt/myapp/app.js
Restart=on-failure
RestartSec=5
Environment=NODE_ENV=production

[Install]
WantedBy=multi-user.target

The file name (without .service) is the name you'll use with systemctl, here myapp.

What each line does

OptionMeaning
DescriptionShort name shown in systemctl status and in logs
After / WantsStart after the network is up, and pull in network-online.target
Type=simpleThe process in ExecStart is the service itself and stays in front
User / GroupWhich account the app runs as
WorkingDirectoryThe folder the app starts in; relative paths in your code resolve here
ExecStartThe command to run, with absolute paths
Restart / RestartSecWhen to restart and how many seconds to wait first
Environment / EnvironmentFileEnvironment variables for the app
WantedBy=multi-user.targetStart the service during a normal boot once it's enabled

A few points that often trip people up:

  • ExecStart doesn't run through a shell. Pipes, &&, > redirects and ~ don't work. If you really need shell features, use ExecStart=/bin/bash -c '...', but a small script file is usually cleaner.
  • Don't let the app fork into the background (for example pm2 start or nohup ... &). With Type=simple, systemd expects the process to stay in the foreground.
  • Restart=on-failure restarts the app after a crash or a non-zero exit code; Restart=always also restarts it after a clean exit. Stopping it with systemctl stop never triggers a restart.

Step 3: Start and enable the service

Tell systemd about the new file, then start the service and enable it at boot in one step:

sudo systemctl daemon-reload
sudo systemctl enable --now myapp
sudo systemctl status myapp

active (running) in the status output means everything works. The everyday commands:

sudo systemctl restart myapp     # restart after deploying new code
sudo systemctl stop myapp        # stop
sudo systemctl disable myapp     # don't start on boot anymore
systemctl is-enabled myapp       # enabled or disabled?

Every time you edit the unit file, run sudo systemctl daemon-reload and then restart the service.

A Python app with a virtual environment

For Python, point ExecStart at the Python binary inside your virtual environment; that way you don't need to "activate" anything:

[Unit]
Description=My Python app
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=myapp
WorkingDirectory=/opt/myapp
ExecStart=/opt/myapp/venv/bin/python /opt/myapp/main.py
Restart=always
RestartSec=5
Environment=PYTHONUNBUFFERED=1
EnvironmentFile=/opt/myapp/.env

[Install]
WantedBy=multi-user.target

PYTHONUNBUFFERED=1 makes print() output show up in the logs immediately instead of being buffered. A complete bot example with this setup is in our How to host a Discord bot guide.

Environment variables and secrets

Short values can go straight into the unit with Environment=. Keep tokens and passwords in a separate file and load it with EnvironmentFile=. The file holds one KEY=value per line, without export:

DATABASE_URL=postgres://myapp:secret@localhost/myapp
API_TOKEN=change-me

Make the file readable only by its owner:

sudo chown myapp:myapp /opt/myapp/.env
sudo chmod 600 /opt/myapp/.env

The file is read by systemd itself, so variables are passed to the app even though it never reads .env on its own. More on permissions in our Linux file permissions guide.

Reading the logs with journalctl

Everything the app writes to standard output and standard error lands in the journal:

journalctl -u myapp -f                  # follow live
journalctl -u myapp -n 100              # last 100 lines
journalctl -u myapp --since "1 hour ago"
journalctl -u myapp -b                  # since the last boot

Add sudo or put your user in the adm or systemd-journal group if you don't see any output. More useful commands are in our Linux commands guide.

Common errors and how to fix them

systemctl status myapp shows the exit reason in the Main PID or Process line. The most frequent ones:

  • status=203/EXEC: systemd couldn't run the program in ExecStart. The path is wrong or relative, the file isn't executable or the script has no shebang (#!/usr/bin/env bash). Find the real path with which node or which python3. If Node.js was installed with nvm, it lives under the user's home folder, for example /home/user/.nvm/versions/node/<version>/bin/node, so use that full path.
  • status=217/USER: the user in User= doesn't exist. Check the spelling or create it with useradd.
  • status=200/CHDIR: the folder in WorkingDirectory doesn't exist or the user can't enter it.
  • start-limit-hit: the app crashed too often in a short time, so systemd stopped trying. By default that happens after 5 starts within 10 seconds. Fix the crash first (the cause is in journalctl -u myapp), then clear the counter with sudo systemctl reset-failed myapp.

You can adjust the start limit in the [Unit] section; with these values, systemd allows 5 restarts within 5 minutes:

[Unit]
StartLimitIntervalSec=300
StartLimitBurst=5

To check a unit file for typos before starting it, run systemd-analyze verify /etc/systemd/system/myapp.service.

Changing a service with systemctl edit

To change a service that came with a package, such as nginx, don't edit its file under /usr/lib/systemd/system/; a package update would overwrite it. Create an override instead:

sudo systemctl edit nginx

This opens an editor and saves your lines to /etc/systemd/system/nginx.service.d/override.conf. Only write what you want to change:

[Service]
Restart=on-failure
RestartSec=5

systemd reloads its configuration when you close the editor; restart the service to apply the change. To replace ExecStart, first clear it with an empty ExecStart= line and add the new one below it. systemctl cat nginx shows the original file together with your overrides.

Light hardening

A few options limit what the app can do if it is ever compromised, with little risk of breaking it:

[Service]
NoNewPrivileges=true
ProtectSystem=full
PrivateTmp=true
  • NoNewPrivileges=true: the process and its children can't gain extra privileges, for example through sudo or setuid programs.
  • ProtectSystem=full: /usr, /boot and /etc become read-only for the service.
  • PrivateTmp=true: the service gets its own /tmp and /var/tmp, separate from other users.

systemd-analyze security myapp rates a service and lists further options. Add them one by one and test after each change; general server security is covered in our Linux server security guide.

systemd timers vs cron

systemd can also run tasks on a schedule with a timer: a .timer unit with the same name as a .service unit starts that service at set times. A minimal /etc/systemd/system/backup.timer that runs backup.service every night:

[Unit]
Description=Nightly backup

[Timer]
OnCalendar=*-*-* 03:00:00
Persistent=true

[Install]
WantedBy=timers.target

Enable it with sudo systemctl enable --now backup.timer and list all timers with systemctl list-timers. The service it starts is usually Type=oneshot. Timers log to the journal and, with Persistent=true, catch up on runs missed while the server was off. For simple jobs, cron is still a fine choice; see our What is cron? guide.

systemd services at Nodesty

Nodesty AMD Ryzen 9 9950X VPS and AMD EPYC 7763 VPS plans come with NVMe disks and full root access, so you can create your own systemd services and keep your apps, bots and APIs running 24/7. Daily backups are free on VPS plans and are kept for 7 days. To learn what keeps a service reachable around the clock, read our What is uptime? guide.

Frequently Asked Questions

What is the difference between Restart=always and Restart=on-failure?

With on-failure, systemd restarts the app only when it exits with an error code, crashes on a signal or times out; a clean exit with code 0 leaves it stopped. With always, it is restarted even after a clean exit. In both cases, stopping the service yourself with systemctl stop does not trigger a restart.

Do I need to run daemon-reload after every change?

Yes, whenever you create or edit a unit file by hand, run sudo systemctl daemon-reload so systemd reads the new version, then restart the service. systemctl edit runs the reload for you when you save and close the editor, but you still need to restart the service for the change to take effect.

Why does my service fail with status=203/EXEC?

systemd could not run the program in ExecStart. The path is usually wrong or relative, the file isn't executable or a script has no shebang line. Find the full path with which node or which python3, write it into ExecStart and check the file with ls -l.

Where can I see the output of my app?

Everything your app writes to standard output and standard error goes to the systemd journal. Read it with journalctl -u myapp, add -f to follow new lines live and -n 100 to see the last 100 lines. For Python apps, set PYTHONUNBUFFERED=1 so lines appear immediately.

Should I use systemd or pm2 for a Node.js app?

Both keep the app running and start it on boot. pm2 adds Node.js specific conveniences such as cluster mode and its own log view, while systemd is already part of the system, needs no extra installation and works the same for Node.js, Python, Go or any other program.

Can a systemd service replace a cron job?

Yes, a systemd timer can run a service on a schedule, much like cron. Timers log to the journal and can catch up on missed runs with Persistent=true. For simple scheduled tasks, cron is still perfectly fine; pick the one you find easier to maintain.

Nodesty

About the author

Nodesty Team · Infrastructure & Support

The Nodesty team runs our servers, network and DDoS protection day to day and answers customer support requests around the clock. These guides come from that work.

Related articles

Launch your server now.

Build, scale, and conquer without limits on Nodesty's premium infrastructure.

                                                                                                                                                                                                                            
                                                                                                                                                                                                                            
                                                                                                                                                                                                                            
                                                                                                                             ············································                                                   
                                                ··································································································..........···························                                     
                                       ················..........................................................................................................................··············                             
                                  ·············.................::::::::::::::::::::::::::::::::::::::::::::::....................:::::::::::::::::::::::::::::::::::::::................···········                        
                             ············................:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::............·········                     
                         ············.................:::::::::::::::::::::::::::::::::::::::::::::::::::------------::::::::::::::::::::::::::::::----------------:::::::::::::::::::::..........········                  
                    ············......................::::::::::::::::::::::::::::::::::::------------------------------------------------------------------------------------:::::::::::::.........········                
                ··········.............................................::::::::::::::::::-------------==========================================-----------------------------------:::::::::::........·······               
             ········..................:.....................................::::::::::--------=======+++++++++++++++++++++++++++++++++++++=========================------------------::::::::::.......·······              
           ······.........::::::::::::::::::::................................:::::::-----=====++++xxxxxx**************************xxxxxxxxx++++++++++++++===================------------::::::::.......·······             
          ·····.......:::::::::::::::::::::::::::.............................:::::----===+++xxx****%%%%&&&&&&#############&&&&&&&%%%%%*******xxxxxxxx++++++++++++++==============----------:::::::......······             
         ····......::::::::-------------:::::::::::..........................::::---===+++xx***%%%&&&####@@@@@@@@@@@@@@@@@@@@@@@@####&&&&&%%%%*******xxxxxxxxx+++++++++++++===========--------::::::......·····             
        ····.....:::::::--------------------:::::::::.......................::::---===++xxx**%%&&&###@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@###&&&&%%%%%********xxxxxxxxxxx++++++++++++========------::::::.....······            
        ····.....:::::--------------------------::::::::....................::::---===++xx***%%&&&####@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@###&&&&&%%%%%**********xxxxxxxxxxxxx+++++++++=======------:::::.....·····            
        ····....::::::-------=============---------:::::::::................:::::---===+++xx***%%%&&&#####@@@@@@@@@@@@@@@@@@@@@@@@@#####&&&&&%%%%%%*************xxxxxxxxxxxxxx+++++++++======-----:::::....·····            
         ····....:::::-------================---------:::::::::...............:::::----===++++xxx***%%%%&&&&&&#################&&&&&&%%%%%%%*******************xxxxxxxxxxxxxxxxx++++++++======----:::::....·····            
         ·····....:::::--------=================---------::::::::::..............:::::::-----====+++++xxxxxx**************************xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx++++++++=====-----::::....·····            
          ·····.....:::::--------=================----------:::::::::::.................:::::::::-------=============++++++++++++++++++++++++++++++++++++xxxxxxxxxxxxxxxxxxxxxxx++++++++======-----::::....·····            
            ·····.....:::::::----------===========-------------::::::::::::.........................::::::::::::::::::------------------=============+++++++++++++++++++++++++++++++++=======-----::::.....·····            
              ······......:::::::---------------------------------:::::::::::::........................................:::::::::::::::-----------============+++++++++++++++++++++========------:::::.....·····             
                 ······........:::::::::---------------------------:::::::::::::::::...........................................:::::::::::::------------=============================--------::::::.....······              
                    ·········.........:::::::::::::::-------------::::::::::::::::::::::::.......................................::::::::::::::::--------------------------------------::::::::......·······                
                          ··········............::::::::::::::::::::::::::::::::::::::::::::::::::................................::::::::::::::::::::::::::-------------:::::::::::::::.........········                   
                                  ············..................:::::::::::::::::::::::::::::::::::::::::::.........................:::::::::::::::::::::::::::::::::::::................···········                        
                                             ················.............................................................................................................·················                                 
                                                           ······················................................................................···························                                                
                                                                               ·········································································