Deploy an Astro app

New to seenode? Start free: 7-day trial, no credit card. Apps run on credit-based pricing from $3/mo.

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 (sign up free)
• 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

Set the container port in the Port input during service setup, then bind your server to the same port on 0.0.0.0. The Port field defaults to 80; set it to the port your server binds to, and you can change it later in the project’s Settings tab. Configure your Astro project accordingly:

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

4
export default defineConfig({
5
  output: 'server', // Enable SSR mode
6
  adapter: node({
7
    mode: 'standalone'
8
  }),
9
  server: {
10
    // Bind to 0.0.0.0 and use the same port you set in the dashboard.
11
    // Example: use 80 in production, 4321 for local development.
12
    port: process.env.NODE_ENV === 'production' ? 80 : 4321,
13
    host: true // Bind to 0.0.0.0 for container networking
14
  }
15
});

::::note[Port input is the source of truth] In seenode, the Port input in the dashboard tells the load balancer which container port to proxy to. Make sure your application binds to the same port. You can change this anytime from the project’s Settings tab. ::::

Update Package Scripts

Ensure your package.json includes the following scripts:

1
{
2
  "scripts": {
3
    "dev": "astro dev",
4
    "build": "astro build",
5
    "preview": "astro preview",
6
    "start": "NODE_ENV=production node ./dist/server/entry.mjs"
7
  }
8
}

::::note[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

::::tip[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

• The Port field defaults to 80. Ensure your application listens on host 0.0.0.0 and the port you set in the Configure Build & Start screen.
• Adjust in framework code if needed (for example, change the port passed to your adapter server).
• 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)

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:

::::note[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

Related

• Set up a custom domain
• Connect a database
• Manage your service
• Pricing