The short answer

To deploy an Astro site, start with the rendering mode. When the HTML can be generated at build time, host the dist files. Unbroker’s Astro preset serves that build. When a page needs the visitor’s data on each request, add a server adapter and deploy that output as a Node.js service or a Dockerfile.

Leave the static preset pointed at generated files. Set site to the public origin you will publish, so canonical URLs and the sitemap use it. The product page is Deploy Astro. The steps are Deploy an Astro website.

Start with the rendering mode

The hosting choice is which pages exist before anyone asks for them. Astro’s default output is 'static': pages are prerendered at build time, and the result is a static site when no page opts out. output: 'server' server-renders pages by default. On-demand rendering, also called server-side rendering, needs an adapter. The reference is Astro’s configuration and on-demand rendering.

Static outputServer adapter
What the build writesHTML, CSS, and JavaScript in dist, unless you change outDirThe server files that adapter needs. This is a different output from the static preset.
What runs in productionA file server for those files. Unbroker’s Astro preset does this.The adapter’s server process: a Node.js service or a Dockerfile on Unbroker.
When it fitsMarketing pages, docs, and blogs whose HTML can be generated at build time.A page that needs a logged-in user’s data, or other data from the request, on each visit.

You can keep the default static mode and opt one route out with export const prerender = false after an adapter is installed. The rest of the site stays static. output: 'server' switches the default. Astro’s guide says to start with 'static' until most pages need to be rendered on demand, and that 'server' adds no extra features. It only changes which pages render on demand by default.

Hosting static Astro output

Confirm the build with the package manager and lockfile the repository already uses. The Unbroker guide’s example is npm ci, then npm run build. A standard Astro build script runs astro build. By default that writes dist/. outDir changes the directory. Astro’s deploy guide lists the build command as astro build or npm run build, and the publish directory as dist. See Deploy your Astro site.

In Cloud, create a repository service and choose Astro. Set the build command to the project’s build script and the output directory to dist, unless you changed Astro’s output directory.

Open the service URL. Request a nested page directly, refresh it, and follow links to images and stylesheets. If assets are missing, check the output directory and any configured base path. base is the path Astro uses as the root for pages and assets. If only the homepage exists, inspect the generated routes. Adding a server command to a static service does not create the missing pages.

astro preview starts a local server for the built static directory. Astro’s CLI says it is for checking the build before you deploy, and that it is not designed to be run in production. Unbroker’s guide says the same thing for the static preset: the local preview checks the output, and the preset is the production server for those files. The command reference is astro preview.

When you need a server adapter

A page that requires a logged-in user’s data at request time cannot be supplied by static HTML alone. Add an adapter for the runtime that will render those routes. Astro maintains official adapters for Node.js, Netlify, Vercel, and Cloudflare. On Unbroker, deploy that output as a Node.js service or with a Dockerfile, and follow the adapter’s build and start instructions. The static Astro preset serves a built static site, so server output stays on the Node.js or Dockerfile path.

The plans table includes managed Node.js on Free and lists Dockerfile builds as available on Pro. The Astro guide names the static preset as the path that runs on Free. Plan rows are in Plans.

Static Astro plus a separate API

If only a few interactions need a backend, keeping Astro static and adding a separate API can be simpler. Public frontend configuration is visible to visitors. Astro makes variables prefixed with PUBLIC_ available to client code through import.meta.env. Unbroker selects public build prefixes, including PUBLIC_, VITE_, and NEXT_PUBLIC_, before the build. A value that lands in the bundle the visitor downloads is public, including one you typed in Variables.

Put database credentials and other secrets on the API service. Private variables stay runtime-only, except the documented package-registry credentials. How scopes work is Environment variables and secrets.

Deploy the API first and confirm an endpoint on its public URL. Point the frontend’s public variable at that origin, then build the frontend. A change to a value embedded in the bundle needs a new build. Configure the API’s CORS policy for the frontend’s exact origin. A private project hostname is not reachable from a visitor’s browser. Browser calls need a public route. The walkthrough is Deploy a frontend and API together. CORS, cookies, and a preview that must not call the production API are deploy a frontend and an API separately. What Free can run for that API is Free backend hosting.

Use the real production URL

Set Astro’s site to the final deployed URL. Astro uses that full URL to generate the sitemap and canonical URLs in the build. The option is site. If the site is served under a path, base is the matching setting for pages and assets.

A custom domain is a later step, and it requires Pro. Once it is ready, check that canonical URLs and social images use that origin. Astro documents site for the sitemap and canonical URLs. The Unbroker guide also asks you to verify social images against the production origin, rather than a preview hostname. DNS and the certificate are Custom domain and HTTPS.

