Deploy an Astro site

Deploy an Astro site on Hangar, as a static build served with compression and clean URLs, or with server rendering through the Node adapter.

Updated

Markdown

Skip the setup

Deploy a working starter of this guide, on its own URL, in one click.

Deploy on Hangar

Astro deploys on Hangar in either of its modes. A static site is built once and served as files. With server rendering, Astro runs as a Node.js server in a container, so on-demand pages, API endpoints and sessions work.

Before you start#

  • An Astro project in a Git repository, with its lockfile.
  • A Hangar account.

1Choose the output#

A static site needs nothing: it is Astro's default output.

For server rendering, add the Node adapter in standalone mode:

Terminal
npx astro add node
JavaScript
// astro.config.mjs
import node from "@astrojs/node";

export default defineConfig({
  output: "server",
  adapter: node({ mode: "standalone" }),
});

2Create the service#

Create a project, add a service and pick your repository and branch. Leave the builder on Automatic. It installs dependencies with the package manager of your lockfile, runs astro build and then:

  • for a static site, serves the dist folder with the Caddy web server, with gzip and zstd compression and clean URLs, so /about serves about.html or about/index.html;
  • with the Node adapter, builds a Node.js server and makes it listen on every interface.

3Start the server#

Skip this step for a static site.

With server rendering, set the start command in Settings → Runtime:

Terminal
node ./dist/server/entry.mjs

The standalone server listens on PORT, which Hangar sets to the domain's container port.

4Deploy and add a domain#

Deploy the service. In Settings → Networking, add a domain with HTTPS on and leave the container port at 3000. Both outputs listen on PORT, which follows the container port, so any port works as long as you don't set PORT yourself.

A static site changes only when you deploy. With server rendering, variables your pages read at request time, such as API keys, come from the environment when the server runs; values used during astro build must be set before the deploy that builds them.

Adding a database#

With server rendering, add a PostgreSQL service in the same project and region, copy its internal connection URL and set it as DATABASE_URL on the site. Read it in server code with process.env.DATABASE_URL. See Databases.

Troubleshooting#

  • 502 on the domain: a PORT variable you set differs from the container port. Remove it, or make the two match.
  • The server does not start: the start command is missing, or the adapter is not in standalone mode.

Frequently asked questions

How does Hangar serve a static Astro site?
The automatic builder runs astro build and serves the dist folder with the Caddy web server, with gzip and zstd compression and clean URLs. Caddy listens on the PORT Hangar sets, so the domain needs no port setting.
Can I use Astro server rendering on Hangar?
Yes. Add the @astrojs/node adapter in standalone mode, and set the start command to node ./dist/server/entry.mjs. The server listens on the PORT Hangar sets.