How to Deploy Astro on a VPS with CloudPanel (2026 Guide)

Deploying Astro on a VPS with CloudPanel gives you the one thing free platforms never do: full control. Your build, your cache headers, your rollback path, and no build-minute caps waiting to surprise you at the end of the month. Free hosting like Cloudflare Pages, Vercel, and Netlify works well until it doesn’t: bandwidth caps, build limits, or platform lock-in.

CloudPanel is a free hosting panel that runs on Nginx. It handles site management, SSL, and user isolation through a web UI. You deploy Astro as a Static HTML site and let CloudPanel serve the built files directly from Nginx. No Node.js process runs at runtime, which means a small, cheap VPS is enough. And since Astro 7 shipped in June 2026 with 15 to 61% faster builds (our Astro 7 build benchmark), rebuilds on that small box are quicker than they used to be.

VPS prices jumped across the board in 2026. If you’re rethinking a rented box, see what changed and when a mini PC wins.

Prerequisites

Before you start, here is what needs to already exist:

The stack this guide builds: Linux VPS + CloudPanel (Nginx) + NVM + Node 24 + Cloudflare in front. Everything else is optional.

You can also deploy Astro on a VPS with Coolify or EasyPanel if you prefer a different panel. For Docker-heavy stacks those are fine choices. For a pure static Astro site, CloudPanel is the simpler path.

If you want to monitor CPU, memory, and disk space on your server, check: How To Monitor Server and Docker Resources

Video walkthrough

Deploy Astro.js on VPS with CloudPanel

There are two approaches in CloudPanel: a Static HTML site (recommended for pure static output) or a Node.js site. The Static HTML approach is simpler and cheaper to run: CloudPanel serves the built files directly from Nginx with no Node.js process at runtime. Here’s the full sequence: site, DNS, SSL, Node for building, project, build, then automation.

Step 1: Add a static HTML site in CloudPanel

1. Log in to your CloudPanel admin panel.
2. Go to Sites > Add Site > Create a Static HTML Site. (CloudPanel’s current docs for all site types live at cloudpanel.io/docs/v2/frontend-area/add-site/.)
3. Enter your domain name and create the site user credentials.
4. After the site is created, edit it and change the Root Directory to point to the dist directory:

htdocs/www.yourdomain.com/dist

Astro outputs its production build into dist/ by default (outDir: './dist'). CloudPanel needs to serve from that directory, not the project root.

CloudPanel also creates the www↔non-www redirect and forces HTTP→HTTPS for you. You don’t need to hand-write those rules.

Step 2: Point DNS to your VPS

Add an A record in your DNS provider pointing your domain to the VPS IP address. If you use Cloudflare, add the A record there and enable the proxy for CDN benefits and DDoS protection.

dig +short www.yourdomain.com
# With Cloudflare proxy on, you'll see Cloudflare IPs (that's expected)
# With proxy off (DNS only), you should see your VPS IP

Step 3: Generate a Let’s Encrypt SSL certificate

In CloudPanel, go to your site’s SSL/TLS section and click New Let’s Encrypt Certificate. CloudPanel handles the certificate generation and Nginx configuration automatically.

Verify it before moving on:

curl -I https://www.yourdomain.com
# Expect: HTTP/2 200 (the CloudPanel placeholder page is fine at this stage)

curl -I http://www.yourdomain.com
# Expect: 301 redirect to https://www.yourdomain.com

If you get a certificate warning in curl, the cert didn’t issue. Check that the DNS record from Step 2 is already resolving before retrying.

Step 4: Install Node.js 24 LTS with NVM

Astro needs Node.js to build the site. CloudPanel creates isolated Linux users per site, so install Node.js under the site user, not as root. SSH into your VPS and switch to the site user:

ssh root@your-server-ip
sudo su - www.yourdomain.com

Install NVM (Node Version Manager). v0.40.8 is current as of September 2026:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.8/install.sh | bash
source ~/.bashrc

Install Node.js 24, the active LTS line:

nvm install 24
nvm alias default 24

Verify the installation:

node -v
# Should output v24.x.x

nvm ls
# Should show v24.x.x as default

Step 5: Clone and set up your Astro project

Remove the default CloudPanel placeholder files and get your project in place. The directory name must match what CloudPanel expects (www.yourdomain.com).

cd htdocs
rm -rf www.yourdomain.com
git clone [email protected]:your-username/your-astro-repo.git www.yourdomain.com
cd www.yourdomain.com
npm install

ssh-keygen -t ed25519 -C "deploy-www.yourdomain.com"
cat ~/.ssh/id_ed25519.pub
# Copy the output, then in GitHub: repo Settings > Deploy keys > Add deploy key
# Paste it and leave "Allow write access" unchecked

cd htdocs
rm -rf www.yourdomain.com
npm create astro@latest www.yourdomain.com
cd www.yourdomain.com
npm install

Step 6: Build the Astro static site

Once your site is configured and content is in place, build the production version:

