Documentation

DigitalOcean VPS Setup

A complete walkthrough from creating a DigitalOcean Droplet to a live, HTTPS-secured SaleX store with its own PostgreSQL database on the same server. No Supabase account is needed. The same steps work on any Ubuntu VPS (Hetzner, Vultr, Linode, Contabo…) — only the dashboard screens differ.

On this page

What you will build

One Droplet (virtual server) running everything: Nginx in front, the SaleX Node.js app behind it, and PostgreSQL on the same machine. The database only listens on localhost, so it is never exposed to the internet.

Visitor ──HTTPS──► Nginx (ports 80/443)
                      │
                      ▼
               SaleX / Next.js  (port 3000, managed by pm2)
                      │
                      ▼
          PostgreSQL (localhost:5432)      storage/ folder (uploads)
ItemRecommendationNotes
Droplet size2 vCPU / 4 GB RAMA 2 GB Droplet can work if you add swap (step 3), but builds are slower and tighter. Check current prices on DigitalOcean's pricing page.
Operating systemUbuntu 24.04 LTS (22.04 also works)All commands below are for Ubuntu.
DiskThe Droplet's default diskHolds the database and uploaded images. Grow it later if the catalog grows.
DomainYour own domainNeeded for HTTPS, emails and payment webhooks.
Your computerA terminal with ssh, scp/rsyncmacOS/Linux Terminal, or PowerShell / Git Bash on Windows 10/11.
Values in CAPS (such as YOUR_SERVER_IP and YOUR_DOMAIN.com) are placeholders — replace them with your own. Run server commands on the Droplet unless a step says “on your computer”.

1. Create the Droplet

  1. Create an SSH key on your computer

    An SSH key is safer than a password. Skip this if you already have one.

    # on your computer
    ssh-keygen -t ed25519 -C "salex-server"
    # then show the PUBLIC key (the one ending in .pub):
    cat ~/.ssh/id_ed25519.pub          # macOS / Linux
    type $env:USERPROFILE\.ssh\id_ed25519.pub   # Windows PowerShell

    Copy the whole line that starts with ssh-ed25519. Never share the file without .pub.

  2. Start a new Droplet

    Sign in to cloud.digitalocean.com → Create → Droplets.

  3. Choose the settings

    • Region: closest to most of your customers.
    • Image: Ubuntu 24.04 (LTS) x64.
    • Size: a shared CPU plan with 2 vCPU / 4 GB RAM (see the table above).
    • Authentication: choose SSH Key → New SSH Key → paste the public key from step 1.
    • Additional options: tick Enable backups (an extra safety net on top of the database backups in step 9) and Monitoring.
    • Hostname: for example salex-prod.
  4. Create and note the IP address

    Click Create Droplet. After a minute the Droplet shows a public IPv4 address — this is your YOUR_SERVER_IP.

    ✓ Success: the Droplet is listed with a green “active” dot and an IP address.

2. Point your domain at it

Create two DNS records at your domain registrar (or in DigitalOcean → Networking → Domains if you moved your nameservers there):

TypeHost / NameValue
A@YOUR_SERVER_IP
AwwwYOUR_SERVER_IP
# on your computer — should print YOUR_SERVER_IP once DNS has propagated
nslookup YOUR_DOMAIN.com
DNS can take a few minutes to a few hours. Keep going — you only need it to resolve before the HTTPS step. More detail: Domain, SSL & Email.

3. First login & secure the server

Log in as root for the first time only:

