Deploy an Astro App

This guide explains how to deploy a basic Astro (opens in a new tab) application to Koyeb using:

Git-driven deployment to automatically build and deploy a new version of your application each time a change is detected on your branch.
Pre-built containers you can deploy from any public or private registry.

To successfully follow this documentation, you will need to have a Koyeb account (opens in a new tab). You can optionally install the Koyeb CLI if you prefer to follow this guide without leaving the terminal.

You can deploy and preview the Astro application from this guide by clicking the Deploy to Koyeb button below.

(opens in a new tab)

You can consult the repository on GitHub (opens in a new tab) to find out more about the example application that this guide uses.

Create the Astro app

We will start by creating a basic Astro application. You will need a recent version of Node.js (opens in a new tab) and npm (or another package manager) installed on your local machine. Additionally, you may wish to install Docker (opens in a new tab) if you are planning on building and testing a container image for the application locally.

Generate the project files

To get started, generate the example project files by running the npm create command:

npm create astro@latest

The project creation procedure will ask you a series of questions to determine how to set up Astro for the project. Feel free to accept the recommended defaults. This guide assumes the following choices:

Where should we create your new project? example-astro
How would you like to start your new project? Include sample files
Do you plan to write TypeScript? Yes
How strict should TypeScript be? Strict
Install dependencies? Yes
Initialize a new git repository? Yes

Once the components are installed, enter the project directory and run the development server to test out the basic functionality:

cd example-astro
npm run dev

If you navigate to http://localhost:4321 in your browser, you should see the basic Astro test page.

Make the service port configurable

By default, Astro applications listen on port 4321. Koyeb automatically sets the PORT environment variable to the port it is configured to serve the application on. We can modify our Astro application to listen on the port defined by the PORT environment variable to ensure that the Koyeb deployment configuration and the Astro app agree on the service port.

Open the astro.config.mjs file in the project root directory in your text editor. Inside, modify the defineConfig declaration to parse the PORT environment variable. We will configure it to fall back on port 4321 if no port is defined. Additionally, we'll set host to true to ensure that the server always listens on all interfaces instead of binding explicitly to localhost:

astro.config.mjs

import { defineConfig } from 'astro/config'
 
// https://astro.build/config
export default defineConfig({
  server: { port: parseInt(process.env.PORT) || 4321, host: true },
})

You can test the new functionality by starting the development server again. First, confirm that the application starts on the original port using the default run mode:

npm run dev

The application should be served on port 4321 as it was previously.

Next, add a PORT environment variable to confirm that we can change the listening port dynamically:

PORT=8888 npm run dev

The application should now be listening on port 8888, as expected.

Add the Node.js adapter

By default, Astro's build process produces a static site in a dist directory. The site files can then be served using a conventional web server.

Astro can also use adapters to serve the site using server-side rendering (SSR) (opens in a new tab). We will add the Node.js adapter to our project so that we can deploy easily without integrating with a web server.

You can add the Node.js adapter to your project using the astro add command:

npm run astro add node

Accept the recommended modifications to install the adapter and modify your current project configuration as necessary.

You can test the Node.js adapter by building the application and executing the resulting artifacts using the node binary:

npm run build
node dist/server/entry.mjs

Modify the start script

Koyeb consults the start script in the package.json file to determine how to run the application after building.

We will configure the project to use Node.js to serve the build artifacts instead of using the Astro development server. Open the package.json file and make the following modification:

package.json

{
  "name": "example-astro",
  "type": "module",
  "version": "0.0.1",
  "scripts": {
    "dev": "astro dev",
    "start": "node dist/server/entry.mjs",
    "build": "astro check && astro build",
    "preview": "astro preview",
    "astro": "astro"
  },
  "dependencies": {
    "@astrojs/check": "^0.5.10",
    "@astrojs/node": "^8.2.5",
    "astro": "^4.6.0",
    "typescript": "^5.4.5"
  }
}