npm run build

This generates the static files in dist/. Since CloudPanel’s root directory already points at dist/, the site goes live the moment the build finishes.

Verify:

curl -I https://www.yourdomain.com
# Expect: HTTP/2 200 and content-type: text/html

curl -I https://www.yourdomain.com/_astro/*.css
# Expect: 200. Astro emits hashed assets under /_astro/

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

Step 7: Automate rebuilds and deployments

Pulling and building by hand gets old on the third content push. The whole pipeline is small:

Write a minimal deploy script as the site user, at ~/deploy.sh:

#!/usr/bin/env bash
set -euo pipefail

cd ~/htdocs/www.yourdomain.com
git pull
npm ci
npm run build

chmod +x ~/deploy.sh

Use npm ci instead of npm install. It installs exactly what’s in package-lock.json, so a rebuild tomorrow behaves like the rebuild today. Now pick a trigger:

*/5 * * * * /home/www.yourdomain.com/deploy.sh >> /home/www.yourdomain.com/deploy.log 2>&1

cd ~/htdocs/www.yourdomain.com
git fetch -q
[ "$(git rev-parse HEAD)" = "$(git rev-parse @{u})" ] && exit 0

Whichever trigger you use: the build output lands in cron logs or the webhook’s journal. When a deploy “silently” doesn’t happen, that log is the first place to look. The script is also where the rollback safeguard hooks in (covered next).

Roll back a failed deploy

npm run build empties dist/ before writing new output. If the build fails midway (markup error, OOM kill, broken dependency), you can be left serving nothing. The fix is boring: keep the previous good build around until the new one is proven.

Extend the deploy script with the swap:

#!/usr/bin/env bash
set -euo pipefail

cd ~/htdocs/www.yourdomain.com
git pull
npm ci

# Keep the previous build until the new one is proven
if [ -d dist ]; then
  rm -rf dist.last-known-good
  mv dist dist.last-known-good
fi

if npm run build && [ -f dist/index.html ]; then
  rm -rf dist.last-known-good
else
  echo "Build failed or produced no index.html, restoring previous dist" >&2
  if [ -d dist.last-known-good ]; then
    rm -rf dist
    mv dist.last-known-good dist
  fi
  exit 1
fi

The [ -f dist/index.html ] check catches the worst case: a build that exits 0 but emits an empty or wrong output tree. If it fails, the backup is swapped back and Nginx keeps serving the previous version.

This is a “last known good static output” strategy, not versioned deploys. For a solo static site it’s enough: restore time is a mv, and the only state that matters (the git repo) is elsewhere.

Verify your deployment and set cache headers

Run this checklist after the first deploy and after every rebuild. It takes 30 seconds and catches most of what breaks:

Then caching. Astro emits hashed files under /_astro/, so those are safe to cache hard: Cache-Control: public, max-age=31536000, immutable. HTML should stay short-lived, otherwise visitors keep seeing the previous deploy after you rebuild.

CloudPanel’s static vhost template handles basic serving, but if you want explicit, predictable headers, add them in the site’s Vhost editor (CloudPanel vhost docs):

location /_astro/ {
  add_header Cache-Control "public, max-age=31536000, immutable";
}

Leave HTML to default handling, or set a short Cache-Control (60 seconds is plenty). On the Cloudflare side, set Browser Cache TTL to “Respect Existing Headers” so the origin wins. That way a rebuild shows up without you needing to purge.

After the site is live, watch it: monitor uptime with Beszel and Uptime Kuma and track server resources. A static site can still go down: cert expiry, disk full, Nginx misconfig on the next edit.

If you’d rather not put Cloudflare in front, Bunny.net works as a drop-in edge CDN on the same origin. Pull zone pointed at your VPS, same /_astro/ immutable caching story.

Troubleshooting common failures

Alternative: use CloudPanel’s Node.js site type

For a purely static site, use the Static HTML site type. You can always recreate the site as Node.js later if you go SSR. It’s a 10-minute change. If you’re still deciding on a panel overall, the best self-hosted server panels comparison covers the trade-offs.

Conclusions

Deploying Astro on a VPS with CloudPanel is the right move when you outgrow free hosting limits or want control over the box. The Static HTML site type is the simplest version of it: Nginx serves dist/, no Node process runs at runtime, a $5 to $10/month VPS is enough, and Astro 7’s faster builds make rebuilds on that small machine less painful. Add the deploy script, the dist.last-known-good swap, and the verify checklist, and you have a deploy path you can trust at 1 a.m.

One security recap: keep CloudPanel updated. The panel runs with real privileges on your server and the changelog shows the CVE history to prove it matters.

If you want a web panel that also works as a reverse proxy for Docker containers, check this course:

Where to go next:

• Add a contact form to your Astro site (free, no backend)
• Build a free Astro blog on Cloudflare if you want the zero-server path
• Deploy Astro.js on Cloudflare Pages (free, zero-config hosting)
• Astro deployment docs (covers every supported platform)