ssh root@YOUR_SERVER_IP
  1. Update the system

    apt update && apt upgrade -y

    If it says a restart is required, run reboot, wait a minute and log in again.

  2. Create a normal user for running SaleX

    Running a web app as root is risky, so create a user named deploy.

    adduser deploy
    usermod -aG sudo deploy
    rsync --archive --chown=deploy:deploy ~/.ssh /home/deploy

    The last line copies your SSH key so you can log in as deploy.

  3. Turn on the firewall

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

    ✓ Success: status is “active” and lists OpenSSH, 80 and 443. Port 5432 (PostgreSQL) and 3000 (the app) stay closed on purpose.

  4. Add swap memory (recommended)

    Building Next.js uses a lot of RAM. Swap prevents the build from being killed on smaller Droplets.

    fallocate -l 2G /swapfile
    chmod 600 /swapfile
    mkswap /swapfile
    swapon /swapfile
    echo '/swapfile none swap sw 0 0' >> /etc/fstab
    free -h
  5. Test the new user — in a second terminal

    # on your computer, in a NEW terminal window
    ssh deploy@YOUR_SERVER_IP
    sudo whoami      # should print: root

    Keep the original root window open until this works.

  6. Disable root and password logins

    Back in the root window, once the deploy login works:

    cat > /etc/ssh/sshd_config.d/00-hardening.conf <<'EOF'
    PermitRootLogin no
    PasswordAuthentication no
    EOF
    systemctl restart ssh
    apt install -y fail2ban

    fail2ban automatically blocks IPs that keep guessing SSH logins. From now on, log in as deploy and put sudo in front of admin commands.

    ✓ Success: ssh root@YOUR_SERVER_IP is now refused, while ssh deploy@YOUR_SERVER_IP still works.

If you also attach a DigitalOcean Cloud Firewall to the Droplet, allow inbound TCP 22, 80 and 443 there too — otherwise the site or HTTPS certificate request will time out even though ufw is correct.

4. Install Node.js, Nginx and Git

Logged in as deploy:

# Node.js 22 LTS
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

# Web server, git and tools
sudo apt install -y nginx git build-essential apache2-utils

# Verify
node -v && npm -v && nginx -v

✓ Success: Node prints v22.x and npm prints a version number. (apache2-utils is only used to make the admin password hash in step 6.)

5. Install PostgreSQL & create the database

This replaces Supabase. PostgreSQL runs on the same Droplet and SaleX connects to it over localhost.

  1. Install and start PostgreSQL

    sudo apt install -y postgresql postgresql-contrib
    sudo systemctl enable --now postgresql
    systemctl status postgresql --no-pager
  2. Create a user and an empty database

    This generates a strong random password made only of letters and digits, so it never needs URL-encoding. Save the printed password in a password manager — you need it for .env.

    DB_PASS=$(openssl rand -hex 24)
    echo "Database password: $DB_PASS"
    
    sudo -u postgres psql <<SQL
    CREATE USER salex WITH PASSWORD '$DB_PASS';
    CREATE DATABASE salex OWNER salex;
    SQL

    ✓ Success: the last command prints CREATE ROLE and CREATE DATABASE.

  3. Check the connection and that it is private

    # Should print a table with "1"
    PGPASSWORD="$DB_PASS" psql -h localhost -U salex -d salex -c "SELECT 1;"
    
    # Should show 127.0.0.1:5432 (and/or [::1]:5432) — NOT 0.0.0.0:5432
    sudo ss -ltnp | grep 5432
Your connection string will be postgresql://salex:DB_PASSWORD@localhost:5432/salex. On plain PostgreSQL there is no connection pooler, so DATABASE_URL and DIRECT_URL are the same value and you must not add ?pgbouncer=true (that flag is for Supabase’s pooler only).

