Deploy a Node.js or Python web app

With Node.js

The example is a small Express app. Node.js is developed by its contributors as a project of the OpenJS Foundation, and is open source under the MIT licence. The packages come from NodeSource's apt repository, deb.nodesource.com, which the server contacts on every apt update. npm downloads your app's dependencies from registry.npmjs.org, and by default also checks it for a newer npm, which the deploy below switches off.

With Python

The example is a small Flask app run by gunicorn, with a note for FastAPI. Python is developed by its community under the Python Software Foundation, a US non-profit, and is open source under the PSF licence. It comes from Debian's own packages. pip downloads your app's dependencies from PyPI, pypi.org, which the Python Software Foundation runs.

With Node.js

Debian 13 ships Node.js 20, whose support from the Node.js project ended in April 2026. NodeSource builds each Node.js release line as Debian packages, so you get the current long-term support version, 24, and its updates arrive through apt like everything else. A version manager such as nvm installs Node.js into one user's home and never updates it by itself: fine on a laptop, not on a server.

As root, add NodeSource's signing key and repository:

apt update
apt install -y curl
curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key -o /etc/apt/keyrings/nodesource.asc

Create /etc/apt/sources.list.d/nodesource.sources:

Types: deb
URIs: https://deb.nodesource.com/node_24.x
Suites: nodistro
Components: main
Signed-By: /etc/apt/keyrings/nodesource.asc

Install Node.js, which brings npm with it, and Caddy and Git from Debian:

apt update
apt install -y nodejs caddy git
node -v

v24.21.0

Debian's automatic updates only install from Debian. To let them install Node.js updates too, create /etc/apt/apt.conf.d/51unattended-upgrades-nodesource:

Unattended-Upgrade::Origins-Pattern {
    "site=deb.nodesource.com";
};

Check that it is picked up:

unattended-upgrade --dry-run --debug 2>&1 | grep 'Allowed origins'

The line ends with site=deb.nodesource.com.

With Python

Debian's Python gets security updates from Debian's security team, which install by themselves on a server set up as in the security guide. Your app's own packages go in a virtual environment (venv), a directory of their own, so they never mix with Debian's.

As root:

apt update
apt install -y python3-venv caddy git curl
python3 -V

Python 3.13.5

With Python

Create the venv for the app:

runuser -u myapp -- python3 -m venv /home/myapp/venv

With Node.js

The example app, server.js:

const express = require('express');

const app = express();
// Caddy on this server passes the visitor's address in X-Forwarded-For.
app.set('trust proxy', 'loopback');

app.get('/', (req, res) => {
  res.send(`Hello from Node.js ${process.version}. Your address: ${req.ip}, via ${req.protocol}\n`);
});

const port = process.env.PORT || 3000;
const server = app.listen(port, '127.0.0.1', () => {
  console.log(`Listening on 127.0.0.1:${port}`);
});

// On a restart, finish the requests that are open before exiting.
process.on('SIGTERM', () => {
  console.log('SIGTERM: finishing open requests');
  server.close(() => process.exit(0));
});

trust proxy set to loopback makes req.ip the visitor's address when the request comes from Caddy on the same server, and ignores the header from anywhere else. npm ci on the server installs exactly what package-lock.json lists, so commit that file.

With Python

The example app, app.py:

import sys

from flask import Flask, request
from werkzeug.middleware.proxy_fix import ProxyFix

app = Flask(__name__)
# Caddy on this server passes the visitor's address in X-Forwarded-For.
app.wsgi_app = ProxyFix(app.wsgi_app, x_for=1, x_proto=1, x_host=1)


@app.get("/")
def index():
    return f"Hello from Python {sys.version.split()[0]}. Your address: {request.remote_addr}, via {request.scheme}\n"

And requirements.txt:

flask==3.1.*
gunicorn==26.*

gunicorn trusts X-Forwarded-Proto from 127.0.0.1 by default, so the app knows the visitor came over HTTPS, but it does not take the visitor's address from X-Forwarded-For. Without ProxyFix, the app sees every visitor as 127.0.0.1. gunicorn already finishes open requests when it stops.

FastAPI: run it in gunicorn with uvicorn's worker. Add uvicorn-worker to requirements.txt, and in step 5 replace app:app with -k uvicorn_worker.UvicornWorker main:app. uvicorn trusts the headers from 127.0.0.1 by default, so you need no ProxyFix. This was tested with FastAPI 0.142 under the same service, including the reload in step 10.

With Node.js

