Deploy Astro with Dokploy: Static Build Type for Static Sites, Node Adapter for SSR, and the Host Setting Everyone Misses

Astro is two deployment stories in one framework. A content site builds to static files in dist/ and needs nothing but a web server; add the Node adapter and the same project becomes a server-rendered application listening on a port. Dokploy covers both: the Static build type serves the folder with Nginx, and an Application with Nixpacks or a Dockerfile runs the SSR server. This guide does each on a MassiveGRID server from the Dokploy hosting page, including the one setting that trips most Astro deployments.

Route A: a static Astro site with the Static build type

1. Create Service, Application, connect the repository, and set the build type to Static (or Nixpacks with the Publish Directory set to dist; the Dokploy docs use Astro's dist as their example).
2. Build command npm run build. Dokploy copies dist/ into an Nginx image.
3. Add the domain with HTTPS on port 80, which is what the Static build type serves on. Point DNS at the server first.
4. Turn on Auto Deploy; every push rebuilds and swaps the site. Preview Deployments give each pull request its own URL.

A static Astro site uses a few megabytes of RAM; dozens fit on the Starter preset next to other services. For redirects and headers (the _redirects you may have on Netlify), use Traefik middlewares in the application's Advanced tab, as our Netlify alternative page describes.

Route B: server-rendered Astro with the Node adapter

Install the adapter and set standalone mode:

npx astro add node
// astro.config.mjs
import { defineConfig } from 'astro/config';
import node from '@astrojs/node';
export default defineConfig({
  output: 'server',
  adapter: node({ mode: 'standalone' }),
  server: { host: true }      // listen on all interfaces for preview and dev
});

npm run build produces dist/server/entry.mjs, started with node ./dist/server/entry.mjs. The standalone server reads HOST and PORT; set HOST=0.0.0.0 and PORT=4321 in Dokploy's Environment tab, and add the domain on port 4321. In Dokploy use Nixpacks with NIXPACKS_START_CMD=node ./dist/server/entry.mjs, or the Dockerfile below.

The host setting everyone misses

Astro's dev and preview servers bind to localhost by default, and the Dokploy troubleshooting docs name Astro specifically as a Bad Gateway cause: Traefik cannot reach a process on 127.0.0.1. server: { host: true } in astro.config.mjs fixes preview; HOST=0.0.0.0 fixes the standalone production server. If the site answers at ip:4321 but not on the domain, this is why.

A Dockerfile for Astro SSR

FROM node:22-alpine AS build
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:22-alpine
WORKDIR /app
ENV HOST=0.0.0.0 PORT=4321 NODE_ENV=production
COPY --from=build /app/node_modules ./node_modules
COPY --from=build /app/dist ./dist
COPY package.json ./
EXPOSE 4321
CMD ["node", "./dist/server/entry.mjs"]

Select Dockerfile as the build type and keep the domain on 4321. Environment variables used at build time (PUBLIC_ prefixed in Astro) must be set before the first build; server-only secrets are read at runtime.

Images, content collections and databases

Astro's image service runs with sharp inside the container, no per-image meter. Content collections build in; for a CMS, deploy Strapi or PocketBase in the same Dokploy project and point Astro at the internal URL at build time, or at the public URL for client-side fetches. Astro DB and libSQL work against a Dokploy database service as well. Put Cloudflare in front if your readers are spread across continents; otherwise one server in the right city is enough.

Common problems and their fixes

• Client-side routes return 404 on the Static build type. Astro writes one HTML file per page, so a URL that no page generates is a real 404; add a src/pages/404.astro so visitors get your page rather than Nginx's, and check trailingSlash in astro.config.mjs matches how you link.
• A changed PUBLIC_ variable has no effect. Public variables are inlined at build time. Change them in Dokploy's Environment tab and redeploy; a restart is not enough.
• Images are served unoptimised in SSR. Astro's default image service needs sharp in the runtime image; the Dockerfile above keeps node_modules, so sharp is present. With Nixpacks, make sure sharp is a dependency, not a devDependency.
• Redirects from netlify.toml or vercel.json are ignored. They are platform files. Use Astro's redirects config for page redirects and Traefik middlewares in the application's Advanced tab for host-level rules such as www to apex.
• The certificate did not issue. DNS must point at the server before the domain is added; otherwise recreate the domain or restart Traefik, as our SSL troubleshooting post explains.

Sizing and cost

A static site is almost free to run; an SSR Astro server idles at 80 to 150 MB and a build spikes to about a gigabyte.

An Astro site with its CMS fits the MassiveGRID Starter preset (2 vCPU, 4 GB RAM, 64 GB NVMe) at $9.58 a month on shared cores, or $19.80 on dedicated cores when build times and response latency must stay steady; the Growth preset (4 vCPU, 8 GB) at $19.16 or $39.60 adds room for previews, a worker and a second project. Dokploy is free, MassiveGRID installs it on request after you order from the Dokploy hosting page, and the server runs on a Proxmox HA cluster with Ceph storage and a 15-day money-back guarantee.

Frequently Asked Questions

Should I deploy Astro as static or SSR on Dokploy?

Static whenever the content allows it: the Static build type serves dist/ from Nginx on port 80, uses almost no resources and never 502s. Use SSR with the Node adapter only when pages depend on the request (authentication, personalisation, live data), and set HOST=0.0.0.0 with the domain on port 4321.

Why does my Astro site show Bad Gateway on Dokploy?

Because the server is bound to localhost or the domain port does not match. For SSR set HOST=0.0.0.0 and PORT=4321 and use 4321 in the domain; for preview set server.host to true in astro.config.mjs; for the Static build type the domain must be on port 80. The Dokploy troubleshooting docs list Astro by name for exactly this.

Does Dokploy support Astro preview deployments?

Yes. Preview Deployments build each pull request into its own environment on a generated domain, for both the Static build type and SSR applications, so content and layout changes can be reviewed before merging, the same workflow Netlify and Vercel offer.