Deploying on a VPS

A VPS from DigitalOcean, Hetzner, Vultr, Linode or similar is an empty Linux computer on the public internet. The company gives you an IP address and a login, and everything after that is your job. Commands on this page assume Ubuntu, and the order matters.

• What you get: an IP address, a root login, and a bare operating system.
• What you do not get: security, backups, HTTPS, monitoring or a way to deploy. Those are all yours.
• Choosing a plan: an Ubuntu LTS image, a location near your users, and at least 1 GB of RAM for a small app.
• Use an SSH key at purchase: most providers let you add one when creating the server.

Your first job is to connect over SSH and install every security update. The image your provider used may be weeks old, and its known bugs are public.

• Connect: use the IP address and login from your provider.
• Update: apt pulls down the latest fixes. Reboot if the kernel changed.
• Automatic updates: unattended-upgrades keeps installing security fixes after today.

ssh root@203.0.113.10

apt update && apt upgrade -y
apt install -y unattended-upgrades
dpkg-reconfigure -plow unattended-upgrades
reboot

Password login on port 22 is the first thing bots attack. Replace it with SSH keys, which cannot realistically be guessed, and work as a normal user who uses sudo.

• Create a user: day-to-day work should not happen as root.
• Use keys: your laptop holds a private key, and the server holds the public half.
• Disable root and passwords: only after you have tested the new login.

adduser deploy
usermod -aG sudo deploy

# from your laptop
ssh-copy-id deploy@203.0.113.10

# in /etc/ssh/sshd_config
PermitRootLogin no
PasswordAuthentication no

sudo systemctl restart ssh

Any program listening on a public port can be reached by the whole world. A firewall blocks everything by default, and you open only what you mean to.

• Open: SSH, plus 80 and 443 for the web. Usually nothing else.
• Keep private: databases, admin panels, and your app's own port.
• Docker warning: ports published with Docker can bypass UFW rules. Bind them to 127.0.0.1 instead.
• Provider firewall: many companies offer one too, and using both is fine.

sudo ufw allow OpenSSH
sudo ufw allow 80,443/tcp
sudo ufw enable
sudo ufw status

Fail2ban watches your logs and blocks addresses that keep failing to log in. With SSH keys in place it is an extra layer, and it keeps your logs far quieter.

• How it works: it reads login failures, then adds a temporary firewall ban.
• Default on Ubuntu: installing it turns on protection for SSH.
• Other services: jails can also protect Nginx and other logins.

sudo apt install -y fail2ban
sudo systemctl enable --now fail2ban
sudo fail2ban-client status sshd

Domain names are bought separately, from a registrar. You add an A record that points your domain at your VPS IP, and browsers can then find you by name.

• A record: links a name such as example.com to an IPv4 address.
• www: add a second record for www, or redirect it.
• TTL: how long others may cache the answer. Changes can take minutes to hours to spread.

Type   Name   Value            TTL
A      @      203.0.113.10     300
A      www    203.0.113.10     300

# check it from your laptop
dig +short example.com

Running your app in an SSH session ties its life to that session. A process manager like systemd, or Docker with a restart policy, starts it at boot and restarts it after a crash.

• systemd: built into Ubuntu, and all you need for one app.
• Docker Compose: good when you have several containers. Use restart: unless-stopped.
• Environment files: keep secrets in a file only that user can read, never in Git.
• Run as a normal user: a bug in your app should not hand out root.

# /etc/systemd/system/app.service
[Unit]
Description=My app
After=network.target

[Service]
User=deploy
WorkingDirectory=/home/deploy/app
EnvironmentFile=/home/deploy/app/.env
ExecStart=/usr/bin/node server.js
Restart=always

[Install]
WantedBy=multi-user.target

# then
sudo systemctl enable --now app

Your app listens on a private port such as 3000. Nginx, or Caddy, faces the internet on ports 80 and 443 and passes requests to it. One server can then host many sites.

• Clean URLs: visitors use example.com, with no port number.
• One front door: HTTPS, compression and rate limits all live in one place.
• Static files: Nginx serves them directly, so your app does not have to.
• Many sites: route by domain name to different apps on the same VPS.

