Deploy Astro to Quant

Quick start with the wizard

The Quant deployment wizard auto-detects Astro projects and generates the correct build configuration. Start from an Astro template or import your existing repo.

Astro is a modern web framework for building fast, content-focused websites. This guide covers deploying Astro sites to Quant, including both static and server-rendered options.

Static Astro sites

For most Astro sites, static output is the best choice — you get the fastest possible performance with global CDN delivery.

Prerequisites

• An Astro project (create one with npm create astro@latest)
• A Quant account
• Node.js 20 or later

Step 1: Configure Astro for static output

Ensure your astro.config.mjs uses static output (this is the default):

import { defineConfig } from 'astro/config';

export default defineConfig({
  output: 'static',
  // Quant handles trailing slashes, but you can configure:
  trailingSlash: 'ignore',
});

Step 2: Build your site

npm run build

This creates a dist/ folder with your static site.

Step 3: Deploy with CLI

Install the Quant CLI and deploy:

npm install -g @quantcdn/quant-cli

# Initialise (first time only)
quant init
# Enter your credentials when prompted
# Set directory to: dist

# Deploy
quant deploy

Step 4: Set up GitHub Actions

Create .github/workflows/deploy.yml:

name: Deploy Astro to Quant

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '22'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Restore revision log
        uses: actions/cache@v5
        with:
          path: .quant-revision
          key: quant-revision-${{ github.ref }}-${{ github.run_id }}
          restore-keys: |
            quant-revision-${{ github.ref }}-

      - name: Build Astro
        run: npm run build

      - name: Deploy to Quant
        uses: quantcdn/deploy-action@v6
        with:
          customer: ${{ secrets.QUANT_CUSTOMER }}
          project: ${{ secrets.QUANT_PROJECT }}
          token: ${{ secrets.QUANT_TOKEN }}
          dir: dist
          revision-log: .quant-revision
          skip-purge: true

      - name: Purge cache
        uses: quantcdn/purge-action@v6
        with:
          customer: ${{ secrets.QUANT_CUSTOMER }}
          project: ${{ secrets.QUANT_PROJECT }}
          token: ${{ secrets.QUANT_TOKEN }}
          url_pattern: "/*"

Server-rendered Astro with Quant Cloud

For Astro sites that need server-side rendering (SSR), API routes, or dynamic content, deploy to Quant Cloud.

Step 1: Configure Astro for SSR

Update your astro.config.mjs:

import { defineConfig } from 'astro/config';
import node from '@astrojs/node';

export default defineConfig({
  output: 'server', // or 'hybrid' for mixed static/SSR
  adapter: node({
    mode: 'standalone',
  }),
});

Install the Node adapter:

npm install @astrojs/node

Step 2: Create a Dockerfile

Create a Dockerfile in your project root:

FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:20-alpine AS runner
WORKDIR /app
ENV NODE_ENV=production
ENV HOST=0.0.0.0
ENV PORT=4321

COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/package.json ./

EXPOSE 4321
CMD ["node", "./dist/server/entry.mjs"]

Step 3: Create a Quant Cloud application

1. Go to the Quant Dashboard
2. Navigate to Cloud Applications → New Application
3. Enter your application name
4. Configure your environment

Step 4: Deploy with GitHub Actions

Create .github/workflows/deploy-cloud.yml:

name: Deploy Astro SSR to Quant Cloud

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Initialise Quant Cloud
        uses: quantcdn/quant-cloud-init-action@v1
        id: init
        with:
          quant_organization: ${{ secrets.QUANT_ORGANIZATION }}
          quant_api_key: ${{ secrets.QUANT_API_KEY }}

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Build and push image
        uses: docker/build-push-action@v5
        with:
          context: .
          platforms: linux/arm64
          push: true
          tags: ${{ steps.init.outputs.stripped_endpoint }}/${{ secrets.QUANT_ORGANIZATION }}/my-astro-app:web${{ steps.init.outputs.image_suffix }}

      - name: Deploy environment
        uses: quantcdn/quant-cloud-environment-action@v1
        with:
          quant_organization: ${{ secrets.QUANT_ORGANIZATION }}
          quant_api_key: ${{ secrets.QUANT_API_KEY }}
          application: my-astro-app
          environment: production
          operation: update

Hybrid rendering

Astro’s hybrid mode lets you choose static or server rendering per-page:

astro.config.mjs

export default defineConfig({
  output: 'hybrid', // Default to static, opt-in to SSR
  adapter: node({ mode: 'standalone' }),
});

Mark pages that need SSR:

src/pages/api/search.astro

---
export const prerender = false; // This page is server-rendered
---

For hybrid sites:

• Deploy static pages to Quant’s static edge for best performance
• Deploy the SSR application to Quant Cloud
• Use Page Rules to route dynamic paths to your Cloud app

Environment variables

Static builds

Set environment variables in your CI workflow:

- name: Build Astro
  run: npm run build
  env:
    PUBLIC_API_URL: https://api.example.com
    SITE_URL: https://www.example.com

Quant Cloud

Configure environment variables in the dashboard under your environment settings, or use the Environment Variables Action.

Astro integrations

Common integrations that work well with Quant:

Integration	Notes
@astrojs/sitemap	Generated sitemap is deployed automatically
@astrojs/image	Optimised images are deployed as static assets
@astrojs/mdx	Works perfectly with static output
@astrojs/tailwind	CSS is bundled and deployed

Performance tips

1. Use static output when possible — Static pages are served from edge cache in under 50ms
2. Enable image optimisation — In the Quant dashboard, enable image optimisation for automatic WebP/AVIF conversion
3. Leverage revision tracking — Use --revision-log to speed up deployments
4. Pre-render where possible — Even with SSR adapter, pre-render pages that don’t need dynamic data

Troubleshooting

404 errors on nested routes

Ensure trailing slash handling matches between Astro and your expectations:

astro.config.mjs

export default defineConfig({
  trailingSlash: 'always', // or 'never' or 'ignore'
});

Assets not loading

Check that asset paths are relative or use the correct base URL:

astro.config.mjs

export default defineConfig({
  site: 'https://www.example.com',
  base: '/', // or '/subpath' if deploying to a subdirectory
});

SSR routes returning 502

For Quant Cloud deployments:

• Check your application logs in the dashboard
• Verify the PORT environment variable matches your Dockerfile
• Ensure the health check endpoint responds correctly