Running a Node.js application as a foreground process may work during development, but a production server needs a repeatable way to start, stop, restart, observe, and update that process. This deployment guide shows how to run a Node.js app as a Linux service with systemd, including a service file, environment variables, logs, restart behavior, permissions, migrations, release checks, and rollback steps.
Overview
systemd is the service manager commonly used by modern Linux distributions. A systemd unit describes what command to run, which user should run it, where it should run, when it should start, and how it should respond when the process exits.
The examples below assume:
- The application lives at
/srv/myapp/current. - The application has a production start script, such as
npm run start. - The application listens on a local port such as
3000. - A dedicated Linux user named
myappowns or runs the application. - A reverse proxy, if needed, forwards public traffic to that local port.
Keeping the Node.js process behind a reverse proxy is a separate concern from managing the process itself. For routing several applications and adding HTTPS, see the Nginx reverse proxy setup guide.
Before creating the service, confirm the runtime version and application command manually. From the application directory, run the equivalent of npm ci --omit=dev followed by npm run start, or use the package manager and command defined by the project. A service manager cannot compensate for a missing dependency, an invalid environment variable, or an application that fails during startup.
What to track
1. The service definition
Create a unit at /etc/systemd/system/myapp.service:
[Unit]
Description=My Node.js application
After=network.target
[Service]
Type=simple
User=myapp
Group=myapp
WorkingDirectory=/srv/myapp/current
EnvironmentFile=/etc/myapp/myapp.env
ExecStart=/usr/bin/npm run start
Restart=on-failure
RestartSec=5
# Give the process a predictable shutdown window
TimeoutStopSec=30
[Install]
WantedBy=multi-user.target
Adjust ExecStart to the actual path on the server. Node version managers often place Node and npm in a user-specific directory rather than /usr/bin. A system service does not automatically load a shell profile, so do not assume that a version manager configured for interactive SSH sessions will be available to systemd. Use an explicit executable path, or create a small, controlled wrapper script that loads the intended runtime.
Restart=on-failure restarts the service when it exits unsuccessfully, while avoiding a restart after a deliberate clean stop. A restart policy is useful for transient failures, but it is not a substitute for finding the cause of repeated crashes. Keep the delay long enough to avoid an unnecessarily tight restart loop.
2. Environment and secrets
Place production configuration outside the release directory, for example at /etc/myapp/myapp.env:
NODE_ENV=production
PORT=3000
DATABASE_URL=replace-with-your-secret
Restrict access to the environment file:
sudo install -d -o root -g myapp -m 0750 /etc/myapp
sudo chown root:myapp /etc/myapp/myapp.env
sudo chmod 0640 /etc/myapp/myapp.env
Use the format supported by your systemd version and application. Avoid putting secrets directly in the unit file, shell history, deployment logs, or source repository. If the application needs a variable containing spaces or special characters, test the exact parsing behavior rather than assuming that a shell script and an EnvironmentFile behave identically.
3. Ownership and permissions
The dedicated myapp user should be able to read the application files and write only to directories that genuinely require runtime writes, such as a temporary or upload directory. The service should not run as root merely to bypass a permissions problem. Check ownership, file modes, and the permissions of every parent directory:
sudo -u myapp test -r /srv/myapp/current/package.json
sudo -u myapp test -x /srv/myapp/current
sudo -u myapp /usr/bin/npm run start
4. Logs and health signals
By default, standard output and error can be collected by the journal. Useful commands include:
sudo systemctl status myapp
sudo journalctl -u myapp -n 100 --no-pager
sudo journalctl -u myapp -f
sudo journalctl -u myapp --since "1 hour ago"
Track whether the service is active, whether its restart count is increasing, whether startup errors repeat, and whether the application responds on its expected local port. If the application exposes a health endpoint, check it locally before diagnosing the reverse proxy or DNS layer.
Cadence and checkpoints
Use a small deployment checklist every time you install or update the service:
- Confirm the supported Node.js version and package manager for the application.
- Build or install dependencies in a new release directory rather than modifying the active release in place.
- Run tests, lint checks, and any required build command before switching releases.
- Review environment variables and confirm that database connectivity is available.
- Run database migrations as a deliberate, separately logged step when the application requires them.
- Update the
currentsymlink or service path only after the new release is ready. - Run
sudo systemctl daemon-reloadif the unit changed, then restart the service. - Check status, recent journal entries, the local health endpoint, and the public endpoint.
- Record the release identifier, migration result, and rollback decision in the deployment log.
For an initial installation, enable and start the service with:
sudo systemctl daemon-reload
sudo systemctl enable myapp
sudo systemctl start myapp
sudo systemctl status myapp
For ordinary application releases, the unit usually does not change, so daemon-reload is unnecessary. Restart only after the new files and configuration are in place. If a deployment pipeline performs these actions, keep the same checkpoints visible in its output. A GitHub Actions workflow can automate the sequence, but the server should still have a clear, manually verifiable service state. The GitHub Actions deployment guide provides broader CI/CD context.
Review service behavior monthly or quarterly, depending on how often the application changes. Check the Node.js runtime, dependency installation process, disk usage, journal retention, backup assumptions, exposed ports, and the documented rollback procedure. Also review the service after a server rebuild, operating system upgrade, runtime upgrade, or change to the database schema.
How to interpret changes
A failed start has a different meaning from a service that starts and then repeatedly exits. Begin with:
sudo systemctl status myapp --no-pager
sudo journalctl -u myapp -b --no-pager
If systemd reports 203/EXEC, inspect the executable path and permissions in ExecStart. If the application reports a missing module, install dependencies in the release directory with the intended Node.js version. If it reports a missing configuration value, inspect the environment file and confirm that systemd can read it as configured.
A service that is active but unreachable may be listening on the wrong address or port. Check the application configuration and listen sockets locally. Then inspect the reverse proxy configuration, firewall rules, and DNS separately. DNS changes do not repair a process that is not listening, and restarting systemd will not correct an incorrect DNS record. For related domain diagnosis, use the DNS propagation check guide.
Repeated restarts usually indicate an application error, incompatible runtime, failed migration, unavailable dependency, or insufficient permissions. Temporarily increasing logging can help, but avoid responding by setting an unlimited restart loop or running the service as root. When a release fails, stop further automation, preserve the journal output, and return to the last known-good release.
Safe updates and rollback
A simple release layout makes rollback clearer:
/srv/myapp/
releases/
2026-10-30-1200/
2026-10-29-1630/
current -> releases/2026-10-30-1200
Build and validate the new directory first. Point current to it, restart the service, and verify the health check. If the process fails, point current back to the previous release and restart. Database changes need additional care: a code rollback may not be safe if a migration removed or changed data. Prefer backward-compatible migrations when possible, and define a recovery plan before applying destructive changes.
When to revisit
Revisit this setup at least quarterly and immediately after any event that changes the service’s assumptions. The most important triggers are a new Node.js major version, a Linux distribution upgrade, a change in the package manager, a move to a new server, a new database migration pattern, or a change from direct hosting to containers. If the application moves to Docker, compare this workflow with the Docker deployment guide rather than running two process managers without a clear reason.
During each review, run a controlled restart, verify that the service starts after a reboot, inspect recent logs, confirm the environment file permissions, and test rollback in a non-production environment. Remove obsolete releases only after the current and previous known-good versions are identified. Confirm that monitoring or an alerting process can distinguish a healthy service from a process that is merely running.
For a practical next step, create the unit with the smallest working configuration, start the app manually as the dedicated user, then move one responsibility at a time into systemd. After every change, check systemctl status, follow journalctl -u myapp -f, and test the application locally. This turns a one-time Node.js deployment into a repeatable Linux service that can be maintained, reviewed, and safely updated.