Deploy a Hapi App

This guide explains how to deploy a basic Hapi (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 Express 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 Hapi app

We will begin by creating a basic Hapi 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.

Create a new project and install dependencies

To get started, create a directory to hold the Hapi project files and then enter the new directory:

mkdir example-hapi
cd example-hapi

Inside the project directory, initialize a new Node.js project by with the npm init command:

npm init --yes

This will generate a basic package.json file and allow us to begin installing and managing dependencies.

Install Hapi within the new project directory by typing:

npm install @hapi/hapi

This will install Hapi with its dependencies.

Create the application file

Now that Hapi is installed, we can use it to create a basic web application.

Open a new file called app.js and paste the following within:

// app.js
 
'use strict'
 
const Hapi = require('@hapi/hapi')
const port = process.env.PORT || 3000
 
const init = async () => {
  const server = Hapi.server({
    port: port,
    host: '0.0.0.0',
  })
 
  server.route({
    method: 'GET',
    path: '/',
    handler: (request, h) => {
      return 'Hello World!'
    },
  })
 
  await server.start()
  console.log('Server running on %s', server.info.uri)
}
 
process.on('unhandledRejection', (err) => {
  console.log(err)
  process.exit(1)
})
 
init()

The above code imports Hapi into the project and uses it to create a basic web server. We configure the application to listen on the port specified by the PORT environment variable, with port 3000 as a fallback value. Afterwards, we configure a route that responds with a "Hello World!" message to requests on /.

Test the web application

The app.js file is all that we need to run our basic web app. Try it out now by typing:

node app.js

If you visit http://localhost:3000 in your web browser, Hapi should serve the "Hello World!" message we configured.

You can also verify that the listening port is configurable by passing a PORT value to the command:

PORT=5555 node app.js

This time, Hapi should be listening on port 5555 instead of the default port 3000.

Define a start script

The last thing we should do is define a start script for the project. Koyeb's Node.js buildpack automatically executes the start script defined in the package.json to start the application. Since our package.json file is very basic, we do not currently have a start script. Let's define one now.

Open the package.json file in your editor and define a start command in the scripts section of the file:

{
  . . .
  "scripts": {
    "start": "node app.js",
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  . . .
}

Here, we map the start script to the same command we used to run the application during testing. You can verify that it works as expected by typing:

npm run start

The server should start up and serve the file on port 3000, as per usual.

.git
.gitignore
Dockerfile
.dockerignore
node_modules

FROM node:lts-alpine
 
USER node
WORKDIR /home/node
 
COPY . .
RUN npm ci
 
ARG PORT
EXPOSE ${PORT:-3000}
 
CMD ["npm", "run", "start"]

Push the project to GitHub

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

git init

Next, download a basic .gitignore file designed for Node.js projects from GitHub:

curl -L https://raw.githubusercontent.com/github/gitignore/main/Node.gitignore -o .gitignore

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

Deploy to Koyeb using git-driven deployment

Once the repository is pushed to GitHub, you can deploy the Hapi 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.

Deploy to Koyeb from a container registry

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