Create a Dockerfile for the project (Optional)

We can build and run our Astro project on Koyeb using the native Node.js buildpack, but we can also optionally build from a Dockerfile for more control. To make it possible to build a container image for our application, we just need to create the Dockerfile. We'll also define a .dockerignore file to tell the builder what files to skip when creating the image.

First, define a .dockerignore file in your main project directory. Inside, paste the following contents:

.dockerignore

.git
.gitignore
Dockerfile
.dockerignore
node_modules/
dist/
.astro/
.env

This file tells Docker to not include Git files, the Docker files themselves, and some project-specific files and directories if they is present. This helps ensure that the image we build is not bloated and that the build completes faster.

Next, create a new file called Dockerfile within the main project directory. Inside, paste the following contents:

Dockerfile

FROM node:lts-alpine
 
WORKDIR /app
COPY . .
 
RUN npm ci
RUN npm run build
 
ARG PORT
EXPOSE ${PORT:-4321}
 
CMD npm run start

This Dockerfile is based on the Alpine LTS (long term support) version of the node image (opens in a new tab). The Dockerfile copies all of the project files to the image's filesystem and then installs the dependencies with npm ci. It is configured to allow optionally passing PORT as a build argument and it runs the start script we defined earlier when the container starts.

If you have Docker installed locally, you can build and test the image on your computer and optionally upload it to a registry. You can deploy container images from any container registry to Koyeb.

We can also build the Dockerfile directly from the repository when we deploy, which is useful as a way of automatically deploying when changes occur. We will demonstrate this method as one of the options in this guide.

Push the project to GitHub

When we initialized the project, Astro automatically initialized a git repository and created a .gitignore file.

Once you're ready, add the project files to the staging area and commit them. If you don't have an existing GitHub repository to push the code to, create a new one (opens in a new tab) and then run the following commands to commit and push changes to your GitHub repository:

git add :/
git commit -m "Initial commit"
git remote add origin git@github.com:<YOUR_GITHUB_USERNAME>/<YOUR_REPOSITORY_NAME>.git
git branch -M main
git push -u origin main

Make sure to replace <YOUR_GITHUB_USERNAME>/<YOUR_REPOSITORY_NAME> with your GitHub username and repository name.

Deploy to Koyeb using git-driven deployment

Once the repository is pushed to GitHub, you can deploy the Astro application to Koyeb. Any changes in the deployed branch of your codebase will automatically trigger a redeploy on Koyeb, ensuring that your application is always up-to-date.

To deploy the Astro app on Koyeb using the control panel (opens in a new tab), follow the steps below:

Click Create Web Service on the Overview tab of the Koyeb control panel.
Select GitHub as the deployment option.
Choose the GitHub repository containing your application code. Alternatively, you can enter our public Astro example repository (opens in a new tab) into the Public GitHub repository at the bottom of the page: https://github.com/koyeb/example-astro.
Choose the Builder for your project. We can use either a Dockerfile or buildpack for this repository.
Choose a name for your App and Service, for example example-astro.
Click the Deploy button.

A Koyeb App and Service will be created. Your application will be built and deployed to Koyeb. Once the build has finished, you will be able to access your application running on Koyeb by clicking the URL ending with .koyeb.app.

Deploy to Koyeb from a container registry

If you chose to build a container image for the Astro application, you can optionally deploy the application from a container registry instead of from GitHub.

To deploy a pre-built Astro container image on Koyeb using the control panel (opens in a new tab), follow the steps below:

Click Create Web Service on the Overview tab of the Koyeb control panel.
Select Docker as the deployment option.
Choose the container image and tag from your registry and click Next to continue.
Choose a name for your App and Service, for example example-astro.
Click the Deploy button.

A Koyeb App and Service will be created. The container image will be pulled from the container registry and a container will be deployed from it. Once the initialization is complete, you will be able to access your application running on Koyeb by clicking the URL ending with .koyeb.app.

Hapi Rust