6. Upload SaleX, configure and build

  1. Create the app folder on the server

    sudo mkdir -p /var/www/salex
    sudo chown deploy:deploy /var/www/salex
  2. Upload the project — on your computer

    Extract your SaleX package, then from the folder that contains it run one of these. Do not upload node_modules, .next or your local .env.

    # Option A — rsync (macOS / Linux / Git Bash). Safe to re-run for updates.
    rsync -av --exclude node_modules --exclude .next --exclude .env --exclude storage \
      ./salex/ deploy@YOUR_SERVER_IP:/var/www/salex/
    
    # Option B — private Git repository (run on the server)
    git clone https://github.com/YOU/YOUR_REPO.git /var/www/salex

    The --exclude storage part matters: it stops an update from overwriting the images customers and vendors have uploaded.

  3. Install dependencies — on the server

    cd /var/www/salex
    npm install
    npm run db:generate
  4. Create the production .env

    cp .env.example .env
    nano .env
    chmod 600 .env

    Set at least these values (generate the secret with openssl rand -base64 32 and use a new one, never your local value):

    DATABASE_URL="postgresql://salex:DB_PASSWORD@localhost:5432/salex"
    DIRECT_URL="postgresql://salex:DB_PASSWORD@localhost:5432/salex"
    APP_URL="https://YOUR_DOMAIN.com"
    NEXT_PUBLIC_SITE_URL="https://YOUR_DOMAIN.com"
    AUTH_SECRET="PASTE_GENERATED_SECRET"
    NODE_ENV="production"
    # + SMTP and payment variables — see Environment Configuration

    Save in nano with Ctrl+O, Enter, then exit with Ctrl+X. Full variable list: Environment Configuration.

  5. Create the tables

    npm run db:deploy

    ✓ Success: it lists the migrations being applied and ends without errors. It is safe to run again later.

  6. Create your admin account (once only)

    Make a bcrypt hash of the admin password you want, then seed. Use single quotes around the password so the shell does not mangle special characters. A command that starts with a space is not saved in the shell history on Ubuntu.

     HASH=$(htpasswd -bnBC 10 "" 'YOUR_ADMIN_PASSWORD' | tr -d ':\n' | sed 's/^\$2y/\$2b/')
    
    SEED_SUPER_ADMIN_EMAIL="you@YOUR_DOMAIN.com" \
    SEED_SUPER_ADMIN_PASSWORD_HASH="$HASH" \
    npm run db:seed
    Run db:seed once. Never run db:migrate, a second seed or any reset command on a database that has real orders.
  7. Build the production version

    npm run build

    ✓ Success: “Compiled successfully” and a route listing. If you see Killed or exit code 137, the server ran out of memory — add swap (step 3) and rebuild.

7. Keep it running with pm2

sudo npm install -g pm2
cd /var/www/salex
pm2 start npm --name salex -- start
pm2 save
pm2 startup

pm2 startup prints one line beginning with sudo env PATH=…. Copy that exact line and run it, then run pm2 save again. This makes SaleX start automatically after a reboot.

pm2 status                          # salex should be "online"
curl -I http://localhost:3000       # should return HTTP 200 (or a redirect)
pm2 logs salex --lines 50           # view recent app logs

8. Nginx & free HTTPS

sudo tee /etc/nginx/sites-available/salex > /dev/null <<'EOF'
server {
    listen 80;
    server_name YOUR_DOMAIN.com www.YOUR_DOMAIN.com;
    client_max_body_size 20m;   # allow product image uploads

    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
    }
}
EOF

sudo ln -s /etc/nginx/sites-available/salex /etc/nginx/sites-enabled/
sudo rm -f /etc/nginx/sites-enabled/default
sudo nginx -t && sudo systemctl reload nginx

Once your domain resolves to the Droplet (step 2), request a free Let’s Encrypt certificate:

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

✓ Success: https://YOUR_DOMAIN.com loads the storefront with a padlock, and /admin accepts your seeded login. Certificates renew automatically.

Next, complete the First-Time Setup checklist (store name, currency, payments, shipping, email) and change the admin password if needed.

9. Automatic backups

With your own database, backups are your responsibility. A complete backup is the database plus the storage/ uploads folder. This script saves both every night and deletes copies older than 14 days.

sudo tee /usr/local/bin/salex-backup.sh > /dev/null <<'EOF'
#!/usr/bin/env bash
set -euo pipefail

BACKUP_DIR=/var/backups/salex
APP_DIR=/var/www/salex
STAMP=$(date +%F)

# Backups contain customer data: readable only by root and the deploy user
umask 027
install -d -m 2750 -o root -g deploy "$BACKUP_DIR"

# Database (runs as the postgres system user, so no password is needed)
sudo -u postgres pg_dump salex | gzip > "$BACKUP_DIR/db-$STAMP.sql.gz"

# Uploaded media
if [ -d "$APP_DIR/storage" ]; then
  tar -czf "$BACKUP_DIR/storage-$STAMP.tar.gz" -C "$APP_DIR" storage
fi

# Keep 14 days
find "$BACKUP_DIR" -type f -mtime +14 -delete
EOF

sudo chmod +x /usr/local/bin/salex-backup.sh
sudo /usr/local/bin/salex-backup.sh && ls -lh /var/backups/salex

