Deploy a Bun App

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

  1. Git-driven deployment to automatically build and deploy a new version of your application each time a change is detected on your branch.
  2. 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 Bun application from this guide by clicking the Deploy to Koyeb button below.

Deploy to Koyeb (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 Bun app

Get started by creating a minimalistic Bun application. You will need Bun (opens in a new tab) and Docker (opens in a new tab) installed on your machine.

In your terminal, run the following commands to create the directory that will hold the application code:

mkdir example-bun
cd example-bun

To generate a new Bun application, in the example-bun directory, run the following command:

$ bun init
bun init helps you get started with a minimal project and tries to guess sensible deults. Press ^C anytime to quit
 
package name (example-bun):
entry point (index.ts): server.ts
 
Done! A package.json file was saved in the current directory.
 + server.ts
 + .gitignore
 + tsconfig.json (for editor auto-complete)
 + README.md
 
To get started, run:
  bun run server.ts

This command initializes a Bun project and creates various files and folders:

  • .gitignore: To ignore files that should not be committed to the repository
  • server.ts: The main entry point of the application
  • tsconfig.json: To define the TypeScript configuration required to compile the project
  • README.md: A starter README file for your project
  • package.json: Basic Node.js configuration, metadata, and dependency file

Open the file called server.ts and copy the following code into it:

const port = process.env.PORT || 3000
 
console.log(`Launching Bun HTTP server on port: ${port}, url: http://0.0.0.0:${port} 🚀`)
 
Bun.serve({
  port: port,
  fetch(_request) {
    return new Response('Hello from Koyeb')
  },
})

The Bun application is now ready and can be run locally.

The next step is to create a Dockerfile at the root of the project to deploy the application on Koyeb.

Dockerize the Bun app

To deploy the Bun application on Koyeb, you need to create a Dockerfile in your project root directory. The Dockerfile will be used to build and deploy the Bun application on Koyeb each time a change is detected on your branch.

Copy the content below in the Dockerfile:

Dockerfile
FROM oven/bun:1
WORKDIR /app
COPY . .
RUN bun install
 
ARG PORT
EXPOSE ${PORT:-3000}
 
CMD ["bun", "server.ts"]

The Dockerfile above provides the minimum requirements to run the Bun application. You can easily extend it depending on your needs.

Run the Bun app locally

To launch the application locally and make sure everything is running as expected, run the following command in your terminal:

bun run server.ts

Open your browser and visit http://localhost:3000. Once the application loads, the following content will appear Hello from Koyeb.

In the previous step, we launched the Bun app using the Bun executable. We will now build and run the application using Docker.

docker build -t example-bun . # Build the Docker image
docker run --name example-bun -p 3000:3000 example-bun # Run the Docker image

If you visit the http://localhost:3000 URL, you will see the same content as before. But this time, the application is running inside a container.

With everything working as expected, we are now ready to deploy the application on Koyeb.

Push the project to GitHub

In the project directory, initialize a new git repository by running the following command:

git init

We will use this repository to version the application code and push the changes to a GitHub repository. If you don't have an existing GitHub repository to push the code to, you can create a new one and run the following commands to commit and push changes to your GitHub repository:

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

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

Deploy to Koyeb using git-driven deployment

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

  1. Create a new Koyeb App
  2. Select GitHub as the deployment option
  3. Choose the GitHub repository and branch containing your application code
  4. Select Dockefile as the builder type
  5. Name your service, for example bun-service.
  6. Name the App, for example example-bun.
  7. 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 using a pre-built container

As an alternative to using git-driven deployment, you can deploy a pre-built container from any public or private registry. This can be useful if you need more control over how the build is performed.

To build and push the Docker image to a registry and deploy it on Koyeb, refer to the page on deploying pre-built container images.