# /etc/nginx/sites-available/app
server {
    listen 80;
    server_name example.com www.example.com;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

sudo ln -s /etc/nginx/sites-available/app /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx

HTTPS encrypts everything between the browser and your server. Certificates from Let's Encrypt are free, and Certbot can install and renew them for you.

• Certificate: proves that you control the domain.
• Certbot: requests a certificate and edits your Nginx config.
• Renewal: certificates are short-lived, so Certbot sets up automatic renewal.
• Caddy: an alternative web server that handles HTTPS with almost no setup.

sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d example.com -d www.example.com

# prove that renewal works
sudo certbot renew --dry-run

A database should talk only to your app, never to the internet. Bind it to localhost, give it a strong password, and connect through an SSH tunnel when you need to look inside.

• Bind to localhost: PostgreSQL does this by default. Do not change it to all addresses.
• Docker: publish with 127.0.0.1:5432:5432, or do not publish at all.
• Separate user: give the app its own login with only the rights it needs.
• Remote access: use an SSH tunnel instead of opening the port.

# docker-compose.yml: reachable from this machine only
ports:
  - "127.0.0.1:5432:5432"

# look inside from your laptop, through SSH
ssh -L 5432:127.0.0.1:5432 deploy@203.0.113.10

Small servers run out of memory quickly. When that happens, Linux kills a process to save itself, and the victim is often your database. Swap gives you breathing room by using disk as slow overflow.

• OOM killer: the part of Linux that picks a process to kill when memory runs out.
• Swap: overflow space on disk. Slow, but much better than a crash.
• Limits: cap memory for each container, so one app cannot starve the others.
• Check: free -h shows memory, and dmesg shows whether the OOM killer has struck.

sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

A VPS is one disk in someone else's building. Backups must live outside that server, ideally with another company, and they only count once you have restored from them.

• Automate: a scheduled job, because manual backups stop happening.
• Off-site: send copies to object storage, such as S3 or Backblaze B2.
• Snapshots: provider snapshots are handy, but they share your account and your provider.
• Test restores: practise on a spare server. An untested backup is only a hope.
• Encrypt: a backup holds all your data, so protect it like the database.

#!/bin/sh
# /usr/local/bin/backup.sh
pg_dump -U app shop | gzip > /tmp/shop.sql.gz
rclone copy /tmp/shop.sql.gz b2:my-backups/
rm /tmp/shop.sql.gz

# crontab -e: every night at 02:30
30 2 * * * /usr/local/bin/backup.sh

Nobody is watching your server unless you arrange it. You need something outside the server to check that it is up, and alerts for the slow problems, like a disk filling with logs.

• Uptime check: an outside service that requests your site every minute and alerts you.
• Resource alerts: warn at about 80% disk and memory, while there is still time to act.
• Log rotation: logrotate and Docker log limits stop logs growing forever.
• Self-hosted: tools like Uptime Kuma are good, but should not run on the server they watch.

# how full is the disk?
df -h

# what is using it?
sudo du -h /var --max-depth=2 | sort -h | tail

# cap Docker logs in /etc/docker/daemon.json
{ "log-opts": { "max-size": "10m", "max-file": "3" } }

Copying files by hand works once and fails later. A pipeline makes every deploy the same: test, build, send to the server, restart, check it is healthy.

• GitHub Actions: runs on merge, using an SSH key stored as a secret.
• A limited key: give CI its own deploy user, not your personal key.
• Versioned images: tag each release so going back is one command.
• Health check: after deploying, confirm the site answers before calling it done.

# .github/workflows/deploy.yml (the last job)
- name: Deploy
  run: |
    ssh deploy@203.0.113.10 '
      cd app &&
      docker compose pull &&
      docker compose up -d &&
      curl -f http://127.0.0.1:3000/health
    '

One well-set-up VPS can carry a surprising amount of traffic, and it is cheap and simple. It is still a single machine, though, so plan what happens when it fails or fills up.

• Single point of failure: if the host dies, so does everything on it.
• First upgrade: a bigger plan is the quickest step.
• Split the database: move it to its own server or a managed service.
• Then scale out: add a second app server behind a load balancer.