
**With native support for WebSockets, Koyeb is a good place to run real-time applications globally in minutes. [Get started](https://app.koyeb.com) for free.**

## Introduction

Many types of applications depend on real-time communication: chat, gaming, live-streaming, and collaborative tools to name a few. To develop real-time applications using Node.js, you can use WebSockets or abstraction libraries like [Socket.io](https://socket.io/).

Socket.io provides a simple and easy-to-use API to create real-time applications.
It enables real-time, bidirectional, and event-based communication between a server and clients.
Using Socket.io as an abstraction layer, you get built-in capabilities such as rooms, namespaces, and automatic reconnection out of the box.

In this guide, we will create a simple chat application with Express and Socket.io and deploy it on Koyeb using git.
Koyeb provides built-in support for WebSocket connections, making it the ideal place to deploy your WebSocket applications.

## Requirements

To successfully follow and complete this guide, you need:

- A local development environment with Node.js installed
- A [GitHub account](https://github.com/) to version and deploy your application code on Koyeb
- A [Koyeb account](https://app.koyeb.com/) to deploy and run the application

## Steps

This guide will cover how to deploy an application using WebSockets with Socket.io and Node.js on Koyeb through the following steps:

1. [**Initialize the project to use Socket.io with Express**](#initialize-the-project-to-use-socket-io-with-express)
2. [**Create the Socket.io server**](#create-the-server-using-express-and-socket-io)
3. [**Create the Socket.io client**](#create-the-client-using-socket-io)
4. [**Preview the app**](#preview-the-app)
5. [**Deploy on Koyeb**](#deploy-the-application-on-koyeb)

## Initialize the project to use Socket.io with Express

To get started, open your terminal and navigate to a location of your choice. Create the directory that will hold the application code:

```bash
mkdir socketio-on-koyeb
cd socketio-on-koyeb
```

Inside your app folder, create and initialize the package.json file. The package.json contains various metadata, gives npm information to identify the project, handles the project's dependencies, etc.

In your terminal run the following command:

```bash
$ npm init --yes

{
  "name": "socketio-on-koyeb",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "author": "",
  "license": "ISC"
}
```

As our application uses the Express framework and Socket.io, we need to add them as dependencies of our project. In your terminal, run:

```bash
npm install express socket.io --save
```

Last, open the `package.json` file and add the following entry to the `scripts` section to be able to run the application running `npm run start`:

```js
{
  "name": "socketio-on-koyeb",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "start": "node server.js", // [!code ++]
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "author": "",
  "license": "ISC",
  "dependencies": {
    "express": "^4.18.2",
    "socket.io": "^4.6.1"
  }
}
```

The project environment is now ready, we can now start writing our application.

## Create the server using Express and Socket.IO

Create and open a file named `server.js` and copy the content below:

```js
const express = require('express')
const app = express()

const port = process.env.PORT || 8000

app.get('/', function (req, res) {
  res.sendFile(__dirname + '/index.html')
})

app.listen(port, () => {
  console.log(`App listening on port ${port}`)
})
```

The code above creates a simple Express web server that serves an `index.html` file when a request is made to the root path `/`.

The next step is to initialize a new instance of Socket.io to be able to listen to incoming WebSocket connections.
We will also add the logic to handle client connection, disconnection, and emit an event of type `message` to all connected clients when a message is emitted by a client.

```js
const express = require('express')
const app = express()
const http = require('http').Server(app) // [!code ++]
const io = require('socket.io')(http) // [!code ++]

const port = process.env.PORT || 8000

app.get('/', function (req, res) {
  res.sendFile(__dirname + '/index.html')
})

io.on('connection', (socket) => { // [!code ++]
  console.log('Client connected') // [!code ++]
  socket.on('disconnect', () => { // [!code ++]
    console.log('Client disconnected') // [!code ++]
  }) // [!code ++]

  socket.on('message', (msg) => { // [!code ++]
    io.emit('message', msg) // [!code ++]
  }) // [!code ++]
}) // [!code ++]

app.listen(port, () => { //[!code --]
http.listen(port, () => { // [!code ++]
  console.log(`App listening on port ${port}`)
})
```

The server is ready and properly integrated with Socket.io. We can now create a minimalistic `index.html` page that clients will use to connect to the server and send messages to each other.

## Create the client using Socket.IO

In the current app directory, create a file named `index.html` and copy the content below:

```html
<html>
  <body>
    <ul id="messages"></ul>
    <form id="form" action=""><input id="input" autocomplete="off" /><button>Send</button></form>
    <script src="/socket.io/socket.io.js"></script>
    <script>
      var socket = io()

      var form = document.getElementById('form')
      var input = document.getElementById('input')

      form.addEventListener('submit', function (e) {
        e.preventDefault()
        if (input.value) {
          socket.emit('message', input.value)
          input.value = ''
        }
      })

      socket.on('message', function (msg) {
        var item = document.createElement('li')
        item.textContent = msg
        messages.appendChild(item)
        window.scrollTo(0, document.body.scrollHeight)
      })
    </script>
  </body>
</html>
```

## Preview the app

Launch the app running the following command:

```bash
npm run start
```

Open two different browser windows and navigate to http://localhost:8000 on each to see the chat application.
Each time you send a message, the server will emit a `message` event to all connected clients. The client will then append the message to the list of messages displayed on the page.

This means that by sending a message from your first browser window, the message will also appear in the second one and vice-versa.

We can now deploy the application on Koyeb.

## Deploy the application on Koyeb

We are going to deploy the application using git. If you want to learn how Koyeb automatically builds your application from git, read our [how we build from git](/docs/apps/build-from-git) documentation.

Initialize a new git repository on your local machine running:

```bash
git init
```

Add a new remote pointing to your GitHub repository:

```bash
git remote add origin git@github.com:<YOUR_GITHUB_USERNAME>/<YOUR_GITHUB_REPOSITORY>.git
```

Last, add the `server.js`, `package.json`, `package-lock.json` and `index.html` files to your repository and commit & push your changes:

```bash
git add server.js package.json package-lock.json index.html
git commit -m "Initial commit"
git push -u origin main
```

Next, you can deploy the app on Koyeb using the [control panel](#via-the-control-panel) or [Koyeb CLI](#via-the-cli).

### Via the control panel

From the [Koyeb Console](https://app.koyeb.com/), on the **Overview** tab, click on the **Create Web Service** button to import your project and configure your deployment.

1. Select **GitHub** as your deployment method.
2. Pick your GitHub **repository** from the list.
3. Name your App, for example `socketio-on-koyeb`.

When you are done configuring your application, click the **Deploy** button to deploy your application.
You land on the deployment page where you can follow the progress of your application's deployment.
Once the build and deployment are completed, you can access your application by clicking the App URL ending with `koyeb.app` in the Koyeb control panel.

### Via the CLI

To deploy the app on Koyeb using the [Koyeb CLI](/docs/quickstart/koyeb-cli), you will need the Koyeb CLI installed. Once installed, run the following command in your terminal:

```bash
koyeb app init socketio-on-koyeb \
  --git github.com/<YOUR_GITHUB_USERNAME>/<YOUR_REPOSITORY_NAME> \
  --git-branch main \
  --ports 8080:http \
  --routes /:8080 \
  --env PORT=8080
```

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

**Access deployment logs**

To track the app deployment and visualize build logs, execute the following command:

```bash
koyeb service logs socketio-on-koyeb/socketio-on-koyeb -t build
```

**Access your app**

Once the deployment of your application has finished, you can retrieve the public domain to access your application by running the following command:

```bash
$ koyeb app get socketio-on-koyeb
ID      	NAME           	  STATUS 	DOMAINS                               CREATED AT
2b3c4170	socketio-on-koyeb	HEALTHY	["socketio-on-koyeb-myorg.koyeb.app"]	30 Mar 23 09:06 UTC
```

**Access runtime logs**

With your app running, you can track the runtime logs by running the following command:

```bash
koyeb service logs socketio-on-koyeb/socketio-on-koyeb -t runtime
```

## Conclusion

In this tutorial, we demonstrated how to deploy a real-time application using Socket.io and Express on Koyeb. We explained how to integrate Socket.io with Express, add the logic to handle client connection, disconnection, and emit events.

Thanks to Koyeb native support for WebSockets, you can easily deploy real-time applications globally effortlessly.

You can learn more about Socket.io and explore implementations in other languages by looking at the official [documentation](https://socket.io/docs/v4/).


Deploy real-time applications with Koyeb's native support for long-running WebSocket connections. No credit card required.

Long-running WebSockets

Learn how to build and deploy real-time applications by using WebSockets with Socket.io on Koyeb.

Using WebSockets with Socket.io and Node.js on Koyeb


**Koyeb provides developers the fastest way to deploy full stack applications and APIs globally. Want to deploy your MERN stack application globally in minutes? [Sign up](https://app.koyeb.com/) today and deploy 2 services for free forever!**

## Introduction

Search capabilities help users find what they are looking for as fast as possible.
While traditional searches return exact matches, a **full-text search provides an added level of flexibility** when querying data because it returns results that contain some or all of the words from a query.

Thankfully, certain managed database providers like MongoDB offer a built-in full-text search feature. In this guide, we are going to enhance the blog application we created in the first part of this mini MERN series -
[Get started with the MERN stack: Build a blog with MongoDB Atlas](/tutorials/get-started-with-the-mern-stack-build-a-blog-with-mongodb-atlas) -
by adding full-text search with Atlas Search.

Since we deployed the application on Koyeb in the [first guide](/tutorials/get-started-with-the-mern-stack-build-a-blog-with-mongodb-atlas),
we will benefit from the platform's built-in continuous deployment. All we have to do is push our commits, and Koyeb will automatically
build and deploy the latest version of our application.

## Requirements

To successfully follow and complete this second and final part of the MERN series, you need:

- Built the app by following the first guide of the MERN series [Get started with the MERN stack: Build a blog with MongoDB Atlas](/tutorials/get-started-with-the-mern-stack-build-a-blog-with-mongodb-atlas)
- A local environment with [Yarn](https://yarnpkg.com/) and [Node.js](https://nodejs.org/en/download/) installed
- A [MongoDB Atlas](https://www.mongodb.com/cloud/atlas/register) account for your managed MongoDB database
- A [GitHub account](https://github.com/) to version and deploy your application code on Koyeb
- A [Koyeb account](https://app.koyeb.com/) running the application

## Steps

To successfully follow this guide, you need to follow these steps:

1. [Set up Atlas Search](#set-up-atlas-search)
   - [Upload the sample data](#upload-the-sample-data)
   - [Create a search index](#add-search-index)
   - [Build the aggregation pipeline to filter the posts: using $search, $limit and $project](#create-the-aggregation-pipleline-to-filter-the-posts-using-search-limit-and-project)
2. [Enhance the search API](#enhance-the-search-api-endpoint)
3. [Add Search UI in the React app](#add-search-ui-in-the-react-app)
4. [Deploy on Koyeb for built-in continuous deployment](#deploy-on-koyeb-for-built-in-continuous-deployment)

## Set up Atlas search

### Upload the sample data

In order to take advantage of the Atlas search capabilities, we first need better sample data for our blog. Luckily, there are several online resources for this. I decided to use government blog posts shared on the platform [Data.world](https://data.world/opm/open-government-blog).
I cleaned the sample data, so it would seamlessy integrate into our web app. Instead of downloading the JSON file from the website, you can take it directly from my [GitHub](https://github.com/samuxyz/mongo-blog-sample-data).

The first step to upload this data is to create a new database and collection using the [Mongo Atlas dashboard](). From the dashboard:

- Go to your database deployments
- Click on the "browse collections" tab
- Click on the left button "Create Database"
- Enter the new database and collection names. For example, I named my collection `posts`.

To upload the JSON collection from your local device you need install the package "mongodb-database-tools". The following documentation provides easy steps for the most common OS:

- [Mac OS](https://www.mongodb.com/docs/database-tools/installation/installation-macos/)
- [Windows](https://www.mongodb.com/docs/database-tools/installation/installation-windows/)
- [Linux](https://www.mongodb.com/docs/database-tools/installation/installation-linux/)

In the terminal, run the following command:

```bash
mongoimport --uri mongodb+srv://USERNAME:PASSWORD@CLUSTERNAME.<>.mongodb.net/DB_NAME --collection COLLECTION_NAME --type json --file SAMPLE_DATA_PATH --jsonArray
```

Make sure to substitute the following:

- The connection string with `USERNAME` and `PASSWORD` with your personal user credentials.

  **Note**: You can retrieve your connection string by clicking the "Connect" button next to your MongoDB cluster name. Select the "Connect your application" option and copy your database connection string to a safe place for later use.

- `DB_NAME` and `COLLECTION_NAME` with the name of the database you created and `post` as the collection name
- `SAMPLE_DATA_PATH` with the path to the index.json file on your laptop

If everything is set up correctly, you should see a successful message like `10 document(s) imported successfully. 0 document(s) failed to import.` Head to the MongoDB Atlas dashboard again and open the collection, you should see the new sample data for our blog!

### Create a search index

The blog search function will query the database for keywords within the title of a post. This means we are going to do a full-text search on the title and enable the autocomplete operators.

For this, we need to create a full-text search index on the title field. From the MongoDB dashboard for your cluster:

- Click on the "Search" tab
- Click "Create Search Index"
- Select JSON editor and "Next"

Replace the default definition with the following code:

```json
{
  "mappings": {
    "dynamic": false,
    "fields": {
      "title": [
        {
          "foldDiacritics": true,
          "maxGrams": 15,
          "minGrams": 2,
          "tokenization": "edgeGram",
          "type": "autocomplete"
        }
      ]
    }
  }
}
```

You can see that we are creating an index of type "autocomplete" on the "title" field of our collection.

There are several configuration options available in the autocomplete data type, such as tokenization strategy and diacritic folding. A complete explanation can be found on the official Atlas Search [documentation](https://www.mongodb.com/docs/atlas/atlas-search/define-field-mappings/#std-label-bson-data-types-autocomplete), but for the purpose of the tutorial we are using the following options:

- `foldDiactrics`: When true, diactricts are included in the index.
- `maxGrams` and `minGrams`: Respectively maximum and minimum number of characters per indexed sequence.
- `tokenization`: edgeGram tokenizer tokenizes input from the left side, or "edge", of a text input into n-grams of given sizes.

Name your search index for easy reference and select your database and collection collection, then click "Next".

After you reviewed your newly created index, click on "Create Search Index" where you will be redirected to the "Search" tab.
The index creation takes about a minute and when it is ready, its status will automatically change to "Active".

### Build the aggregation pipleline to filter the posts: using $search, $limit and $project

In your MongoDB Collection, click on the tab "Aggregation". We are going to create and test your query. The amazing part of the aggregation UI is that, for every stage in the pipeline, they show you the result directly form the posts collection.

![MongoDB Dashboard](/static/images/tutorials/add-full-text-search-with-mongodb-atlas-and-mern/mongodb-search-dashboard.png)

Our aggregation pipeline is composed of 3 stages/parameters:

1. `$search`: We define the index to use, the autocomplete option, the field and the query itself.
2. `$limit`: We can decide to limit the result number.
3. `$project`: What kind of fields to return for each post entry.

Whenever we add a stage, the aggregation pipeline will run and return the result in real-time.

### Using $search

The first step is to use `$search`. The `search` operator lets you perform full-text searches. Find and click on it in the dropdown menu. A basic syntax structure will show up for you to populate:

```js
{
    'index': 'title_autocomplete',
    'autocomplete': {
      'query': 'open gov',
      'path': 'title',
    }
  }
```

- Assign to `index` the name of the index we have just created.
- Since we are using the autocomplete option, replace `text` with `autocomplete`.
- `query` can be an example of a search query for now.
- `path` is the field to search upon.

Once done, you should see the UI to automatically query the collection and return the list of blog posts that satisfy the conditions above.

### Using $limit

Using `$limit`, we can simply return a subset of the result by returning only the top posts. In the aggregation UI choose `$limit` and enter 5 for example.
You should see the number of posts be limited to 5!

### Using $project

With `$project`, we can tell the query to return a subset of the posts fields. Choose `$project` in the dropdown and add the following code:

```js
'_id': 1,
'title': 1,
'author': 1,
'createdAt': 1,
```

The value of "1" tells the pipeline that we want to include specific fields. Based on the query, we want to return the `post _id`, `title`, `author` and `createdAt`. These are the only 4 values we need to show on the blog homepage.

For fun practice, you can go ahead and tweak the values of each stage and see how they affect the final result.

Finally, Atlas UI provides a handy function to quickly export the aggregation with the right syntax of several languages, Node.js included.
Under the "aggregation" tab and beside the "collation" button, click on the export pipeline and choose Node.js. Here is the resulting aggregation code:

```js
{
         '$search': {
           'index': 'title_autocomplete',
           'autocomplete': {
             'query': 'open gov',
             'path': 'title',
           }
         }
       }, {
         '$limit': 5
       }, {
         '$project': {
           '_id': 1,
           'title': 1,
           'author': 1,
           'createdAt': 1,
         }
       }
```

Notice that we still have a hard-coded "open gov" value for "query". In our backend endpoint, we are going to replace it with a dynamic search value coming from the search bar that we are building in the client.

## Enhance the search API endpoint

Return to the server code. We currently have a GET endpoint `/api/blogs` that queries the database and returns the full list of blog posts. We are going to extend its capabilities by:

- Adding a search query parameters which contains the query from the client search bar
- Adding extra logic when the search parameter exists

### Run the aggregation

When a user reaches the blog homepage, the search bar is empty so that the very first API call will not send any search parameter, the endpoint will return the whole list of posts and
typing on the search bar will trigger subsequent API calls including the extra `search` params. In our case, the endpoint will not return the whole list of posts but instead will use the aggregation function on mongoose to search for the right posts.

Here is the new code for the first API endpoint in `/routes/posts.js`:

```js
/* GET posts */
router.get('/', async (req, res, next) => {
  // We look for a query parameter "search"
  const { search } = req.query
  let posts
  if (search) {
    // If search exists, the user typed in the search bar
    posts = await Post.aggregate([
      {
        $search: {
          index: 'title_autocomplete',
          autocomplete: {
            query: search, // noticed we assign a dynamic value to "query"
            path: 'title',
          },
        },
      },
      {
        $limit: 5,
      },
      {
        $project: {
          _id: 1,
          title: 1,
          author: 1,
          createdAt: 1,
        },
      },
    ])
  } else {
    // The search is empty so the value of "search" is undefined
    posts = await Post.find().sort({ createdAt: 'desc' })
  }

  return res.status(200).json({
    statusCode: 200,
    message: 'Fetched posts',
    data: { posts },
  })
})
```

With this change, we have now added search capabilities to our Node server.

## Add Search UI in the React app

The second to last step of the tutorial is to add the search bar to the homepage of our client.
As we are using `react-boostrap`, all we need to do is import `Form` and `FormControl` components. Then, we are going to attach an action listener on "onChange" events to call our backend whenever a user inputs anything in the search bar.

Open `home.js` inside `/client/src/pages` and add the following code:

```js
import { useEffect, useState } from 'react'
import Container from 'react-bootstrap/Container'
// Here we import the new components for the seach bar
import Form from 'react-bootstrap/Form'
import FormControl from 'react-bootstrap/FormControl'
import Image from 'react-bootstrap/Image'
import ListGroup from 'react-bootstrap/ListGroup'
import { Link } from 'react-router-dom'

import formatDate from '../lib/formatDate'
import http from '../lib/http'

const Home = () => {
  const [posts, setPosts] = useState([])
  useEffect(() => {
    async function fetchData() {
      const { data } = await http.get('/api/posts')
      setPosts(data.data.posts)
    }
    fetchData()
  }, [])
  /* We are creating a new function that calls the API endpoint
     and passing the search value as a query parameter
  */
  const searchPost = async (e) => {
    const searchValue = e.target.value
    const { data } = await http.get(`/api/posts?search=${searchValue}`)
    // The subset of posts is added to the state that will trigger a re-render of the UI
    setPosts(data.data.posts)
  }

  return (
    <>
      <Container className="my-5" style={{ maxWidth: '800px' }}>
        <Image
          src="avatar.jpeg"
          width="150"
          style={{ borderRadius: '50%' }}
          className="d-block img-fluid mx-auto"
        />
        <h2 className="text-center">Welcome to the Digital Marketing blog</h2>
        // Let's add the search bar under the subheader
        <Form>
          <FormControl
            type="search"
            placeholder="Search"
            className="me-5"
            aria-label="Search"
            onChange={searchPost} // onChange will trigger "search post"
          />
        </Form>
      </Container>
      <Container style={{ maxWidth: '800px' }}>
        <ListGroup variant="flush" as="ol">
          {posts.map((post) => {
            return (
              <ListGroup.Item key={post._id}>
                <div className="fw-bold h3">
                  <Link to={`/posts/${post._id}`} style={{ textDecoration: 'none' }}>
                    {post.title}
                  </Link>
                </div>
                <div>
                  {post.author} - <span className="text-secondary">{formatDate(post.createdAt)}</span>
                </div>
              </ListGroup.Item>
            )
          })}
        </ListGroup>
      </Container>
    </>
  )
}

export default Home
```

Thanks to this new code, we added search capabilities to our blog with only a bit more than 10 lines of code!

### Render posts content as HTML

The last code change in the client is a pure UI enhancement in the `post.js` page that handles the new format of a post content. When we imported the dataset from data.world, the content contains some HTML code for symbols such as commas, semicolons, etc.
Open `post.js` inside `/client/src/pages` and change the following line of code:

```html
from
<div className="h4 mt-5">{post.content}</div>
to
<div className="h4 mt-5" dangerouslySetInnerHTML="{{__html:" post.content}}></div>
```

By injecting HTML, we are going to show the symbols used in the content in the correct format.

## Deploy on Koyeb for built-in continuous deployment

Finally, you just have to commit your changes with git and Koyeb will trigger a redeployment of the app with the new search functionality!

![MERN blog with full-text search](/static/images/tutorials/add-full-text-search-with-mongodb-atlas-and-mern/blog-homepage.png)

## Conclusion

Congratulations for finishing the second and last part of the MERN tutorial!

In this second part, we successfully indexed our posts collection to make use of Atlas Search capabilities. We also created an aggregation pipeline with autocomplete to add search functionalities to your blog. During the pipeline creation, we played with `$search`, `$limit` and `$project` to create a basic aggregation that satisfies our requirements.
Then, we tweaked our server and client code to allow users to query the blog's database and search for posts by title.

If you want, you can read more about MongoDB Atlas Search and its different features and capabilities [here](https://www.mongodb.com/basics/full-text-search).

The last step was deploying the newest code, which was easy because it was once again handled by Koyeb. Koyeb is making it extremely simple for developers: Just commit your code and Koyeb will trigger the redeployment.

If you would like to read more Koyeb tutorials, checkout out our [tutorials collection](/tutorials). Have an idea for a tutorial you'd like us to cover? Let us know by joining the conversation over on the **[Koyeb community platform](https://community.koyeb.com/)**!


This is the second part of our mini MERN series. In this guide, we showcase how to add search capabilities to the MERN blog we created in part one using MongoDB Atlas Search.

Add full-text search with MongoDB Atlas and MERN

Discover the MERN stack by learning how to build a blog application using MongoDB Atlas, Express, React, and Node. Then, learn how to deploy your MERN stack on the Koyeb Serverless Platform. This guide is the first in a mini-series on the MERN stack.

Get started with the MERN stack: Build a blog with MongoDB Atlas

bigpdfconverter

This guide shows how to deploy a web scraper using Puppeteer, Node.js, Docker and Express.js on the Koyeb Serverless Platform.

Deploy a Web Scraper using Puppeteer, Node.js and Docker on Koyeb


## Introduction

[NestJS](/docs/deploy/nestjs) is a Node.js framework to build efficient and scalable server-side applications. Nest uses and abstracts ExpressJS under the hood to ease development but keeps its API accessible to developers.
This allows you to compose and use all Express's compatible third-party modules and middlewares. In addition to Express, you can also configure Nest to use Fastify, another popular Node.js framework.
Nest is built with typescript and combines the use of object-oriented programming, functional programming, and functional reactive programming.

In this tutorial, we will create a minimalist NestJS application and showcase how to deploy the application with continuous deployment on Koyeb.
By deploying the Nest application on Koyeb using the git-driven deployment method, each time you push new changes to your GitHub repository, a new deployment will occur and be promoted once the built and health checks are completed.

Thanks to Koyeb, you will benefit from native global load-balancing across our edge network, autoscaling, automatic HTTPS (SSL), and auto-healing with zero configuration.

## Requirements

To successfully follow and complete this guide, you need:

- A local development environment with Node.js installed
- A [GitHub account](https://github.com)
- A [Koyeb account](https://app.koyeb.com) to deploy and run the Nest application

## Steps

To successfully complete this tutorial and deploy the Nest application on Koyeb Serverless Platform, you need to follow these steps:

1. [Create and configure the Nest application](#create-and-configure-the-nest-application)
2. [Push the sources to GitHub](#push-the-sources-to-git-hub)
3. [Deploy the Nest app on Koyeb](#deploy-the-nest-app-on-koyeb)

## Create and configure the Nest application

### Installing the NestJS CLI

To get started, we need to install the Nest CLI. In your terminal run the following command:

```bash
npm i -g @nestjs/cli
```

### Create a new Nest application

The Nest CLI installed, we can initialize a new Nest app running:

```bash
nest new nestjs-on-koyeb
```

The command below created a directory `nestjs-on-koyeb` containing the node modules to properly run the Nest application and a few other boilerplate files.

```bash
.
├── README.md
├── nest-cli.json
├── node_modules
├── package-lock.json
├── package.json
├── src
│   ├── app.controller.spec.ts
│   ├── app.controller.ts
│   ├── app.module.ts
│   ├── app.service.ts
│   └── main.ts
├── test
│   ├── app.e2e-spec.ts
│   └── jest-e2e.json
├── tsconfig.build.json
└── tsconfig.json
```

### Configuring the Nest application

By default, the Nest listens on port 3000. There are many cases you will want the application to listen on a different port.
Replace the line below to allow setting up the port via the `PORT` environment variable or use the port 3000 if no environment variable is provided in the `src/main.ts` file.

`main.ts` is the entry file of the application which uses the core function NestFactory to create a Nest application instance.

```typescript
await app.listen(3000) // [!code --]
await app.listen(process.env.PORT || 3000) // [!code ++]
```

Then, open and edit the `package.json` file to specify the `npm` and `node` versions to use. Here we use the Node LTS version and the latest NPM version:

```typescript
  ...
  "engines": {
    "node": "14.x",
    "npm": "7.x"
  },
  ...
```

## Push the sources to GitHub

Once the edits are performed, we can commit and push our application to a GitHub repository. When we previously ran the `nest new nestjs-on-koyeb` command, a git repository has been initialized so we don't need to run `git init` inside our application directory.

Add the Nest application sources:

```
git add .
git commit -m "Nest app initial commit"
```

Add a new remote pointing to your GitHub repository:

```
git remote add origin git@github.com:<YOUR_GITHUB_USERNAME>/<YOUR_GITHUB_REPOSITORY>.git
```

Rename the repository default branch to `main` running:

```
git branch -M main
```

Push your changes to the GitHub repository:

```
git push -u origin main
```

## Deploy the Nest app on Koyeb

On the **Overview** tab of the [Koyeb control panel](https://app.koyeb.com), click the **Create Web Service** button to begin:

1. Choose **GitHub** as the deployment method.
2. In the repositories selector, select the repository containing your Nest application sources.
3. In the **Builder** section, click the **Override** toggle associated with the **Run command** and enter `npm run start:prod` in the field.
4. In the **Environment variables** section, add a new entry with the name `NODE_ENV` and `production` as value.
5. Choose a name for your App and Service, for example `koyeb-nestjs-demo`, and click **Deploy**.

You land on the deployment page where you can follow the build of your Nest application. Once the build is completed, your application is being deployed and you will be able to access it via `<APP_NAME>.<ORG_NAME>.koyeb.app`.

If you want to learn about how Koyeb automatically builds your applications from git, make sure to read our [how we build from git](/docs/apps/build-from-git) documentation.

In this guide, we showcased how Koyeb simplifies the deployment of a NestJS application. With minimal effort, you have a complete, production-ready environment with native global load-balancing, TLS encryption, autoscaling, autohealing, and more to run your Nest application.

## Conclusion

Want more NestJS on Koyeb? Check out our [NestJS documentation](/docs/deploy/nestjs) to learn how to deploy a NestJS application on Koyeb.


This guide explains how to continuously deploy a NestJS application on the Koyeb serverless platform.

Continuous Deployment of a NestJS Application on Koyeb


## Introduction

Heroku provides managed Postres databases and makes them accessible over the Internet. Whether you are an existing Heroku user wanting to deploy your apps globally while keeping your database on Heroku or looking for a place to host a managed Postgres database, this guide explains how to use and connect a Heroku Postgres database from an application running on Koyeb.

Heroku allows you to create Heroku Apps using add-ons. Since its managed PostgreSQL database is an add-on, this means you can create a Heroku app that only runs the Postgres database without having to deploy your entire application on Heroku.

In this guide, we will create a Heroku App with a Heroku Postgres add-on, create a simple Node.js application to connect the database and deploy the application on Koyeb.

## Requirements

For this guide, you need:

- A [Koyeb account](https://app.koyeb.com/auth/signin) to deploy and run the Node application
- A [Heroku account](https://id.heroku.com/login) to run the Heroku Postgress add-on
- The [Koyeb CLI](https://github.com/koyeb/koyeb-cli) installed to interact with Koyeb from the command line
- A registry that will store our Node app Docker image that will be deployed on Koyeb

## Steps

To use and connect a Heroku Postgres database on Koyeb, you need to follow these steps:

1. [**Create a Heroku App with the Postgres add-on**](#create-a-heroku-app-with-the-postgres-add-on)
2. [**Write a Node.js app connection to the Heroku Postgres database**](#write-a-node-js-app-to-connect-to-the-heroku-postgres-database)
3. [**Deploy the Node.js app on Koyeb**](#deploy-the-node-js-app-on-koyeb)

## Create a Heroku App with the Postgres add-on

In the Heroku [control panel](https://dashboard.heroku.com/), on the top right navigation bar, click the **Create** button and select **Create new app**.
You land on the App creation form where you need to:

- Give your application a name
- Choose the region your App will be located: Europe or the United-States

Once the form is filled in, click the **Create app** button. Then click the **Resources** tab and in the **Add-ons** section of the page fill the search input with **Heroku Postgres** and validate.
A modal opens and asks you to select the plan you want to use. In this guide, we use the Heroku Postgres add-on free tier **Hobby Dev**. Once the plan you want to use is selected, click **Submit order form**.

## Write a Node.js app to connect to the Heroku Postgres database

With the Heroku Postgres add-on deployed, we will now create a basic Node application to connect the database. We will then deploy this application on Koyeb.

### Initialize the environment

```bash
mkdir node-demo
cd node-demo
yarn init
yarn add express sequelize pg pg-hstore
```

### Create the app

In the `node-demo` directory, create a new file `app.js` and paste the snippet below.
The app uses Express and Sequelize to connect the Heroku database and expose an API endpoint on `/` to return Todo mock data from the database.

```js
const { Sequelize } = require('sequelize')
const express = require('express')

const port = 3000(async () => {
  try {
    const sequelize = new Sequelize(process.env.PG_URL, {
      dialectOptions: {
        ssl: { sslmode: 'true', rejectUnauthorized: false },
      },
    })
    await sequelize.authenticate()
    console.log('Connection has been established successfully.')

    console.log('Create fake data.')
    const todos = sequelize.define('todos', { todo: Sequelize.TEXT })
    await sequelize.sync({ force: true })

    await todos.bulkCreate([
      { todo: 'Create a Koyeb account.' },
      { todo: 'Deploy my app.' },
      { todo: 'Enjoy!' },
    ])

    const app = express()

    app.get('/', async (_, res) => {
      items = await todos.findAll()
      res.json(items)
    })
    app.listen(port, () => {
      console.log(`Demo app listening at http://localhost:${port}`)
    })
  } catch (error) {
    console.error('Unable to connect to the database:', error)
  }
})()
```

### Write the Dockerfile and build the Docker image

To Dockerize our Node.js app, you need to create a `Dockerfile` in your project folder containing the content below.

```dockerfile
FROM node:lts as runner
WORKDIR /node-express
ENV NODE_ENV production
COPY . .
RUN npm ci --only=production
EXPOSE 3000
CMD ["node", "app.js"]
```

To build and properly tag the Docker image execute the following command:

```bash
docker build . -t ghcr.io/<YOUR_GITHUB_USERNAME>/node-app
```

_In this guide, we will push the Docker image to a GitHub container registry. You are free to use another different registry as Koyeb allows you to deploy from any container registry._

Once the build is over, you can run a container using the image locally to validate everything is working as expected running:

```bash
docker run -p 3000:3000 ghcr.io/<YOUR_GITHUB_USERNAME>/node-app
```

As in the previous step, you can perform a curl request to ensure the app is running as expected:

```bash
$curl http://localhost:3000/
[
  {
    "id": 1,
    "todo": "Create a Koyeb account.",
    "createdAt": "2021-07-21T10:18:16.576Z",
    "updatedAt": "2021-07-21T10:18:16.576Z"
  },
  {
    "id": 2,
    "todo": "Deploy my app.",
    "createdAt": "2021-07-21T10:18:16.576Z",
    "updatedAt": "2021-07-21T10:18:16.576Z"
  },
  {
    "id": 3,
    "todo": "Enjoy!",
    "createdAt": "2021-07-21T10:18:16.576Z",
    "updatedAt": "2021-07-21T10:18:16.576Z"
  }
]
```

### Push the Docker image to the GitHub container registry

With the Docker image built and functional, we can now upload it to the GitHub container registry.
In your terminal run the command below to push the image:

```bash
ghcr.io/<YOUR_GITHUB_USERNAME>/node-app
```

Once the push command is completed, the Docker image is stored in your GitHub container registry.

## Deploy the Node.js app on Koyeb

We are now ready to deploy our application on Koyeb. First, create a Koyeb Secret to store your container registry configuration.
In this guide, we will deploy our app from the GitHub container registry. For other container registries examples, check out this related [documentation](/docs/apps/private-container-registry-secrets).

_If your Docker image is public, there is no need to create a secret containing your container registry configuration._

```bash
echo \
'{
  "auths": {
    "https://ghcr.io": {
      "username": "<REPLACE_ME_WITH_GITHUB_USERNAME>",
      "password": "<REPLACE_ME_WITH_GITHUB_TOKEN>"
    }
  }
}' | koyeb secrets create ghcr-credentials
```

Then, create a second secret to securely store your Heroku Postgres database connection string.
You can retrieve the information from the [Heroku control panel](https://data.heroku.com/), selecting your database, clicking the **Settings** tab and clicking the **View credentials** button.

Copy the URI and create the Koyeb secret to securely store running in your terminal:

```bash
$koyeb secrets create heroku-pg-url
postgres://...
```

We are now ready to deploy our application, in the terminal run:

```bash
koyeb app init node-app --docker "ghcr.io/<YOUR_GITHUB_USERNAME>/node-app" --ports 3000:http --routes /:3000 --docker-private-registry-secret ghcr-credentials --env PG_URL=@heroku-pg-url
```

This command creates a new Koyeb App and deploys our Node application exposing port 3000 and making it publicly accessible on the `/` route of your Koyeb App URL.

To retrieve your Koyeb App URL and access your application, run:

```bash
$koyeb app get node-app
ID                                  	NAME           	DOMAINS                             	UPDATED AT
d58ebed1-48c0-46b7-a2f1-91f3ffdbccf2	node-app        node-app-<YOUR_ORG>.koyeb.app         2021-06-23 09:46:55.411403 +0000 UTC
```

Open the URL in your browser to access your application running on Koyeb. The application returns the mock Todo data stored in the Heroku Postgres database.
By running your application on Koyeb you benefit from native autoscaling, automatic HTTPS (SSL), auto-healing, and global load-balancing across our edge network allowing you to make your applications faster and distribute your content near your users thanks to Koyeb's 55 edge locations.


This guide explains how to use and connect an Heroku Postgres database from a Koyeb app.

How to use Heroku Postgres with Koyeb Serverless Platform


**Koyeb provides developers the fastest way to deploy full stack applications and APIs globally. Want do deploy your Node.js application globally in minutes? [Sign up](https://app.koyeb.com/) today and deploy 2 services for free forever!**

## Introduction

In this guide, we will explain how to deploy a Node.js Express application to production. We will write a simple Node.js API using the Express framework, see how to Dockerize the application,
version it on GitHub, and create a GitHub Actions workflow to perform the CI/CD and deploy the application on Koyeb each time you push changes on a specific branch.

By deploying the Node app on Koyeb, you benefit from native autoscaling, automatic HTTPS (SSL), auto-healing, and global load-balancing across our edge network with zero configuration.

## Requirements

To successfully follow and complete this guide, you need:

- [Docker](https://docs.docker.com/get-docker/) installed on your machine
- A [Koyeb account](https://app.koyeb.com) to deploy and run the Node.js Express application
- The [Koyeb CLI](https://github.com/koyeb/koyeb-cli) installed to interact with Koyeb from the command line
- Have [configured Docker for use with the GitHub container registry](https://docs.github.com/en/packages/guides/configuring-docker-for-use-with-github-packages)
- A [GitHub account](https://www.github.com) with an empty repository we will use to version the application and perform the CI/CD with GitHub Actions

## Steps

To deploy a Node Express Application to Production, you need to follow these steps:

1. [**Create a simple Node.js API using the Express app or use an existing one**](#create-a-simple-node-js-api-using-the-express-framework-application-or-use-an-existing-one)
2. [**Write the Dockerfile and build the Docker image**](#write-the-dockerfile-and-build-the-docker-image)
3. [**Push the Docker image to the GitHub container registry**](#automate-deployment-with-git-hub-actions)
4. [**Deploy the Dockerized Node.js app on Koyeb**](#deploy-the-dockerized-node-js-app-on-koyeb)
5. [**Automate deployment with GitHub Actions**](#automate-deployment-with-git-hub-actions)

## Create a simple Node.js API using the Express framework application or use an existing one

If you already have an existing Node.js application you want to dockerize, you can jump to the next step.

Create a new directory to store our Node.js application:

```bash
mkdir node-express
cd node-express
```

The next step is to create and initialize the package.json file. The package.json contains various metadata and gives npm information to identify the project, handles the project's dependencies, etc.

In your terminal run the following command and complete as below:

```bash
$npm init

This utility will walk you through creating a package.json file.
It only covers the most common items, and tries to guess sensible defaults.

See `npm help init` for definitive documentation on these fields
and exactly what they do.

Use `npm install <pkg>` afterwards to install a package and
save it as a dependency in the package.json file.

Press ^C at any time to quit.
package name: (node-express)
version: (1.0.0)
description: A simple Node.js with Express framework application
entry point: (index.js) app.js
test command:
git repository:
keywords:
author:
license: (ISC)
About to write to /Users/koyeb/demo/node-express/package.json:

{
  "name": "node-express",
  "version": "1.0.0",
  "description": "",
  "main": "app.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "author": "",
  "license": "ISC"
}


Is this OK? (yes)
```

As our application uses the Express framework, we need to add it as a dependency of our project. In your terminal, run:

```
npm install express --save
```

The project environment ready, we can now start writing our application. In this guide, we create a basic application that will return the port and git commit id the application is using on requests received to the root URL `/`. All other routes will respond with a 404 error.

Create and open a file named `app.js` and copy the content below:

```js
const express = require('express')
const app = express()
const port = process.env.PORT || 3000

app.get('/', (req, res) => {
  res.json({
    commit_id: process.env.COMMIT_ID || 'unknown',
    port,
  })
})

app.listen(port, () => {
  console.log(`App listening at http://localhost:${port}`)
})
```

Launch the app running `node app.js` and request the `/` endpoint running:

```bash
curl http://localhost:3000/
{"commit_id":"unknown","port":3000}
```

The Node app responds with the port the application is listening to "3000" and commit_id set at "unknown" for the moment.

## Write the Dockerfile and build the Docker image

To Dockerize our Node.js app, you need to create a `Dockerfile` in your project folder containing the content below.

```dockerfile
FROM node:lts as runner
WORKDIR /node-express
ENV NODE_ENV production
ARG COMMIT_ID
ENV COMMIT_ID=${COMMIT_ID}
COPY . .
RUN npm ci --only=production
EXPOSE 3000
CMD ["node", "app.js"]
```

To build and properly tag the Docker image execute the following command:

```bash
docker build . -t ghcr.io/<YOUR_GITHUB_USERNAME>/node-express:prod
```

Once the build is over, you can run a container using the image locally to validate everything is working as expected running:

```bash
docker run -p 3000:3000 ghcr.io/<YOUR_GITHUB_USERNAME>/node-express:prod
```

As in the previous step, you can perform a curl request to ensure the app is running as expected:

```bash
$curl http://localhost:3000/
{"commit_id":"unknown","port":3000}
```

## Push the Docker image to the GitHub container registry

With our image built, we can now push it to the GitHub container registry. We will then use this image to deploy the application on Koyeb.

```bash
docker push ghcr.io/<YOUR_GITHUB_USERNAME>/node-express:prod
```

Within a few minutes, you will see your Docker image available on the GitHub container registry: `https://github.com/<YOUR_GITHUB_USERNAME>?tab=packages`.

## Deploy the Dockerized Node.js app on Koyeb

To deploy our dockerized Node.js application on Koyeb, start by creating a Koyeb Secret to store your Github container registry configuration.
Replace `<REPLACE_ME_WITH_GH_USERNAME>` with your GitHub username and `<REPLACE_ME_WITH_GH_TOKEN>` with a valid GitHub token having registry read/write permissions and execute the command below.

```bash
echo \
'{
  "auths": {
    "ghcr.io": {
      "username": "<REPLACE_ME_WITH_GH_USERNAME>",
      "password": "<REPLACE_ME_WITH_GH_TOKEN>"
    }
  }
}' | koyeb secrets create gh-registry-credentials
```

We can now deploy the Node.js application on Koyeb Serverless Platform running:

```bash
koyeb app init node-express --docker "ghcr.io/<REPLACE_ME_WITH_GH_USERNAME>/node-express:prod" --ports 3000:http --routes /:3000 --docker-private-registry-secret gh-registry-credentials
```

Within a few minutes, your application will be live and accessible at `https://node-express-<REPLACE_ME_WITH_GH_USERNAME>.koyeb.app`.

## Automate deployment with GitHub Actions

In the previous steps, we discovered how to dockerize and deploy a Node.js application on Koyeb.

In this section, we will see how to automate the deployment of ou application each time a change is pushed to the branch `main` of your repository using GitHub Actions.

In your git repository, create a folder to store our GitHub Actions workflow:

```
mkdir -p .github/workflows
cd .github/workflows
```

Create a new file named `workflow.yaml` inside the directory we created in the previous step and paste the snippet below:

```yaml
name: CI

on:
  push:
    branches:
      - main

env:
  GHCR_TOKEN: ${{ secrets.GHCR_TOKEN }}

jobs:
  build-push:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v2
      - name: Seed env
        run: |
          echo $GITHUB_SHA | awk '{ printf "SHORT_SHA1=%.7s\n", $1 }' >> $GITHUB_ENV
          basename $GITHUB_REF | awk '{ printf "BRANCH_NAME=%s\n", $1 }' >> $GITHUB_ENV
      - name: Docker build
        run: docker build --rm=false --build-arg COMMIT_ID=$GITHUB_SHA -t ghcr.io/<YOUR_GITHUB_USERNAME>/node-express:prod . # REPLACE <YOUR_GITHUB_USERNAME> with your GitHub username.
      - name: Docker login
        run: echo $GHCR_TOKEN | docker login ghcr.io -u <YOUR_GITHUB_USERNAME> --password-stdin # REPLACE <YOUR_GITHUB_USERNAME> with your GitHub username.
      - name: Docker push
        run: docker push ghcr.io/<YOUR_GITHUB_USERNAME>/node-express:prod # REPLACE <YOUR_GITHUB_USERNAME> with your GitHub username.
      - name: Deploy on Koyeb
        uses: koyeb-community/koyeb-actions@v2
        with:
          api_token: '${{ secrets.KOYEB_TOKEN }}'
      - run: koyeb services redeploy --app=node-express node-express
```

In your GitHub repository settings, click **Secrets** in the left-side menu and create new secrets:

- `GHCR_TOKEN` containing a valid GitHub token having registry read/write permissions to push the image to the registry.
- `KOYEB_TOKEN` containing a valid Koyeb token to redeploy the application.

Commit and push your GitHub actions workflow, your GitHub Actions workflow is being executed. Each time a change is pushed on the `main` branch, a Docker image is built and push to the GitHub registry with the tag `prod`. Once the image pushed,
a new deployment is triggered and deployed on the Koyeb Serverless platform.

## Conclusion

In this guide, we explained how to containerize a Node.js application and deploy it on Koyeb. We created a GitHub Actions workflow to build and deploy the application each time a change occurs.
By deploying on Koyeb, your application is secured with native TLS encryption and benefits from all the Koyeb Serverless features including autoscaling, auto-healing, and a high-performance edge network.

If you would like to read more Koyeb tutorials, checkout out our [tutorials collection](/tutorials). Have an idea for a tutorial you'd like us to cover? Let us know by joining the conversation over on the **[Koyeb community platform](https://community.koyeb.com/)**!


Enjoy fast deployments for your Node Express applications. No credit card required.

Express Deployments

This guide explains how to deploy a Node.js Express application using Docker to containerize our app, GitHub actions to perform the CI and CD, and Koyeb Serverless Platform to run the application.