For beginners

Deploy a Go and React app to a cheap VPS with HTTPS

A Go program compiles to one file with no runtime to install, which makes deploying it genuinely simple: copy the file to a computer on the internet and run it. Everything else, the proxy, the certificate, the service manager, exists to handle what happens when that computer reboots or somebody visits over HTTPS.

This goes from a fresh server to your app on your own domain with a valid certificate. It assumes nothing: if you do not know what systemd is, that is covered.

22 min read. Commands and output last run against Grit v3.560.0.

What you will have at the end

Your API and frontend reachable at https://yourdomain.com, with a certificate that renews itself.

A service that starts on boot and restarts if it crashes.

A server that is not trivially breakable: no password logins, a firewall, no root.

The four words you need

  • A VPS is a computer somebody else runs, that you get a root login to. Hetzner, DigitalOcean, Vultr and Linode all rent small ones for a few currency units a month, which is enough for a real application with real users.
  • systemd is the thing that starts programs when Linux boots and restarts them when they die. Without it, your app stops the moment you close your SSH session.
  • A reverse proxy sits in front of your app on ports 80 and 443, terminates HTTPS and forwards to your program on some internal port. Caddy, nginx and Traefik all do this; Caddy gets certificates by itself, which is why it is here.
  • A certificate is what makes the padlock appear. Let's Encrypt issues them free, for ninety days, automatically renewed.

01Get a server and a domain

Create the smallest instance your provider offers with Ubuntu LTS. Two vCPU and 2GB is comfortable for a Go API, Postgres and a Next.js frontend on one box. One vCPU and 1GB works and will make next build painful, which is an argument for building elsewhere, later on this page.

Point your domain at it. Two records, at your registrar:

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

Checkpoint. Wait a few minutes, then confirm the world agrees:

Terminal
$dig +short yourdomain.com
# 203.0.113.42

Do not move on until that prints your server's address. Certificate issuance checks DNS, so a deploy attempted before DNS has propagated fails in a way that looks like a Caddy problem and is not.

02Secure the server before anything is on it

A new server on a public address starts receiving password-guessing attempts within minutes. Ten minutes now, once.

Terminal
# From your own machine: copy your key up, so you never type a password
$ssh-copy-id root@203.0.113.42
$ssh root@203.0.113.42
Terminal
# On the server: a user that is not root
$adduser --disabled-password --gecos "" deploy
$usermod -aG sudo deploy
$rsync --archive --chown=deploy:deploy ~/.ssh /home/deploy/
/etc/ssh/sshd_config
PasswordAuthentication no
PermitRootLogin no
PubkeyAuthentication yes
Terminal
$systemctl restart ssh
$ufw allow OpenSSH
$ufw allow 80
$ufw allow 443
$ufw --force enable
$apt update && apt install -y unattended-upgrades

Open a second terminal before you log out

Confirm ssh deploy@203.0.113.42 works in a new window while the first one is still connected. If the key did not copy correctly, closing your only session locks you out of your own server, and the recovery is your provider's web console at best.

Note what is not open: nothing but SSH, 80 and 443. Postgres stays unreachable from the internet, and you reach it over an SSH tunnel when you need to. A database on a public port is found by scanners the same day.

03Build the binary, on your machine

Cross-compiling is one line, and it means the server needs no Go toolchain, no build dependencies and no memory to spare.

Terminal
$cd apps/api
$CGO_ENABLED=0 GOOS=linux GOARCH=amd64 \
go build -ldflags="-s -w" -o api-linux ./cmd/server
# -s -w drop the debug symbols: a smaller file to upload, and you are not
# debugging on the server anyway.
# CGO_ENABLED=0 produces a fully static binary with no libc dependency, so
# it runs on any Linux. Note: it also rules out the cgo SQLite driver, which
# is one more reason production uses Postgres.
Terminal
$scp api-linux deploy@203.0.113.42:/home/deploy/
$ssh deploy@203.0.113.42 'sudo mv ~/api-linux /usr/local/bin/myapp-api && sudo chmod +x /usr/local/bin/myapp-api'

Checkpoint. ssh deploy@... /usr/local/bin/myapp-api --version, or whatever your binary prints, runs without a "cannot execute" error. If it fails with Exec format error, you built for the wrong architecture: an Arm server needs GOARCH=arm64.

04Make systemd responsible for it

Running the binary over SSH works until you disconnect. A unit file hands it to the operating system.

/etc/systemd/system/myapp-api.service
[Unit]
Description=myapp API
After=network.target postgresql.service
[Service]
Type=simple
User=deploy
WorkingDirectory=/home/deploy/myapp
ExecStart=/usr/local/bin/myapp-api
# Restart on any exit, including a clean one, after five seconds. Without
# this a single panic takes the site down until somebody notices.
Restart=always
RestartSec=5
# Secrets live in a file only this user can read, not in this unit, which
# is world-readable.
EnvironmentFile=/home/deploy/myapp/.env
# Logs go to the journal, so journalctl can read them.
StandardOutput=journal
StandardError=journal
# Cheap hardening: no new privileges, a private /tmp, and a read-only
# system except for the one directory the app writes to.
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ReadWritePaths=/home/deploy/myapp
[Install]
WantedBy=multi-user.target
Terminal
$sudo chmod 600 /home/deploy/myapp/.env # before it has anything in it
$sudo systemctl daemon-reload
$sudo systemctl enable --now myapp-api
$systemctl status myapp-api

