Astro Deployment to Production

We have completed the development cycle. We have an optimized application, with a solid architecture… that only works on your machine.

Now comes the moment of truth. We need to build the real website and deploy it to a server so everyone can see it.

In this article, we will address Astro deployment, prioritizing the use of a Virtual Private Server (VPS), both for static sites and server-rendered applications (SSR). We will also briefly review PaaS options for rapid prototyping.

Preparing the Artifact (Build)

Regardless of the deployment destination, the first step is to generate the production code. Astro compiles our code, optimizes images, and minifies assets.

This command will generate a dist/ folder in the project root. The content of this folder will vary depending on the mode configured in astro.config.mjs:

Deployment on VPS

This is the recommended option for having full control and no third-party dependencies. We will assume a standard Linux environment (Ubuntu/Debian).

Static Site (SSG)

If your project is purely static (blog, documentation, landing page), deployment is very simple. We only need an efficient web server like Nginx or Apache to serve the dist folder.

server {
    listen 80;
    server_name midominio.com;
    
    root /var/www/mi-proyecto;
    index index.html;

    location / {
        try_files $uri $uri/ /404.html;
    }

    # Aggressive cache for immutable assets (Astro generates hashes in filenames)
    location /_astro/ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
}

SSR Application (Node.js)

If we use output: 'server' or 'hybrid', we need a runtime environment. For a standard VPS, we will use Node.js.

npx astro add node

import node from '@astrojs/node';

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

# Global installation of PM2
npm install -g pm2

# Start the application
pm2 start dist/server/entry.mjs --name "mi-astro-app"

server {
    listen 80;
    server_name midominio.com;

    location / {
        proxy_pass http://localhost:4321; # Port where Astro runs
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}

name: Deploy to VPS
on: [push]
jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with: { node-version: 18 }
      - run: npm ci && npm run build
      - name: Deploy to Server
        uses: easingthemes/ssh-deploy@main
        env:
            SSH_PRIVATE_KEY: ${{ secrets.SSH_KEY }}
            REMOTE_HOST: ${{ secrets.HOST }}
            REMOTE_USER: ${{ secrets.USER }}
            SOURCE: "dist/"
            TARGET: "/var/www/mi-proyecto"

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

FROM node:lts-alpine AS runtime
WORKDIR /app
COPY --from=build /app/dist ./dist
COPY --from=build /app/node_modules ./node_modules
COPY --from=build /app/package.json ./

ENV HOST=0.0.0.0
ENV PORT=4321
EXPOSE 4321
CMD ["node", "./dist/server/entry.mjs"]

PaaS Alternatives (Vercel / Netlify)

If the project does not require dedicated infrastructure or we are in a rapid prototyping phase, Platform as a Service (PaaS) offerings are valid options.

These platforms abstract server management and offer integrated CI/CD (they connect to your Git repository and deploy on push).