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 TTLA @ 203.0.113.42 300A www 203.0.113.42 300
Checkpoint. Wait a few minutes, then confirm the world agrees:
$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.
# 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
# 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/
PasswordAuthentication noPermitRootLogin noPubkeyAuthentication yes
$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.
$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.
$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.
[Unit]Description=myapp APIAfter=network.target postgresql.service[Service]Type=simpleUser=deployWorkingDirectory=/home/deploy/myappExecStart=/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=alwaysRestartSec=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=journalStandardError=journal# Cheap hardening: no new privileges, a private /tmp, and a read-only# system except for the one directory the app writes to.NoNewPrivileges=truePrivateTmp=trueProtectSystem=strictReadWritePaths=/home/deploy/myapp[Install]WantedBy=multi-user.target
$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:
$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.
$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
yourdomain.com {# The frontend: everything that is not /apireverse_proxy localhost:3000# The APIhandle /api/* {reverse_proxy localhost:8080}encode gzip zstdheader {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}
$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.
# 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:
[Unit]Description=myapp webAfter=network.target[Service]Type=simpleUser=deployWorkingDirectory=/home/deploy/myapp/webEnvironment=PORT=3000Environment=NODE_ENV=productionExecStart=/usr/bin/node server.jsRestart=alwaysRestartSec=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.
#!/usr/bin/env bashset -euo pipefail # stop on the first failure rather than carrying onHOST=deploy@203.0.113.42APP=/home/deploy/myappecho "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 pipefailsudo mv /tmp/api-new /usr/local/bin/myapp-apisudo chmod +x /usr/local/bin/myapp-apisudo 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); doif curl -fsS localhost:8080/health > /dev/null; thenecho "healthy"; exit 0fisleep 1doneecho "did not become healthy; check journalctl -u myapp-api" >&2exit 1REMOTE
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.
$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:
$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 bashset -euo pipefailpg_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.
$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:
$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:
$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.
$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.