Checkpoint. active (running), and curl localhost:8080/health on the server answers. When it does not:

Terminal
$journalctl -u myapp-api -n 50 --no-pager # the last 50 lines
$journalctl -u myapp-api -f # follow it live

Nine times out of ten the journal says a configuration variable is missing or the database refused the connection, and it says so in plain words.

05Caddy, for the proxy and the certificate

This is the step that is traditionally painful and is now four lines, because Caddy requests and renews certificates on its own.

Terminal
$sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
$curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' \
| sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
$curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' \
| sudo tee /etc/apt/sources.list.d/caddy-stable.list
$sudo apt update && sudo apt install -y caddy
/etc/caddy/Caddyfile
yourdomain.com {
# The frontend: everything that is not /api
reverse_proxy localhost:3000
# The API
handle /api/* {
reverse_proxy localhost:8080
}
encode gzip zstd
header {
Strict-Transport-Security "max-age=31536000; includeSubDomains"
X-Content-Type-Options "nosniff"
X-Frame-Options "DENY"
Referrer-Policy "strict-origin-when-cross-origin"
}
log {
output file /var/log/caddy/access.log
}
}
www.yourdomain.com {
redir https://yourdomain.com{uri} permanent
}
Terminal
$sudo systemctl reload caddy
$journalctl -u caddy -f # watch the certificate being issued

Checkpoint. https://yourdomain.com loads with a padlock, and http:// redirects to it. Caddy did that redirect without being asked, and it will renew the certificate without being asked either.

Why not nginx

nginx is excellent and is what you will meet in most existing systems. For a first deploy Caddy removes certbot, a renewal cron job and about forty lines of configuration, and the gap in capability does not matter until you are doing something unusual. Learn nginx when something requires it.

06The frontend

A Next.js app with server components needs Node running. Building on a small server is the step that runs out of memory, so build where you have memory and ship the output.

Terminal
# locally
$cd apps/web && pnpm build
# the standalone output includes only the dependencies actually used
$rsync -avz --delete .next/standalone/ deploy@203.0.113.42:/home/deploy/myapp/web/
$rsync -avz .next/static/ deploy@203.0.113.42:/home/deploy/myapp/web/.next/static/
$rsync -avz public/ deploy@203.0.113.42:/home/deploy/myapp/web/public/

Then a second unit, the same shape as the first:

/etc/systemd/system/myapp-web.service
[Unit]
Description=myapp web
After=network.target
[Service]
Type=simple
User=deploy
WorkingDirectory=/home/deploy/myapp/web
Environment=PORT=3000
Environment=NODE_ENV=production
ExecStart=/usr/bin/node server.js
Restart=always
RestartSec=5
[Install]
WantedBy=multi-user.target

A purely static frontend is simpler still: no Node, no unit, just root * /home/deploy/myapp/web and file_server in the Caddyfile.

07A deploy script, so the next one is one command

You will deploy again today. Write this now, while every step is still in your head, because reconstructing it in three weeks is how a deploy becomes a nervous event.

deploy.sh
#!/usr/bin/env bash
set -euo pipefail # stop on the first failure rather than carrying on
HOST=deploy@203.0.113.42
APP=/home/deploy/myapp
echo "Building..."
(cd apps/api && CGO_ENABLED=0 GOOS=linux GOARCH=amd64 \
go build -ldflags="-s -w" -o api-linux ./cmd/server)
(cd apps/web && pnpm build)
echo "Uploading..."
scp apps/api/api-linux "$HOST:/tmp/api-new"
rsync -avz --delete apps/web/.next/standalone/ "$HOST:$APP/web/"
rsync -avz apps/web/.next/static/ "$HOST:$APP/web/.next/static/"
echo "Switching over..."
ssh "$HOST" bash -s <<'REMOTE'
set -euo pipefail
sudo mv /tmp/api-new /usr/local/bin/myapp-api
sudo chmod +x /usr/local/bin/myapp-api
sudo systemctl restart myapp-api myapp-web
# Wait for health rather than assuming. A deploy that reports success
# while the service is crash-looping is worse than one that fails.
for i in $(seq 1 30); do
if curl -fsS localhost:8080/health > /dev/null; then
echo "healthy"; exit 0
fi
sleep 1
done
echo "did not become healthy; check journalctl -u myapp-api" >&2
exit 1
REMOTE

There is a gap of a second or two where requests fail. For a first deploy that is acceptable. Closing it means running two copies and switching the proxy between them, which is a worthwhile second step and not a first one.

The database, and the backup you have not made

Run Postgres on the same box to begin with. It is one apt install, and the network hop disappears. Move it to a managed service when backups and failover matter more than the bill.

Terminal
$sudo apt install -y postgresql
$sudo -u postgres createuser --pwprompt myapp
$sudo -u postgres createdb --owner=myapp myapp

It listens on localhost only by default. Leave it that way. To connect from your laptop, tunnel:

Terminal
$ssh -L 5433:localhost:5432 deploy@203.0.113.42
# then connect to localhost:5433 as if it were local

A backup you have not restored is not a backup

Dump nightly, copy the dump off the server, and once, now, restore it into a scratch database and look at the data. People discover their backup was empty, or was the wrong database, at the only moment it matters.

#!/usr/bin/env bash
set -euo pipefail
pg_dump -Fc myapp > /tmp/myapp-$(date +%F).dump
# then copy it OFF this machine: object storage, another provider, anywhere
# that is not the disk you are backing up.

When it goes wrong

502 Bad Gateway

Caddy is working and your app is not answering on the port Caddy forwards to. Check the service is running, and check what it is actually listening on: an app bound to 127.0.0.1:8080 is fine here, but one bound to a different port than the Caddyfile names is the usual cause.

Terminal
$systemctl status myapp-api
$sudo ss -tlnp | grep 8080

Job for myapp-api.service failed because the control process exited with error code

The binary started and immediately stopped. The unit file tells you nothing; the journal tells you everything:

Terminal
$journalctl -u myapp-api -n 50 --no-pager

The frequent causes are a missing environment variable, a database that is not running, a port already in use, and the EnvironmentFile path being wrong, which fails silently as "variable not set".

Caddy cannot obtain a certificate

Three causes, in order of likelihood. DNS does not yet point at this server, so check dig +short yourdomain.com from somewhere other than the server. Port 80 is closed, and the challenge needs it even though your site is HTTPS. Or you have been retrying and hit Let's Encrypt's rate limit, which is five failures per hour per domain, so stop, fix DNS properly, and wait.

Permission denied on the binary or the env file

The unit runs as deploy, so deploy must be able to execute the binary and read .env. A file uploaded as root and left at mode 600 is unreadable by the service. ls -l on both, and remember that ProtectSystem=strict makes everything except ReadWritePaths read-only to the service, which is deliberate and occasionally surprising.

The site works and then stops after a few days

Usually the disk filled with logs, or the process was killed by the out-of-memory killer. Both are visible after the fact:

Terminal
$df -h # disk
$journalctl --disk-usage # how much of it is logs
$sudo journalctl --vacuum-time=7d # keep a week
$dmesg | grep -i "killed process" # the OOM killer, if it was that

If you would rather not do any of that

A platform does all of the above for you, at a higher price per unit of compute and with less to understand.

  • Railway, Render, Fly. Push to git, get a URL and a database. Pricing grows with usage, and at steady load a VPS is several times cheaper. The right choice when your time is the scarce resource.
  • Dokploy or Coolify on your own VPS. A deployment platform you host: the git push workflow and a web interface, on hardware you rent. A good middle ground, and more moving parts than this page.
  • Kubernetes. Not for a first deploy, and not for a second. It solves problems you do not yet have, at a cost in understanding that you will pay every week.

One command, for the same thing

Grit automates exactly the sequence above: cross-compile, upload, write the systemd unit, configure Caddy, issue the certificate, run migrations, and health-check before reporting success.

Terminal
$grit deploy --host yourdomain.com

It writes real systemd and Caddy configuration onto the server, which you can read and edit afterwards. That matters more than the convenience: the day something is wrong at three in the morning, you are reading a unit file like the one above and not a platform's dashboard. The VPS deployment guide has the full flow, including the rollback.

Frequently asked questions

How much server do I need?
Less than you think. A Go API serves thousands of requests a second on two cores, and the memory is dominated by Postgres and Node rather than by Go. Two vCPU and 2GB is a comfortable start for a real product. Scale up when a measurement says to, not when traffic feels like it is growing.
Should I deploy with Docker instead of a binary?
Docker makes the server identical to your development environment and adds a layer to debug through. A Go binary already has no runtime dependencies, so containers buy less here than in most ecosystems. Use Docker when you are running several services together, or when the platform you are deploying to expects an image.
How do I deploy without downtime?
Run two copies on different ports and point the proxy at the healthy one, switching after the new copy passes its health check. Caddy and nginx both support this. It is a worthwhile second step; a one-second gap during a deploy is not what is costing you users on day one.
Is a VPS secure enough for real customer data?
Yes, with the basics on this page: key-only SSH, a firewall, unattended security updates, a non-root service user, and the database not listening on a public address. What a managed platform really buys you is that somebody else remembers to apply patches. If that somebody is not going to be you, use a platform.

Next steps