Deploy Astro App on Seenode | Astro Hosting & Deployment Guide

Astro is a modern, content-focused web framework for building fast websites using the Islands Architecture. This guide shows how to deploy your existing Astro project as a web service on seenode.

Prerequisites

Before you begin, ensure you have:

• Node.js 18+ installed locally
• Git configured on your machine
• A seenode account at cloud.seenode.com
• Existing Astro project ready to deploy

Configure for seenode Deployment

Enable Server-Side Rendering (SSR)

To deploy as a web service, Astro needs to be configured for server-side rendering. Install the Node.js adapter:

npx astro add node

This will automatically update your astro.config.mjs and install the required dependencies.

Port Configuration

seenode requires applications to be reachable on port 80 at the load balancer. Your server should listen on PORT from the environment, defaulting to 80 in production. Configure your Astro project accordingly:

astro.config.mjs

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

export default defineConfig({
  output: 'server', // Enable SSR mode
  adapter: node({
    mode: 'standalone'
  }),
  server: {
    // Use port from env in production (default 80), 4321 for development
    port: process.env.NODE_ENV === 'production' ? (Number(process.env.PORT) || 80) : 4321,
    host: true // Bind to 0.0.0.0 for container networking
  }
});

Update Package Scripts

Ensure your package.json includes the following scripts:

package.json

{
  "scripts": {
    "dev": "astro dev",
    "build": "astro build",
    "preview": "astro preview",
    "start": "NODE_ENV=production node ./dist/server/entry.mjs"
  }
}

Understanding the Configuration

• output: 'server': Enables server-side rendering mode
• adapter: node(): Uses the Node.js adapter for server deployment
• mode: 'standalone': Creates a standalone server executable
• start script: Runs the built server directly

Deploy on seenode

1. Push to Git

   Commit your project and push it to GitHub or GitLab.

2. Create a Web Service

   From the seenode Dashboard, create a new Web Service and connect your repository.

3. Configure Build & Start

   seenode will detect a Node.js project. Configure:

   • Build Command:

     npm ci && npm run build

   • Start Command:

     npm start

   

4. Choose Pricing Tier

   Select your preferred instance size and create the service.

5. Deploy

   Click Create Web Service and watch logs until your web service is live.

6. Success

   Once complete, your Astro application will be accessible via your service’s URL.

   Troubleshooting

   If your deployment fails, the first place to check is the Logs tab in your seenode service dashboard. Build and runtime logs often contain valuable information for diagnosing issues.

   Port configuration mismatch

   • Templates default to port 80. Ensure your application listens on the port you set in the Configure Build & Start screen.
   • Adjust in framework config if needed (e.g., in astro.config.mjs, update server.port where it reads from process.env.PORT with a default of 80).
   • Seeing a 502 Bad Gateway? This often means your app is not listening on the configured port.

Starting from Scratch?

If you don’t have an Astro project yet:

Option 1: Use our Template (Recommended)

Astro Web Service Template

Deploy a minimal Astro web service with SSR, API endpoints, and seenode optimization.

Option 2: Create from Astro Docs + seenode Setup

Follow the official Astro documentation to create a new project, then return here for seenode-specific deployment steps.

seenode-Specific Setup Steps:

1. Run npm create astro@latest
2. Select the minimal template
3. Install Node.js adapter: npx astro add node
4. Configure for seenode (see “Configure for seenode Deployment” above)

Troubleshooting

If your deployment fails, check the Logs tab. Here are solutions to common issues:

Common Issues by Symptom

502 Bad Gateway / Service Unavailable

• Ensure your start script runs the built server: node ./dist/server/entry.mjs
• Verify NODE_ENV=production is set in your start command
• Check that the Node.js adapter is properly configured in astro.config.mjs
• Ensure host: true is set in server configuration to bind to 0.0.0.0:80

Build Failures

• Ensure npm run build completes successfully locally before deploying
• Check for missing dependencies in package.json (especially @astrojs/node)
• Verify SSR mode is enabled with output: 'server' in astro.config.mjs
• Review build logs for specific error messages

Port Binding Issues

• Verify astro.config.mjs uses port 80 when NODE_ENV=production
• Ensure no other configuration overrides the port setting
• Check that the Node.js adapter is configured with mode: 'standalone'

SSR Configuration Errors

• Ensure @astrojs/node adapter is installed and imported
• Verify output: 'server' is set in astro.config.mjs
• Check that API routes are properly configured in src/pages/api/

Missing Server Files

• Ensure dist/server/entry.mjs exists after build
• Check that all server-side dependencies are in dependencies (not devDependencies)
• Verify the start command points to the correct server entry file

Next Steps

Connect to a Database

Add PostgreSQL or MySQL for dynamic web services with server-side features