install -m 600 /dev/null /etc/myapp.env
printf 'PORT=3000\nSESSION_SECRET=%s\n' "$(openssl rand -hex 32)" >> /etc/myapp.env

With Python

install -m 600 /dev/null /etc/myapp.env
printf 'SECRET_KEY=%s\n' "$(openssl rand -hex 32)" >> /etc/myapp.env

With Node.js

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

[Unit]
Description=myapp (Node.js)
After=network.target

[Service]
User=myapp
Group=myapp
WorkingDirectory=/home/myapp/app
EnvironmentFile=/etc/myapp.env
Environment=NODE_ENV=production
ExecStart=/usr/bin/node server.js
Restart=on-failure
RestartSec=2

# Hardening
NoNewPrivileges=yes
ProtectSystem=strict
ProtectHome=read-only
PrivateTmp=yes
PrivateDevices=yes
ProtectKernelTunables=yes
ProtectKernelModules=yes
ProtectKernelLogs=yes
ProtectControlGroups=yes
ProtectClock=yes
ProtectHostname=yes
RestrictAddressFamilies=AF_INET AF_INET6 AF_UNIX
RestrictNamespaces=yes
RestrictSUIDSGID=yes
RestrictRealtime=yes
LockPersonality=yes
CapabilityBoundingSet=
SystemCallArchitectures=native
SystemCallFilter=@system-service
UMask=0077

[Install]
WantedBy=multi-user.target

Leave out MemoryDenyWriteExecute=yes, which other hardening lists include: Node.js compiles JavaScript into machine code as it runs, and crashes at once with it.

With Python

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

[Unit]
Description=myapp (Python)
After=network.target

[Service]
User=myapp
Group=myapp
WorkingDirectory=/home/myapp/app
EnvironmentFile=/etc/myapp.env
ExecStart=/home/myapp/venv/bin/gunicorn --bind 127.0.0.1:8000 --workers 2 --no-control-socket app:app
ExecReload=/bin/kill -s HUP $MAINPID
Restart=on-failure
RestartSec=2

# Hardening
NoNewPrivileges=yes
ProtectSystem=strict
ProtectHome=read-only
PrivateTmp=yes
PrivateDevices=yes
ProtectKernelTunables=yes
ProtectKernelModules=yes
ProtectKernelLogs=yes
ProtectControlGroups=yes
ProtectClock=yes
ProtectHostname=yes
RestrictAddressFamilies=AF_INET AF_INET6 AF_UNIX
RestrictNamespaces=yes
RestrictSUIDSGID=yes
RestrictRealtime=yes
LockPersonality=yes
MemoryDenyWriteExecute=yes
CapabilityBoundingSet=
SystemCallArchitectures=native
SystemCallFilter=@system-service
UMask=0077

[Install]
WantedBy=multi-user.target

app:app means the object app in app.py. --no-control-socket switches off the control socket that gunicorn 26 opens in the user's home, which the read-only home would turn into an error at every start. ExecReload lets systemctl reload reload the app gracefully, as step 10 shows.

With Node.js

Create /home/myapp/app.git/hooks/post-receive:

#!/bin/sh
# Deploy every push to main: check out the code, install dependencies, restart.
set -e
while read -r old new ref; do
  [ "$ref" = refs/heads/main ] || continue
  git --work-tree="$HOME/app" checkout -f -q main
  cd "$HOME/app"
  npm ci --omit=dev --no-audit --no-fund --no-update-notifier
  sudo systemctl reload-or-restart myapp.service
  echo "Deployed $new"
done

With Python

Create /home/myapp/app.git/hooks/post-receive:

#!/bin/sh
# Deploy every push to main: check out the code, install dependencies, reload.
set -e
while read -r old new ref; do
  [ "$ref" = refs/heads/main ] || continue
  git --work-tree="$HOME/app" checkout -f -q main
  cd "$HOME/app"
  "$HOME/venv/bin/pip" install -q -r requirements.txt
  sudo systemctl reload-or-restart myapp.service
  echo "Deployed $new"
done

With Node.js

remote: added 68 packages in 2s
remote: Deployed 6f3dbefd446c5710ef8d159e346792a021949777
To app.example.com:app.git
 * [new branch]      main -> main

With Python

remote: Deployed 5bf1717456588772fdf3bdd2f91182806d035cb4
To app.example.com:app.git
 * [new branch]      main -> main

With Node.js

systemctl is-active myapp
curl -s http://127.0.0.1:3000/