Schedule it daily at 03:00 using root’s crontab:

sudo crontab -e
# add this line at the bottom:
0 3 * * * /usr/local/bin/salex-backup.sh >> /var/log/salex-backup.log 2>&1

Copy backups off the server

Backups stored only on the Droplet are lost if the Droplet is lost. Also keep a copy elsewhere — for example pull them to another machine, or push them to DigitalOcean Spaces or any S3-compatible storage with a tool such as rclone:

# on another computer/server: pull the backup folder
rsync -av deploy@YOUR_SERVER_IP:/var/backups/salex/ ./salex-backups/
The script makes the backup folder readable only by root and the deploy user, because the dumps contain customer data. The Droplet backups you enabled in step 1 are a useful second layer, but they are periodic whole-server snapshots — keep the nightly dumps too.

Test a restore (do this once)

An untested backup is only a hope. Restore into a throw-away database to prove it works:

sudo -u postgres createdb salex_restore_test
gunzip -c /var/backups/salex/db-YYYY-MM-DD.sql.gz | sudo -u postgres psql salex_restore_test
sudo -u postgres psql salex_restore_test -c "SELECT count(*) FROM information_schema.tables WHERE table_schema='public';"
sudo -u postgres dropdb salex_restore_test

To restore for real, stop the app (pm2 stop salex), restore into the live database, unpack storage-….tar.gz into /var/www/salex, then pm2 start salex. See also Security & Backups.

Optional: DigitalOcean Managed PostgreSQL

If you would rather not look after the database yourself, DigitalOcean sells a managed PostgreSQL cluster with automatic backups. It costs extra but replaces steps 5 and 9 for the database part. In short:

  1. Create the cluster in the same region as the Droplet (Create → Databases → PostgreSQL).
  2. Add the Droplet as a Trusted Source so only your server can connect.
  3. Create a database named salex (the default one is defaultdb) and copy the connection details from the dashboard.
  4. Fill in .env using the dashboard’s connection string, which includes sslmode=require. Use the direct connection for DIRECT_URL. For DATABASE_URL use the direct connection too, or a connection pool — if the pool is in transaction mode, add pgbouncer=true.
  5. Continue from npm run db:deploy in step 6. Uploaded media still lives in storage/, so keep backing that folder up.
Copy the exact host, port and options from your own dashboard — they differ per cluster. The pooled-vs-direct rules are the same as in Supabase Setup.

Common problems

SymptomLikely causeFix
db:deploy says it cannot reach the database server (P1001)PostgreSQL stopped, or wrong host/port in .envsudo systemctl status postgresql; make sure the URL says localhost:5432.
“password authentication failed for user salex”Wrong password in .env, or special characters not URL-encodedReset it: sudo -u postgres psql -c "ALTER USER salex WITH PASSWORD 'NEW_HEX_PASSWORD';" and update both URLs. Use a hex password (openssl rand -hex 24).
“permission denied to create extension”A migration needs an extension that only a superuser may createCreate it once as the postgres user, then re-run db:deploy: sudo -u postgres psql -d salex -c "CREATE EXTENSION IF NOT EXISTS EXTENSION_NAME;" (the error names the extension).
npm run build shows Killed / exit 137Out of memoryAdd swap (step 3) or resize the Droplet, then rebuild.
Browser shows 502 Bad GatewayThe app is not runningpm2 status then pm2 logs salex; restart with pm2 restart salex.
Changed .env but nothing changedVariables are only read at startuppm2 restart salex --update-env
Certbot fails or the site times out from outsideDNS not pointing yet, or ports 80/443 blockedCheck nslookup, sudo ufw status and any DigitalOcean Cloud Firewall.
Product images vanished after an updateThe storage/ folder was overwritten or deletedRestore it from the latest storage-….tar.gz, and keep --exclude storage in your upload command.
Locked out of SSHHardening applied before the deploy login was testedUse the Droplet’s Access → Recovery Console in the DigitalOcean dashboard to fix /etc/ssh/sshd_config.d/00-hardening.conf.

More solutions: Troubleshooting. For routine updates after launch, follow Updating safely — back up first, and keep your database on the same db:deploy workflow.