Deploy guides

How to deploy an Astro site on Stackap

To deploy a static Astro site on Stackap you remove any server adapter, push the repository, and the server builds the site and serves it from nginx with real 404 pages.

Before you start

This guide is for content sites built with Astro in its default static mode: blogs, documentation, marketing sites. It is honest about one thing up front: no Astro site has been shipped on Stackap by its builders yet, so this guide rests on the generic static-site path, which has real build tests.

The deciding question is whether your site needs a server at request time. If it does not, this guide applies.

Check these in your Astro project

• astro is a dependency and the build script produces the finished site.
• No @astrojs/node, @astrojs/vercel or @astrojs/netlify adapter is installed. Any of them moves the project off the static path.
• The output mode is static, which is the default.
• A custom 404 page exists if you want one.
• Images are processed at build time, not requested through a runtime image service.

What to watch while it builds

In the build log, look for the line that names the detected type. It should say a static site (Astro). If it names a Node app or refuses the build, an adapter is still in your dependencies.

After it goes live, request a path that does not exist. A static site returns a real 404 status, which matters for search engines.

When it does not go live

Build refused with a reason

The project is not recognized. Check for a server adapter and for a missing build script.

Detected as a Node app and fails to start

An adapter is present and there is a start script. Remove the adapter for the static path.

Links break under a sub-path

The site was built with a base that does not match the domain.

Images missing

They were referenced from a runtime service. Move them into the build or into object storage.

Steps

1. Get access, a token and an SSH key. Request an invitation at the contact page. You receive the server's API address and a token. Pushing uses SSH, so the public key you push with must also be registered with your organization, which an owner token can do through POST /v1/ssh-keys, or the operator can do for you.
2. Log in and create the project. Log in once, then create a project for the app.

   $ stackap login --url https://api.<your-domain> --token-stdin
   $ stackap create my-astro-site --name "My Astro Site"

3. Prepare the repository. Remove the adapter if it is only there for local convenience, run the build once locally to confirm it finishes, and add the project's Stackap remote.
4. Set environment variables. A static site has no runtime, so variables matter only at build time and end up in the output. Set what the build needs and nothing secret.

   $ stackap env set my-astro-site PUBLIC_SITE_URL --stdin

5. Push. Deploy. The image builds your site and copies it into nginx.

   $ stackap deploy my-astro-site
   $ stackap logs my-astro-site --source build

6. Point your domain at it. Create the DNS record, then attach the hostname.

   $ stackap domains add my-astro-site www.example.com

Early-access scope

• Astro-specific features have not been exercised on Stackap by us, so treat them as unverified.
• No server-side rendering or on-demand routes through this path.
• No CDN, so far-away visitors see more latency.

Questions

Last updated 2026-10-03.