Keep the Unbroker-provided hostname. It is how you tell a deployment problem from a DNS problem.

How this works on Unbroker

The Astro preset serves a built static site. It is available on Free and on Pro. On Free it runs with Serverless: an idle service scales to zero and wakes on the next request. The first request after a sleep can take longer while the application starts. Pro apps do not sleep because of inactivity. They sleep only when Serverless is turned on. Custom domains and managed TLS are on Pro.

Create a repository service, select Astro, and set the build command and the output directory. Pro is $25 a month with $25 of usage credit. The credit resets each cycle and does not roll over. If eligible usage stays under the credit, the monthly charge is still the plan price. Current figures are on pricing and in Plans.

The product page is Deploy Astro. Which push produced the revision is Deploy on git push.

Checklist

  1. Decide whether each page can be generated at build time.
  2. For that case, keep the default static output and build with the project’s build script.
  3. Confirm dist, or your outDir, contains the pages and assets you expect.
  4. On Unbroker, choose the Astro preset and set the build command and the output directory.
  5. Open a nested page, refresh it, and follow an image and a stylesheet.
  6. Use astro preview to check the build locally. Leave it out of the production start command.
  7. If a page needs the visitor’s data on each request, add a server adapter and deploy that output as Node.js or a Dockerfile.
  8. Put secrets on the API. Keep PUBLIC_ values limited to configuration the visitor can see, and set CORS to the frontend origin.
  9. Set site to the real public origin. After a custom domain, check canonical URLs, the sitemap, and social images. Keep the Unbroker hostname. Custom domains need Pro.

FAQ

Do I need a server to host an Astro site?

Not when the HTML can be generated at build time. Astro's default output is static, and Unbroker's Astro preset serves that build on Free and on Pro. A page that must render on each request, for example with a logged-in user's data, needs a server adapter. Deploy that output as a Node.js service or a Dockerfile. Leave the static preset for generated files.

What is the difference between Astro static output and server rendering for hosting?

Static output prerenders pages at build time, and you host the files. Server rendering, which Astro also calls on-demand rendering, runs an adapter when the route is requested. output: 'static' is the default. output: 'server' makes on-demand the default. After you add an adapter, one route can opt out of prerendering with prerender = false, and the rest of the site stays static. The reference is Astro's on-demand rendering guide.

Which output directory does Astro build to?

dist, unless you change outDir. Astro's deploy guide lists dist as the publish directory and the build command as astro build or npm run build. On Unbroker, set the Astro preset's output directory to dist unless you changed it, and set the build command to the project's build script.

Can I use astro preview in production?

No. astro preview starts a local server for the built static directory so you can check that build. Astro's CLI says the command is not designed to be run in production. Unbroker's guide says the same for the static preset: the local preview checks the build, and the preset is what serves those files.

Can I host an Astro site on Unbroker's Free plan?

Yes, with the static Astro preset. On Free it runs with Serverless: an idle service scales to zero and wakes on the next request. Custom domains require Pro. Server rendering deploys as a Node.js service or a Dockerfile. Managed Node.js is on Free. Dockerfile builds are Pro. The Astro guide names the static preset as the Free path.

Do custom domains work on Free?

No. The plans table lists custom domains and managed TLS as not available on Free and available on Pro. Pro is $25 a month with $25 of usage credit. The credit resets each cycle and does not roll over. If eligible usage stays under the credit, the monthly charge is still the plan price. See pricing and Plans.

How do I deploy an Astro site that uses a server adapter on Unbroker?

Add the adapter, then deploy its output as a Node.js service or with a Dockerfile. Follow that adapter's build and start instructions. The static Astro preset serves generated files, so leave server output off that preset. Dockerfile builds require Pro. Managed Node.js is included on Free. Astro's official adapters include one for Node.js.

Where should API keys go in an Astro site?

On the backend service, not in client code. Astro makes PUBLIC_ variables available to the browser, and Unbroker selects that prefix, along with VITE_ and NEXT_PUBLIC_, as a public build variable. A value in the bundle the visitor downloads is public. Private variables stay runtime-only, except documented package-registry credentials. The split is the frontend and API guide, and the scopes are Environment variables and secrets.

Why are my canonical URLs pointing at a preview hostname?

Canonical URLs and the sitemap are generated from Astro's site value. Set site to the final public origin and rebuild. If they still show a preview hostname, that is the origin configured for that build. After a custom domain is ready, check canonical URLs, the sitemap, and social images against the production origin. Keep the Unbroker hostname so a DNS problem stays separate from the deploy. Custom domains require Pro.