active
Hello from Node.js v24.21.0. Your address: 127.0.0.1, via http

With Python

systemctl is-active myapp
curl -s http://127.0.0.1:8000/

active
Hello from Python 3.13.5. Your address: 127.0.0.1, via http

With Node.js

{
    email you@example.com
}

app.example.com {
    reverse_proxy 127.0.0.1:3000 {
        # While the app restarts, hold requests for up to 5 seconds instead of answering 502.
        lb_try_duration 5s
    }
}

With Python

{
    email you@example.com
}

app.example.com {
    reverse_proxy 127.0.0.1:8000 {
        # While the app restarts, hold requests for up to 5 seconds instead of answering 502.
        lb_try_duration 5s
    }
}

With Node.js

Hello from Node.js v24.21.0. Your address: 198.51.100.7, via https

With Python

Hello from Python 3.13.5. Your address: 198.51.100.7, via https

With Node.js

A single Node.js process cannot hand its port over to a new one, so every deploy is a restart. What you can do is make it invisible:

• Without lb_try_duration in the Caddyfile, 8 of 228 requests got 502 during a deploy: a gap of about 0.4 seconds.
• With lb_try_duration 5s, Caddy holds new requests until the new process listens: 222 of 222 got an answer, none failed.
• The SIGTERM handler in server.js lets requests that are already open finish. Without it, Node.js exits at once: a 3-second POST request sent just before a restart got 502. Caddy sends a cut-off GET again by itself, but not a POST. With the handler, the same POST finished normally.

If your app holds connections open for a long time, such as WebSockets or server-sent events, server.close waits for them, and systemd ends the process after 90 seconds, its default (not tested here). Those connections drop with every deploy, and the client has to reconnect.

Running several processes to take turns would close that last gap, but it needs a process manager or a second service and a load balancer setup, which is more than most apps need.

With Python

gunicorn can reload without a gap. On systemctl reload myapp, which the hook runs, the gunicorn master gets the HUP signal, starts new workers with the new code, and lets the old ones finish their requests before they exit. Its port stays open all the time.

• A systemctl restart myapp, without lb_try_duration in the Caddyfile: 11 of 126 requests got 502.
• A systemctl reload myapp: 140 of 140 got an answer.
• A git push of a new version: 245 of 245 got an answer, and the new text showed straight after.

The journal shows the reload:

[INFO] Hang up: Master
Reloaded myapp.service - myapp (Python).
[INFO] Booting worker with pid: 16461
[INFO] Booting worker with pid: 16463
[INFO] Worker exiting (pid: 15393)
[INFO] Worker exiting (pid: 15394)

A reload loads your app's code and packages again, but not gunicorn itself, which runs in the master. After you update gunicorn, or Python as in step 12, use systemctl restart myapp. lb_try_duration in the Caddyfile hides that restart too.

With Node.js

Updates within Node.js 24 install by themselves, with Debian's, through the file from step 1. The running app keeps the old version until it restarts. To check whether it needs one:

ls -l /proc/$(systemctl show -p MainPID --value myapp)/exe

lrwxrwxrwx 1 myapp myapp 0 Oct  2 19:05 /proc/17446/exe -> /usr/bin/node (deleted)

(deleted) means a newer Node.js is installed. Restart the app:

systemctl restart myapp

To move to the next long-term support line, such as 26, change node_24.x to node_26.x in /etc/apt/sources.list.d/nodesource.sources, then:

apt update
apt install -y nodejs

Then push an empty commit from your own computer, so that npm ci reinstalls the dependencies for the new version and the app restarts:

git commit --allow-empty -m "Redeploy on Node.js 26"
git push live main

Switching from 24 to 26 and back was tested this way.

With Python

Security updates to Python install by themselves with Debian's. The running app keeps the old version until it restarts. To check whether it needs one:

ls -l /proc/$(systemctl show -p MainPID --value myapp)/exe

If the link ends in (deleted), a newer Python is installed. Restart the app:

systemctl restart myapp

Your app's own packages update when you change requirements.txt and push.

The next Debian release brings a new Python version, and a venv only works with the version it was made with. After the upgrade, make the venv again as root:

rm -rf /home/myapp/venv
runuser -u myapp -- python3 -m venv /home/myapp/venv

Then push an empty commit from your own computer, so that pip installs the packages again:

git commit --allow-empty -m "Rebuild venv"
git push live main

Finish with systemctl restart myapp on the server, since a reload does not replace gunicorn itself. Making the venv again and pushing was tested. A Debian release upgrade was not.