Skip to main content

​
Deployment Guide

This guide covers how to deploy the Astro application to various environments.

​
Prerequisites

Before deploying, ensure:
  1. All tests pass (pnpm test)
  2. The build completes successfully (pnpm build)
  3. Required environment variables are set
  4. Convex backend is deployed

​
Environment Variables

The following environment variables should be set in your deployment environment: 
# Convex
PUBLIC_CONVEX_URL=https://your-convex-deployment.convex.cloud
CONVEX_DEPLOYMENT=your-deployment-name
CONVEX_ADMIN_KEY=your-admin-key

# Authentication
AUTH_SECRET=your-auth-secret
AUTH_TRUST_HOST=true

# Application
PUBLIC_SITE_URL=https://your-site-url.com

​
Deployment Options

Astro supports static generation, which is the recommended approach for deploying this application.

​
Build for Static Hosting

pnpm build
This will generate a static site in the dist/ directory, which can be deployed to any static hosting service.

​
Deploy to Vercel

vercel --prod

​
Deploy to Netlify

netlify deploy --prod

​
Deploy to GitHub Pages

pnpm deploy
This runs a script that pushes the dist/ directory to the gh-pages branch.

​
2. Server-Side Rendering (SSR)

For dynamic content that needs to be generated at request time, use SSR deployment.

​
Build for SSR

Update astro.config.mjs to use the appropriate adapter: 
import { defineConfig } from 'astro/config';
import node from '@astrojs/node';

export default defineConfig({
  output: 'server',
  adapter: node({
    mode: 'standalone',
  }),
});
Then build the application: 
pnpm build

​
Deploy to Vercel with SSR

Add a vercel.json file: 
{
  "version": 2,
  "builds": [
    {
      "src": "package.json",
      "use": "@vercel/node"
    }
  ],
  "routes": [
    {
      "src": "/(.*)",
      "dest": "/dist/server/entry.mjs"
    }
  ]
}
Then deploy: 
vercel --prod

​
Deploy to Netlify with SSR

Create a netlify.toml file: 
[build]
  command = "pnpm build"
  publish = "dist/"

[[redirects]]
  from = "/*"
  to = "/.netlify/functions/entry"
  status = 200

[functions]
  node_bundler = "esbuild"
Then deploy: 
netlify deploy --prod

​
3. Docker Deployment

For containerized environments, use Docker:

​
Build the Docker Image

docker build -t your-app-name .

​
Run the Docker Container

docker run -p 3000:3000 \
  -e PUBLIC_CONVEX_URL=https://your-convex-deployment.convex.cloud \
  -e CONVEX_DEPLOYMENT=your-deployment-name \
  -e CONVEX_ADMIN_KEY=your-admin-key \
  -e AUTH_SECRET=your-auth-secret \
  -e AUTH_TRUST_HOST=true \
  -e PUBLIC_SITE_URL=https://your-site-url.com \
  your-app-name

​
Deploying with Docker Compose

Create a docker-compose.yml file: 
version: '3'
services:
  app:
    build: .
    ports:
      - "3000:3000"
    environment:
      - PUBLIC_CONVEX_URL=https://your-convex-deployment.convex.cloud
      - CONVEX_DEPLOYMENT=your-deployment-name
      - CONVEX_ADMIN_KEY=your-admin-key
      - AUTH_SECRET=your-auth-secret
      - AUTH_TRUST_HOST=true
      - PUBLIC_SITE_URL=https://your-site-url.com
Then run: 
docker-compose up -d

​
Convex Backend Deployment

Before deploying the frontend, you need to deploy the Convex backend:
  1. Install the Convex CLI if you haven’t already: npm install -g convex
  2. Log in to Convex: npx convex login
  3. Initialize a new deployment: npx convex init
  4. Deploy the backend: npx convex deploy
Take note of the deployment URL and use it for your PUBLIC_CONVEX_URL environment variable.

​
Continuous Integration/Continuous Deployment (CI/CD)

​
GitHub Actions

Create a .github/workflows/deploy.yml file: 
name: Deploy

on:
  push:
    branches: [ main ]

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

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '22'

      - name: Install pnpm
        uses: pnpm/action-setup@v3
        with:
          version: 10

      - name: Install dependencies
        run: pnpm install --frozen-lockfile

      - name: Run tests
        run: pnpm test

      - name: Build
        run: pnpm build

      - name: Deploy to Vercel
        uses: amondnet/vercel-action@v20
        with:
          vercel-token: ${{ secrets.VERCEL_TOKEN }}
          vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}
          vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }}
          vercel-args: '--prod'

​
Post-Deployment Verification

After deploying, perform these checks:
  1. Verify all pages load correctly
  2. Test authentication flow
  3. Check that Convex integration is working
  4. Verify all interactive components function properly
  5. Test responsiveness on different devices
  6. Run Lighthouse audit for performance and accessibility

​
Rollback Procedure

If issues are encountered after deployment:
  1. For Vercel/Netlify: Use their dashboard to roll back to the previous deployment
  2. For Docker: Restart the container with the previous image version
  3. For Convex: Use npx convex deploy --cmd rollback to roll back to the previous deployment

​
Performance Monitoring

Set up monitoring for your deployed application:
  1. Add Sentry for error tracking
  2. Set up LogRocket for session replay
  3. Configure Vercel Analytics or Google Analytics

​
Troubleshooting

​
Common Issues

  1. Static assets not loading: Check paths in the build output
  2. API calls failing: Verify environment variables are set correctly
  3. Authentication issues: Check Auth settings and secret keys
  4. SSR rendering errors: Look for server logs in your hosting provider

​
Getting Help

If you encounter issues not covered here:
  1. Check the Astro documentation
  2. Post in the Astro Discord
  3. Search for similar issues in the Astro GitHub repository