Deploy your full-stack web apps across continents and run on an edge network of 250 locations.

Global serverless deployments

In this guide, we demonstrate how to deploy and configure Infisical to help you manage secrets and other configuration for applications across your environments.

How to Deploy Infisical to Manage Application Secrets on Koyeb

Set up Strapi as a production-ready content management backend for your website, blog, or application.

How to Deploy Strapi as a Content Backend and Headless CMS on Koyeb


## Introduction

[Wasp](https://wasp-lang.dev/) is a full-stack web framework built to provide a modern take on a Rails-like development experience. Built on top of React, Node.js, and Prisma, Wasp provides the components and structure you need to create well-architected, and feature-rich web experiences.

In this tutorial, we will show how to create and deploy a Wasp application to Koyeb. The application will consist of a server component and a frontend and will be backed by a PostgreSQL database. We will use a Dockerfile to define containers for the two application layers and deploy them using Koyeb's [Dockerfile build feature](/docs/build-and-deploy/build-from-git#the-dockerfile-build-process).

You can consult the [repository for this guide](https://github.com/koyeb/example-wasp) to follow along on your own. You can deploy the Wasp server process by clicking the [Deploy to Koyeb button](/docs/build-and-deploy/deploy-to-koyeb-button) below:

[![Deploy to Koyeb](https://www.koyeb.com/static/images/deploy/button.svg)](https://app.koyeb.com/deploy?name=example-wasp-server&type=git&repository=koyeb%2Fexample-wasp&branch=main&builder=dockerfile&target=server-production&instance_type=nano&env%5BDATABASE_URL%5D=CHANGE_ME&env%5BJWT_SECRET%5D=CHANGE_ME&env%5BWASP_SERVER_URL%5D=CHANGE_ME&env%5BWASP_WEB_CLIENT_URL%5D=CHANGE_ME&ports=8000%3Bhttp%3B%2Fapi)

Be sure to modify all of the environment variable values to reflect your own data. You can consult this guide if you need additional information on appropriate values.

Once the server is deployed, you can deploy the frontend with the following deploy button:

[![Deploy to Koyeb](https://www.koyeb.com/static/images/deploy/button.svg)](https://app.koyeb.com/deploy?name=example-wasp-web-app&type=git&repository=koyeb%2Fexample-wasp&branch=main&builder=dockerfile&target=web-app-production&instance_type=nano&env%5BREACT_APP_API_URL%5D=CHANGE_ME&ports=8000%3Bhttp%3B%2F)

Again, be sure to modify the environment variable configuration to match your information.

## Requirements

To successfully follow and complete this guide, you need:

- A [Koyeb account](https://app.koyeb.com) to provision the PostgreSQL database and to build and deploy the Wasp application components.
- [Node.js](https://nodejs.org/en/download) and the `npm` package manager installed on your local computer.

## Steps

To complete this guide and deploy a Wasp application, you'll need to follow these steps:

1. [Install Wasp on your local computer](#install-wasp-on-your-local-computer)
2. [Create a new Wasp project](#create-a-new-wasp-project)
3. [Provision a PostgreSQL database on Koyeb](#provision-a-postgre-sql-database-on-koyeb)
4. [Configure the Wasp project to use the PostgreSQL database](#configure-the-wasp-project-to-use-the-postgre-sql-database)
5. [Create a Dockerfile](#create-a-dockerfile)
6. [Push the project to GitHub](#push-the-project-to-git-hub)
7. [Deploy the Wasp backend service to Koyeb](#deploy-the-wasp-backend-service-to-koyeb)
8. [Deploy the Wasp web app to Koyeb](#deploy-the-wasp-web-app-to-koyeb)

## Install Wasp on your local computer

To get started, you'll need to install Wasp on your local computer.

You can download and run the installation script by typing the following. This guide was written to target Wasp version `v0.13.2`. If you are using a different version of Wasp, the functionality and specifically the [Dockerfile creation process](#create-a-dockerfile) may be different:

```bash
curl -sSL https://get.wasp-lang.dev/installer.sh | sh -s -- --version 0.13.2
```

The installation script will download the given Wasp release and install it on your system. You may be prompted to modify one of your shell configuration files to add the Wasp installation directory to your `PATH`.

You can check that the installation was successful by typing:

```bash
wasp version
```

The output should tell you the current version information and provide instructions on how to upgrade or switch to a different version if desired.

## Create a new Wasp project

Now that the Wasp CLI is installed, you can use it to create a new project. We will use a [todo app starter template](https://wasp-lang.dev/docs/project/starter-templates#todo-app-w-typescript) for our project so that we can show how to deploy an application with a database, frontend, and backend.

Create a new project from the template by typing:

```bash
wasp new example-wasp -t todo-ts
```

Navigate into the newly generated project directory and follow the instructions to run the database migrations on the new application:

```bash
cd example-wasp
wasp db migrate-dev
```

It will indicate that the database file cannot be found and create a new one. You may be prompted to enter a name for the new migration.

Once the database is initialized, start the development server by typing:

```bash
wasp start
```

Wasp will build the project and serve it using a basic web server. If you navigate to `http://localhost:3000` in your web browser, you will be redirected to the application's login page. Click the link to sign up for a new account and enter account details. Once authenticated, you'll be taken to a basic todo list application.

If, instead, you navigate to `http://localhost:3001`, you can access the server process.

Press <kbd>CTRL</kbd>-<kbd>C</kbd> to stop the development server when you are finished.

## Provision a PostgreSQL database on Koyeb

Wasp uses a local SQLite during development as a quick and easy way to get started without much overhead. However, for production deployments, Wasp requires a PostgreSQL database. We will use [Koyeb's PostgreSQL service](https://www.koyeb.com/docs/databases) which includes a free tier that we can use to get started.

To deploy a new PostgreSQL database, on the **Overview** tab of the [Koyeb control panel](https://app.koyeb.com/), click **Create Database Service**. Choose a name for the service and choose the region closest to you or your users.

Once the database is provisioned, click the **copy icon** associated with `psql` to save the connection details for later.

## Configure the Wasp project to use the PostgreSQL database

Now that we have an external PostgreSQL database, we can modify our project configuration to use it.

Start by creating an environment file to store the database credentials. The server process is the only component that needs to access the database. It automatically consults variables stored in a `.env.server` file.

Create a `.env.server` file and set `DATABASE_URL` to the connection string you copied from the Koyeb database. Append `?ssl_mode=require` to the end of the connection string since the database requires a secure connection:

```env /<YOUR_DATABASE_CONNECTION_STRING>/
DATABASE_URL=<YOUR_DATABASE_CONNECTION_STRING>?ssl_mode=require
```

Next, open the `main.wasp` file in your project root. In the main `app` configuration, add a `db` key to set the database type to PostgreSQL:

```javascript
app exampleWasp {
  db: {  // [!code ++]
    system: PostgreSQL,  // [!code ++]
  },  // [!code ++]
  wasp: {
    version: "^0.13.0"
  },
  title: "example-wasp",

  auth: {
    userEntity: User,
    methods: {
      usernameAndPassword: {}, // This is a very naive implementation, use 'email' in production instead
      //google: {}, // https://wasp-lang.dev/docs/integrations/google
      //gitHub: {}, // https://wasp-lang.dev/docs/integrations/github
      //email: {} // https://wasp-lang.dev/docs/guides/email-auth
    },
    onAuthFailedRedirectTo: "/login",
  }
}

. . .
```

Remove the existing SQLite migrations and reset the development environment by running `wasp clean`:

```bash
rm -r migrations/
wasp clean
```

Now, rerun the migrations against the PostgreSQL database. Wasp will connect using the details found in the `.env.server` file:

```bash
wasp db migrate-dev
```

Once the migration is complete, you can restart the development server to confirm that everything still functions as expected with PostgreSQL:

```bash
wasp start
```

Again, visit `http://localhost:3000` in your web browser to access the frontend and `http://localhost:3001` to connect to the server process.

Press <kbd>CTRL</kbd>-<kbd>C</kbd> to stop the development server when you are finished.

## Create a Dockerfile

To deploy Wasp to Koyeb, we'll need to build two container images, one with the API backend and another for the static files that serve as the frontend.

Wasp includes a `wasp dockerfile` command that generates a `Dockerfile` automatically that can be used to package build artifacts into a container image. Unfortunately, this process requires you to build the project before you can use the `Dockerfile` and we do not want to store our build output in version control.

Koyeb can build container images from a `Dockerfile` during the deployment process, so we will create our own `Dockerfile` based on the generated one that performs the build as a separate stage and then copies the artifacts to a production images.

Create a `Dockerfile` in the project root directory with the following contents:

```dockerfile
FROM node:20 AS base

# Build the project to generate the .wasp/build output
FROM base AS wasp-builder
WORKDIR /wasp
ADD . .
RUN curl -sSL https://get.wasp-lang.dev/installer.sh | sh
RUN /root/.local/bin/wasp build

# Build the server
FROM base AS server-builder
RUN apt update && apt install --yes build-essential python3 libtool autoconf automake && rm -rf /var/lib/apt/lists/*
WORKDIR /app
COPY --from=wasp-builder /wasp/.wasp/build/src ./src
COPY --from=wasp-builder /wasp/.wasp/build/package.json .
COPY --from=wasp-builder /wasp/.wasp/build/package-lock.json .
COPY --from=wasp-builder /wasp/.wasp/build/server .wasp/build/server
COPY --from=wasp-builder /wasp/.wasp/build/sdk .wasp/out/sdk
# Install npm packages, resulting in node_modules/.
RUN npm install && cd .wasp/build/server && npm install
COPY --from=wasp-builder /wasp/.wasp/build/db/schema.prisma .wasp/build/db/
RUN cd .wasp/build/server && npx prisma generate --schema='../db/schema.prisma'
# Building the server should come after Prisma generation.
RUN cd .wasp/build/server && npm run bundle

# Build the web app
FROM wasp-builder AS web-app-builder
ARG REACT_APP_API_URL
ENV REACT_APP_API_URL=$REACT_APP_API_URL
RUN npm ci
WORKDIR /wasp/.wasp/build/web-app
RUN npm ci && REACT_APP_API_URL=$REACT_APP_API_URL npm run build

# Run the server component
FROM base AS server-production
RUN apt update && apt install --yes python3 && rm -rf /var/lib/apt/lists/*
ENV NODE_ENV production
WORKDIR /app
COPY --from=server-builder /app/node_modules ./node_modules
COPY --from=server-builder /app/.wasp/out/sdk .wasp/out/sdk
COPY --from=server-builder /app/.wasp/build/server/node_modules .wasp/build/server/node_modules
COPY --from=server-builder /app/.wasp/build/server/bundle .wasp/build/server/bundle
COPY --from=server-builder /app/.wasp/build/server/package*.json .wasp/build/server/
COPY --from=server-builder /app/.wasp/build/server/scripts .wasp/build/server/scripts
COPY --from=wasp-builder /wasp/.wasp/build/db/ .wasp/build/db/
EXPOSE ${PORT}
WORKDIR /app/.wasp/build/server
ENTRYPOINT ["npm", "run", "start-production"]

# Run the web-app
FROM joseluisq/static-web-server AS web-app-production
ARG PORT
ENV SERVER_PORT=$PORT
COPY --from=web-app-builder /wasp/.wasp/build/web-app/build /public
```

This `Dockerfile` uses a [multi-stage build](https://docs.docker.com/build/building/multi-stage/) to perform various steps in different contexts. Let's take a look at the stages it defines and what they do:

- `wasp-builder`: This stage installs Wasp and runs the build process to generate the build artifacts. Parts of the output produced by this command will be copied over to subsequent stages.
- `server-builder`: This stage builds the Wasp backend code. It begins by installing some system-level dependencies and then copying over the components the server requires from the `wasp-builder` stage. It runs two separate `npm install` commands to install all of the project dependencies, generates the database schema, and then bundles the server project files.
- `web-app-builder`: This stage builds the front end web app. Because the generated files are static, we need to pass in the URL where the backend will be deployed as `REACT_APP_API_URL` during this process. Again, we perform two `npm install` commands (one for the larger project and one for the front end specifically) and build the web app project.
- `server-production`: This stage runs the server process. It installs some system-level runtime dependencies and then copies all of the required build artifacts from the `server-builder` and `wasp-builder` stages. It then runs the server process in production mode.
- `web-app-production`: This stage uses a static web server to serve the web app files generated by the `web-app-builder` stage.

Using this `Dockerfile`, we can build runnable container images for our project by building the `server-production` and `web-app-production` targets. These will contain everything we need to run our application in production.

## Push the project to GitHub

We now have everything we need to build and run our Wasp application in production. Next we need to commit our changes to git and push them to a GitHub repository.

When we initialized a new project, Wasp automatically generated an appropriate `.gitignore` file. Initialize a new git repository in the project root directory by typing:

```bash
git init
```

Once you're ready, add the project files to the staging area and commit them. [Create a new GitHub repository](https://github.com/new) and then run the following commands to commit and push changes to your GitHub repository:

```bash /<YOUR_GITHUB_USERNAME>/ /<YOUR_REPOSITORY_NAME>/
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
```

**Note:** Make sure to replace `<YOUR_GITHUB_USERNAME>` and `<YOUR_REPOSITORY_NAME>` with your GitHub username and repository name.

## Deploy the Wasp backend service to Koyeb

Now that the project code is on GitHub, we can deploy our components to Koyeb. We will start by deploying the server backend.

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

1. Select **GitHub** as the deployment method.
2. Select your Wasp project repository repository. Alternatively, you can enter our public [Wasp example repository](https://github.com/koyeb/example-wasp) into the **Public GitHub repository** field at the bottom of the page: `https://github.com/koyeb/example-wasp`.
3. In the **Builder** section, select **Dockerfile**. Click the **Override** toggle associated with **Target** and enter `server-production` in the field.
4. In the **App and Service names** section at the bottom, choose a name for your App and Service. Your App name will be a component of the public URL for your Service, using the following format: `https://<YOUR_APP_NAME>-<YOUR_KOYEB_ORG>.koyeb.app`.
5. In the **Exposed ports** section, change the **Path** for the configured port from `/` to `/api`.
6. In the **Environment variables** section, click **Bulk edit** to enter multiple environment variables at once. In the text box that appears, paste the following:

   ```
   DATABASE_URL=
   WASP_SERVER_URL=
   WASP_WEB_CLIENT_URL=
   JWT_SECRET=
   ```

   Set the variable values to reference your own information as follows:

   - `DATABASE_URL`: Use the value you from your `.env.server` file. This should be the PostgreSQL connection string with `?ssl_mode=require` appended to the end.
   - `WASP_SERVER_URL`: This is the URL where the server backend will be deployed, including the `/api` path. Set it using the following format: `https://<YOUR_APP_NAME>-<YOUR_KOYEB_ORG>.koyeb.app/api`.
   - `WASP_WEB_CLIENT_URL`: This is the URL where the web frontend will be deployed. We will deploy the web frontend to the web root (`/`), so fill this in using the following format: `https://<YOUR_APP_NAME>-<YOUR_KOYEB_ORG>.koyeb.app`.
   - `JWT_SECRET`: This is the JSON web token (JWT) used during authentication. Set this to a randomly generated string. You can generate an appropriate string by typing `openssl rand -base64 24` in your terminal.

7. Click **Deploy**.

Koyeb will pull the GitHub repository and build the `server-production` target of the `Dockerfile` within.

Once the deployment is healthy, visit your Koyeb Service's subdomain (you can find this on your Service's detail page). It will have the following format:

```
https://<YOUR_APP_NAME>-<KOYEB_ORG_NAME>.koyeb.app/api
```

You will see the "hello world" message from the server backend.

## Deploy the Wasp web app to Koyeb

With the backend service deployed, we can now create a new Service for the web application.

On the **Apps** tab of the [Koyeb control panel](https://app.koyeb.com), click on the Wasp server backend App. In the upper-right corner, click **Create Service** to create a new Service within the same application domain.

1. Select **GitHub** as the deployment method.
2. Select your Wasp project repository repository. Alternatively, you can enter our public [Wasp example repository](https://github.com/koyeb/example-wasp) into the **Public GitHub repository** field at the bottom of the page: `https://github.com/koyeb/example-wasp`.
3. In the **Builder** section, select **Dockerfile**. Click the **Override** toggle associated with **Target** and enter `web-app-production` in the field.
4. In the **Environment variables** section, click **Add variable** to add the following variable:

   - `REACT_APP_API_URL`: Set this to the URL for your backend service. This should be the same value you used for `WASP_SERVER_URL` in the backend configuration. It will have the following format: `https://<YOUR_APP_NAME>-<YOUR_KOYEB_ORG>.koyeb.app/api`.

5. Click **Deploy**.

Koyeb will pull the GitHub repository and build the `web-app-production` target of the `Dockerfile` within.

Once the deployment is healthy, visit the web application's Koyeb subdomain (you can find this on your Service's detail page). It will have the following format:

```
https://<YOUR_APP_NAME>-<KOYEB_ORG_NAME>.koyeb.app/
```

As before, you will be redirected to the application's login page. Click to link to sign up to create a new account. After authenticating, you will be able to access the todo list functionality as before.

## Conclusion

In this guide, we demonstrated how to build and deploy a Wasp application to Koyeb. We started with one of Wasp's templates to create a working, full-stack web application backed by a database. We migrated the application's configuration from a local SQLite database to an external PostgreSQL database to prepare for deployment. Afterwards, we created a multi-stage `Dockerfile` to build and configure our various application layers. Finally, we deployed the backend and web app to Koyeb by targeting different stages in the `Dockerfile`.

This tutorial covers the basics of how to manage a Wasp project and deploy to a production environment. As you continue to develop your projects, be sure to check out the [Wasp documentation](https://wasp-lang.dev/docs) to learn how to integrate new features, work with the data model, and leverage the development framework to make your life easier.


Learn how to build and deploy applications written with Wasp, a Rails-like framework for React, Node.js, and Prisma.

Using Wasp to Build Full-Stack Web Applications on Koyeb


## Introduction

[Directus](https://directus.io/) is an open data platform built to serve as a headless CMS, API, or Backend-as-a-Service (BaaS) for other applications. It is designed to make data accessible to people of all technical levels and to make it easy to build data-centric applications. Directus is extensible and can be integrated with many different frontend technologies to create stable, well-structured development and user experiences.

In this tutorial, we will show how to deploy Directus to Koyeb to enable you to build your own data backend. To ensure that our deployment is both scalable and resilient, we will configure Directus to use a number of accompanying components and services. We will deploy an external PostgreSQL database for long-term data persistence, an S3-compatible object storage bucket for storing uploads and images, and a Redis database for caching and to help our application stay in sync even when scaled to multiple instances.

You can deploy the application from this guide with [our Directus One-Click app](https://www.koyeb.com/deploy/directus) or by clicking the [Deploy to Koyeb button](/docs/build-and-deploy/deploy-to-koyeb-button) below:

[![Deploy to Koyeb](https://www.koyeb.com/static/images/deploy/button.svg)](https://app.koyeb.com/deploy?name=directus&type=docker&image=directus%2Fdirectus&instance_type=small&env%5BADMIN_EMAIL%5D=CHANGE_ME&env%5BADMIN_PASSWORD%5D=CHANGE_ME&env%5BCACHE_AUTO_PURGE%5D=true&env%5BCACHE_ENABLED%5D=true&env%5BCACHE_STORE%5D=redis&env%5BDB_CLIENT%5D=pg&env%5BDB_CONNECTION_STRING%5D=CHANGE_ME&env%5BKEY%5D=CHANGE_ME&env%5BPUBLIC_URL%5D=https://{{KOYEB_PUBLIC_DOMAIN}}&env%5BREDIS%5D=CHANGE_ME&env%5BSECRET%5D=CHANGE_ME&env%5BSTORAGE_S3_BUCKET%5D=CHANGE_ME&env%5BSTORAGE_S3_DRIVER%5D=s3&env%5BSTORAGE_S3_ENDPOINT%5D=CHANGE_ME&env%5BSTORAGE_S3_KEY%5D=CHANGE_ME&env%5BSTORAGE_S3_REGION%5D=CHANGE_ME&env%5BSTORAGE_S3_SECRET%5D=CHANGE_ME&env%5BSTORAGE_LOCATIONS%5D=s3&env%5BSYNCHRONIZATION_STORE%5D=redis&ports=8055%3Bhttp%3B%2F)

Be sure to modify all of the environment variables values set to `CHANGE_ME` to reflect your own data. You can consult the information in this guide if you need additional information.

## Requirements

To successfully follow and complete this guide, you need:

- A [Koyeb account](https://app.koyeb.com) to provision the PostgreSQL database and the Directus application.
- A [Backblaze B2](https://www.backblaze.com/cloud-storage) account to create an S3-compatible object storage bucket.
- An [Aiven Redis instance](https://aiven.io/redis) to cache data and synchronize between Directus instances. This is optional if you only plan on running a single Directus instance, but helps with performance and reliability.

## Steps

To complete this guide and deploy Directus, you'll need to follow these steps:

1. [Provision a PostgreSQL database on Koyeb](#provision-a-postgre-sql-database-on-koyeb)
2. [Provision a Backblaze B2 object storage bucket](#provision-a-backblaze-b2-object-storage-bucket)
3. [Provision a Redis instance on Aiven (Optional)](<#provision-a-redis-instance-on-aiven-(optional)>)
4. [Deploy Directus to Koyeb](#deploy-directus-to-koyeb)

## Provision a PostgreSQL database on Koyeb

Before we can deploy Directus, we need to provision a PostgreSQL database that we can use to persist application data including data collections, user data, and API configuration. We will use [Koyeb's PostgreSQL service](https://www.koyeb.com/docs/databases) which includes a free tier that we can use to get started.

To deploy a new PostgreSQL database, on the **Overview** tab of the [Koyeb control panel](https://app.koyeb.com/), click **Create Database Service**. Choose a name for the service and choose the region closest to you or your users.

Once the database is provisioned, click on the `.env` option of the **Connection Details** tab. Click the **copy icon** to save the connection details for later.

## Provision a Backblaze B2 object storage bucket

By default, Directus will store uploads and other file objects on the local filesystem where the application is running. In a serverless environment, this storage is ephemeral and would be lost when redeploying or reconfiguring the application. To avoid this, we will configure Directus to store these objects in an external object storage bucket. We will use Backblaze B2 for this.

To create an object storage bucket for Directus, log into your [Backblaze account](https://secure.backblaze.com/user_signin.htm) and follow these steps:

1. In the **B2 Cloud Storage** section on the left side of the dashboard, click **Buckets**.
2. Click **Create a Bucket** to begin configuring a new bucket.
3. Choose a name for the bucket. This must be globally unique, so choose a name not likely to be used by another user.
4. Set the bucket privacy to **Private**.
5. Use the provided defaults for the rest of the settings.
6. Click **Create a Bucket** to create the new bucket.

Copy and save the following information about your new bucket. You'll need it later to configure Directus:

| Backblaze B2 item | Example value                       |
| ----------------- | ----------------------------------- |
| Bucket name       | `some-bucket-name`                  |
| Endpoint          | `s3.eu-central-003.backblazeb2.com` |

Now that you have a bucket, you need to create API credentials so that Directus can authenticate to Backblaze as well as upload and manage objects:

1. In the **Account** section on the left side of the dashboard, click **Application Keys**.
2. Under **Your Application Keys**, click **Add a New Application Key** to begin configuring a new key.
3. Select a name for your key to help you identify it more easily.
4. Select the bucket you just created in the **Allow access to Bucket(s)** drop-down menu.
5. Select **Read and Write** as the access type.
6. Leave the remaining fields blank to accept the default policies.
7. Click **Create New Key** to generate the new key to manage your bucket.

Copy and save the following information related to your new API key. You'll need it to properly authenticate to your Backblaze account and perform object operations:

| Backblaze B2 item | Example value                     |
| ----------------- | --------------------------------- |
| `keyID`           | `008c587cb98cb3d0000000003`       |
| `applicationKey`  | `K002cbYLV/CkW/x+28zsqmpbIAtdzMM` |

## Provision a Redis instance on Aiven (Optional)

If you plan on scaling to multiple Directus instances, or if performance is an important factor, you can optionally configure a Redis database for caching and state synchronization. For this, we will use [Aiven Redis](https://aiven.io/redis).

To begin, [log in to your Aiven account](https://console.aiven.io/login) and follow these steps:

1. In the upper-right corner, click **Create service**.
2. On the service selection page, click **Redis**.
3. Select **Free plan** to use a free Aiven service.
4. Select the region closest to where you plan to run Directus.
5. Choose a name for the service or confirm the default choice.
6. Click **Create free service** to initialize the new Redis store.

Once the service is available, click the **copy icon** associated with the **Service URI** to save the connection details for later.

## Deploy Directus to Koyeb

Now that we have the connection details for the PostgreSQL database, object storage bucket, and Redis instance, we can deploy Directus to Koyeb.

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

1. Select **Docker** as the deployment method.
2. Set the **Docker image** to `docker.io/directus/directus`. Optionally, append an [image tag](https://hub.docker.com/r/directus/directus/tags) if you'd like to deploy a specific version.
3. In the **Environment variables** section, click **Bulk edit** to enter multiple environment variables at once. In the text box that appears, paste the following:

   ```
   KEY=
   SECRET=
   DB_CLIENT="pg"
   DB_CONNECTION_STRING=
   STORAGE_LOCATIONS="s3"
   STORAGE_S3_DRIVER="s3"
   STORAGE_S3_KEY=
   STORAGE_S3_SECRET=
   STORAGE_S3_BUCKET=
   STORAGE_S3_ENDPOINT=
   STORAGE_S3_REGION=
   REDIS=
   CACHE_ENABLED="true"
   CACHE_AUTO_PURGE="true"
   CACHE_STORE="redis"
   SYNCHRONIZATION_STORE="redis"
   PUBLIC_URL=https://{{ KOYEB_PUBLIC_DOMAIN }}
   ADMIN_EMAIL=
   ADMIN_PASSWORD=
   ```

   Set the variable values to reference your own information as follows:

   - `KEY`: A unique string that serves as an identifier for the current project. Set to a random number (for example, generated by `openssl rand -base64 24`).
   - `SECRET`: A unique string used to sign JSON web tokens for authentication. Set to a random number (for example, generated by `openssl rand -base64 24`).
   - `DB_CLIENT`: Set to `pg` to indicate a PostgreSQL database.
   - `DB_CONNECTION_STRING`: Set to your PostgreSQL connection string, with `?sslmode=require` appended to the end.
   - `STORAGE_LOCATIONS`: A name for the storage location to be configured. This will be used as part of the other variables used to configure it. Use `s3` here.
   - `STORAGE_S3_DRIVER`: The driver to use for the storage location. Set this to `s3`.
   - `STORAGE_S3_KEY`: The API key ID for authenticating to Backblaze.
   - `STORAGE_S3_SECRET`: The API key secret for authenticating to Backblaze.
   - `STORAGE_S3_BUCKET`: The name of your Backblaze B2 bucket.
   - `STORAGE_S3_ENDPOINT`: The Backblaze B2 endpoint URL. This should look something like `s3.eu-central-003.backblazeb2.com`.
   - `STORAGE_S3_REGION`: The name of the region where your Backblaze B2 bucket can be accessed. This is part of the endpoint URL. For the above endpoint, the region would be `eu-central-003`.
   - `REDIS`: The connection string for the Redis store. If you do not plan on running multiple Directus containers, you can optionally remove this requirement.
   - `CACHE_ENABLED`: Set to `true` to enable caching.
   - `CACHE_AUTO_PURGE`: Set to `true` to automatically purge cache when data is manipulated.
   - `CACHE_STORE`: Set to `redis` if using a Redis store. Set to `memory` if you are not using Redis.
   - `SYNCRHONIZATION_STORE`: Set to `redis` if using a Redis store. Set to `memory` if you are not using Redis.
   - `PUBLIC_URL`: Set to the public URL where the Directus service will run. Set to `https://{{ KOYEB_PUBLIC_DOMAIN }}`, which will substitute the correct domain on deployment.
   - `ADMIN_EMAIL`: Set to the email you wish to use to authenticate to the Directus admin account.
   - `ADMIN_PASSWORD`: Set to the password you wish to use to authenticate to the Directus admin account.

4. In the **Instance** section, select size **eco-micro** or larger. According to the [Directus documentation](https://docs.directus.io/self-hosted/docker-guide.html#requirements), the `eco-micro` Instance provides the minimum amount of resources required to run Directus. The `small` Instance includes the recommended resources.
5. If you wish to scale to more than one instance, adjust the scale values in the **Scaling** section.
6. In the **Exposed ports** section, change the **Port** value that the Service will run on to **8055**, the default port for Directus.
7. Click **Deploy**.

Koyeb will pull the Directus Docker image from Docker Hub and deploy it using the configuration you provided. During the deployment process, Directus will connect to the PostgreSQL database and initialize it to create the necessary data structures. It will perform similar preparatory steps to configure the object storage and Redis components.

Once the deployment is healthy, visit your Koyeb Service's subdomain (you can find this on your Service's detail page). It will have the following format:

```
https://<YOUR_APP_NAME>-<KOYEB_ORG_NAME>.koyeb.app
```

You will be redirected to the Directus login page. Enter the admin email address and password you provided as environment variables to authenticate.

## Conclusion

In this guide, we showed how to deploy and configure Directus on Koyeb to create a data backend for applications. We provisioned a PostgreSQL database to store persistent data, an object storage bucket to manage user uploads and other file-type objects, and a Redis instance to synchronize state between Directus instances and cache content. We deployed Directus using a configuration that'll allow us to scale out as needed in the future, providing our applications, sites, and clients with a reliable, easy-to-manage data backend.

We've left off on this tutorial with a functional Directus instance that you can integrate with your projects. To get started, consider walking through the [Directus Quickstart Guide](https://docs.directus.io/getting-started/quickstart.html) which shows how to create collections, configure data fields and items, and manage roles and permissions to make your data public. If you'd like to further customize your Directus service, take a look at the [Directus configuration options](https://docs.directus.io/self-hosted/config-options.html) in the documentation.


Learn how to deploy and configure Directus, an open-data platform that can be used as a Backend-as-a-Service, headless CMS, or API.

How to Deploy Directus as a Backend-as-a-Service (BaaS) on Koyeb

Run RAG-powered chatbots and your favorite cutting-edge AI tech across continents. No credit card required.

Deploy global AI workloads

In this tutorial, we show how to deploy an RAG chatbot built with the OpenAI embedding API, Replicate, pgvector, and the Koyeb Managed PostgreSQL service.

Build a Retrieval-Augmented Generation Chatbot using pgvector

Deploy your services on the best managed infrastructure in town and across continents. No credit card required.

Serverless and global PostgREST and HTMX

Learn how PostgREST and HTMX can help you build APIs quickly directly from database queries.

Use PostgREST and HTMX to Build RESTful APIs from PostgreSQL Databases

Run your Django applications on high-end infrastructure across continents in seconds. No credit card required.

Deploy Django globally

This tutorial showcases how to build your own URL shortener like tiny.url and bit.ly using Django REST Framework, Managed Postgres, and Koyeb.

Use Django REST Framework and Managed Postgres to Build an API

Deploy your fulll stack apps next to fully-managed serverless PostgreSQL databases on high-end infrastructure. No credit card required.

Serverless PostgreSQL with built-in pgvector

In this tutorial, we showcase how to deploy a FAQ search service built with Hugging Face's Inference API, pgvector, Koyeb's Managed Postgres. The optimized FAQ Search leverages sentence similarity searching to provide the most relevant results to a user's search terms.

Use pgvector and Hugging Face to Build an Optimized FAQ Search with Sentence Similarity

In this tutorial, we demonstrate how to deploy a Cal.com instance to Koyeb to handle meeting scheduling with Google calendar integration.

Deploy Cal.com on Koyeb to Manage Scheduling with Google Calendar

This guide shows how to deploy and configure DocuSeal, an open-source document managment platform, on Koyeb.

How to Set Up DocuSeal on Koyeb to Sign and Manage Digital Documents


## Introduction

[Authorizer](https://authorizer.dev/) is an open-source authentication and authorization platform for applications. It supports a number of different authentication methods including basic authentication, magic links, social logins, and multi-factor authentication. Using Authorizer, you can configure a secure authentication layer that can be used across various applications and servers, helping you provide account-based services to your applications without the headache.

In this guide, we will go over how to deploy and configure an Authorizer instance on [Koyeb](/) to provide authorization and authentication services for your other applications and services.

You can deploy and configure Authorizer as configured in this guide using the [Deploy to Koyeb](/docs/build-and-deploy/deploy-to-koyeb-button) button below:

[![Deploy to Koyeb](/static/images/deploy/button.svg)](https://app.koyeb.com/deploy?name=authorizer&type=docker&image=docker.io/lakhansamani/authorizer&env[PORT]=8000&env[DATABASE_TYPE]=postgres&env[DATABASE_URL]=CHANGE_ME&ports=8000;http;/)

**Note:** Remember to replace the value of the `DATABASE_URL` environment variable with the connection URL for your own PostgreSQL database.

## Requirements

To follow along with this guide, you will need to create accounts with the following services. Each of these services offers a free tier that you can use to get started:

- **[Koyeb](https://app.koyeb.com/):** We will use Koyeb to deploy, run, and scale our Authorizer instance.
- **[Neon](/docs/integrations/databases/neon):** We will use Neon to provision a PostgreSQL database to store and manage Authorizer's data including user information and authentication providers.
- **[Mailgun](https://www.mailgun.com/):** We will use Mailgun to send messages to users for verification, two factor authentication, and other authentication-related transactional emails.

## Steps

This guide will cover how to deploy Authorizer to Koyeb with the following steps:

1. [Create a PostgreSQL database with Neon](#create-a-postgre-sql-database-with-neon)
2. [Set up the Mailgun SMTP service](#set-up-the-mailgun-smtp-service)
3. [Deploy Authorizer to Koyeb](#deploy-authorizer-to-koyeb)
4. [Configure Authorizer](#configure-authorizer)
   - [Set up the admin account](#set-up-the-admin-account)
   - [Configure SMTP for email](#configure-smtp-for-email)
   - [Configure Authorizer features](#configure-authorizer-features)
   - [Test the sign up and authentication workflow](#test-the-sign-up-and-authentication-workflow)

## Create a PostgreSQL database with Neon

The Authorizer application stores its configuration data in a database.

To make it simpler to scale the application as well as ensure the availability of the data across restarts, we'll configure Authorizer to use an external database. Specifically, we will deploy Authorizer to a PostgreSQL database provisioned using Neon since they offer a free tier that is suitable for our purposes.

To create a new PostgreSQL database, log into your [Neon account](https://console.neon.tech/sign_in). In the Neon console, follow these steps to create a new PostgreSQL database:

1. In the **Projects** section, click the **Create a project** link on the bottom of the page.
2. Choose a name for your PostgreSQL database. We will use `authorizer` for this guide.
3. Leave the version to the default selection (15 at the time of writing).
4. Select the region to deploy your database. In this guide, we will select "Europe (Frankfurt)" to demonstrate deploying resources in Europe, but you should choose the region closest to your users.
5. Click the **Create project** button to begin provisioning your new database.

The following screen will show the connection details for your new database. Click on the copy icon associated with the `psql` connection string to copy it and save it to a safe place for later reference. We will use this value when we configure Authorizer so that it can connect to and authenticate with the database.

## Set up the Mailgun SMTP service

Next, you need to copy the SMTP information for your Mailgun account. Authorizer uses email to verify user accounts, send magic sign-in links, or provide additional security through multi-factor authentication.

To begin, log into your [Mailgun account](https://login.mailgun.com/login/). In the side navigation pane, open the **Sending** menu. Next, click the **Overview** sub-menu item.

Mailgun offers sandbox domains to test its functionality. These are useful, but restricted to sending emails only to previously authorised email addresses. We can use this to test the mail delivery with Authorizer for free. On the right sidebar of the Overview page, enter the email address you want to send test emails to in **email address** input field of the **Authorized Recipients** section and click the **Save Recipient** button.

Mailgun will send a verification email to the provided address. In the verification email, click the **I Agree** button to complete the authorisation process. If you refresh the page in Mailgun, you see that the target email address is now marked as verified.

From this same page, click the **Select** box associated with "SMTP" to see the information you need to send email using your Mailgun account. The information related to using SMTP with your Mailgun account will be displayed. Copy and save the following information:

| Mailgun SMTP info | Authorizer environment variable    | Example                                                          |
| ----------------- | ---------------------------------- | ---------------------------------------------------------------- |
| SMTP hostname     | `SMTP_HOST`                        | `smtp.mailgun.org`                                               |
| Port              | `SMTP_PORT`                        | 587                                                              |
| Username          | `SMTP_USERNAME` and `SENDER_EMAIL` | `postmaster@sandboxbac59f0e6dac45cdab38e53aee4e1363.mailgun.org` |
| Password          | `SMTP_PASSWORD`                    | `e627704d99111f00c7aedf3805961383-262b123e-66b6979f`             |

You will need to provide this information either as environment variables when deploying Authorizer or in the web-based administration page after the service is up and running.

## Deploy Authorizer to Koyeb

With the database connection string in hand, you can now deploy an Authorizer instance to Koyeb.

Start by logging into your [Koyeb account](https://app.koyeb.com/auth/signin). Follow these steps to deploy the default [Authorizer container image](https://hub.docker.com/r/lakhansamani/authorizer) to the platform:

1. On the **Overview** tab of the [Koyeb console](https://app.koyeb.com/), click **Create Web Service**.
2. Select **Docker** as your deployment method.
3. Set the **Docker image** to `docker.io/lakhansamani/authorizer`. Optionally, append an [image tag](https://hub.docker.com/r/lakhansamani/authorizer/tags) if you'd like to deploy a specific version.
4. In the **Environment variables** section, click the **Add variable** button to add the following variables and values:
   - `DATABASE_TYPE`: Set to `postgres`.
   - `DATABASE_URL`: Set to the connection URI you copied from Neon.
5. (Optional) If you'd like to configure your SMTP settings now, you can do so by setting the following additional variables:
   - `SMTP_HOST`: The name of the SMTP host (`smtp.mailgun.org`).
   - `SMTP_PORT`: The port of the SMTP service (587).
   - `SMTP_USERNAME`: The username to authenticate to your Mailgun account. This starts with `postmaster@` and ends in `.mailgun.org`
   - `SMTP_PASSWORD`: The password to authenticate to your Mailgun account.
   - `SENDER_EMAIL`: The sending email address. This should match the value set in the `SMTP_USERNAME`.
6. Choose a name for your App and Service and click **Deploy**.

Koyeb will pull the Authorizer container image from Docker Hub and use it to provision a new container. The Authorizer process will start up, connect to and initialize the database, and begin listening on the port specified in the configuration.

## Configure Authorizer

Once Authorizer is up and running, you can visit your Koyeb Service's subdomain (you can find this on your Service's page) to connect. It will have the following format:

```
https://<YOUR_APP_NAME>-<KOYEB_ORG_NAME>.koyeb.app
```

### Set up the admin account

When you visit Authorizer's URL, you will be redirected to the admin login page.

The first time you visit, you'll be asked to set an administrative password:

![Authorizer set admin password](/static/images/tutorials/authorizer/set_admin_password.png)

Choose a secure password and the click **Sign up** to continue.

You will be taken to the administration dashboard:

![Authorizer admin dashboard](/static/images/tutorials/authorizer/admin_dashboard.png)

From here, you can modify settings and continue configuring your instance.

### Configure SMTP for email

In the **Environment** section on the left side menu, click **Email Configurations** to see the settings currently configured for your SMTP service.

If you deployed Authorizer with the SMTP environment variables set, you should see those settings reflected in the form on this page:

![Authorizer email settings](/static/images/tutorials/authorizer/email_settings.png)

If you skipped adding your SMTP settings during the initial deployment, you can set those now. You should set the following fields:

- SMTP Host: The name of the SMTP host (`smtp.mailgun.org`).
- SMTP Port: The port of the SMTP service (587).
- SMTP Username: The username to authenticate to your Mailgun account. This starts with `postmaster@` and ends in `.mailgun.org`
- SMTP Password: The password to authenticate to your Mailgun account.
- From Email: The sending email address. This should match the value set in the "SMTP Username" field.

Click **Save** when you are finished to start using your new email configuration.

### Configure Authorizer features

Next, click the **Features** item in the **Environment** section of the left side menu.

Here, you can select the features that are enabled in your Authorizer instance. Depending on how you initially deployed your service, certain features may be enabled or disabled by default. All email-related features require valid SMTP settings in order to function correctly.

For our testing, we will enable the following features. We will toggle all other features off:

- Login Page
- Email Verification
- Basic Authentication
- Sign Up
- Strong Password
- Use Secure App Cookie
- Use Secure Admin Cookie

![Authorizer feature selection](/static/images/tutorials/authorizer/feature_selection.png)

Click **Save** when you are finished to modify the current configuration.

### Test the sign up and authentication workflow

To test the new settings, visit the built-in authentication page by appending `/app` to the end of Authenticator's base URL. It should look something like this:

```
https://<YOUR_APP_NAME>-<KOYEB_ORG_NAME>.koyeb.app/app
```

Assuming you've enabled only the features we outlined above, you should see a fairly conventional login page with an email field, a password field, a log in button, as well as links to sign up or to recover your account if you forgot your password:

![Authorizer initial login page](/static/images/tutorials/authorizer/initial_login_page.png)

Since we do not yet have a user account, click the **Sign up** link at the bottom of the page. You will be taken to an account creation page:

![Authorizer account creation page](/static/images/tutorials/authorizer/account_creation_page.png)

Create an account to test the authentication settings by inputting your email address and setting and confirming a secure password.

**Note:** Be sure to use the same email address you authorized in your Mailgun account. Your email will not be delivered otherwise.

Click **Sign up** when you are finished. Authorizer will show you a message indicating that it has sent an email to the provided address to confirm the registration:

![Authorizer verification sent](/static/images/tutorials/authorizer/verification.png)

Check the associated email address (be sure to also check the spam folder since we are sending from an untrustworthy sandbox domain) and click **Confirm Email** in email you receive to activate your account.

Revisit the login page to sign in with your new account. Fill in your email address and password and click **Log In**.

Upon successfully authenticating, you will see a short message confirming that the authentication was successful:

![Authorizer authentication successful](/static/images/tutorials/authorizer/authentication_successful.png)

This verifies that Authorizer is able to complete the sign up and login flows successfully. You can use these same flows with your application using one of the [SDKs provided by Authorizer](https://docs.authorizer.dev/getting-started#integrating-into-your-website).

## Conclusion

In this guide, we installed and configured the Authorizer authentication and authorization framework on Koyeb. We provisioned a PostgreSQL database with Neon to store the configuration used by the application and set up Mailgun to handle mail delivery for account-related events. We then deployed Authorizer and configured it to handle account lifecycle management like user sign ups, verification, logins and more.

By exploring the Authorizer administration interface, you can learn about the different features it offers and the integrations it supports. You can connect with social media networks to allow users to authenticate with their existing accounts through OAuth, set up webhooks to listen to authorization events to integrate deeply with your applications, and configure customized email templates to add your own design elements to account messaging. Visit the [Authorizer documentation](https://docs.authorizer.dev/) to learn more about what is possible and how to make it happen.


This tutorial demonstrates how to deploy and configure Authorizer, an authentication and authorization framework to Koyeb.

Deploy Authorizer to Handle User Authentication on Koyeb


## Introduction

[Grafana](https://grafana.com/) is a data monitoring and observability platform that allows you to collect and understand data from tools used throughout your organization. Grafana makes it easy to query data from many different sources, build graphs and dashboards to track changes in metrics, import and analyze logs, and send alerts when customizable thresholds are passed. With a large ecosystem of plugins and complementary systems, Grafana can be extended to work with whatever data is most important to you.

In this guide, we will go over how to set up a Grafana instance on [Koyeb](/) to monitor infrastructure health and essential production resources. We will deploy Grafana using the project's official [Docker image](https://hub.docker.com/r/grafana/grafana), backed by a PostgreSQL database.

You can deploy and preview Grafana as configured in this guide using the [Deploy to Koyeb](/docs/build-and-deploy/deploy-to-koyeb-button) button below:

[![Deploy to Koyeb](/static/images/deploy/button.svg)](https://app.koyeb.com/deploy?name=grafana&type=docker&image=docker.io/grafana/grafana&env[GF_SERVER_HTTP_PORT]=8000&env[GF_DATABASE_TYPE]=postgres&env[GF_DATABASE_URL]=REPLACE_ME&env[GF_DATABASE_SSL_MODE]=require&env[GF_INSTALL_PLUGINS]=grafana-github-datasource&ports=8000;http;/)

**Note:** Remember to replace the value of the `GF_DATABASE_URL` environment variables with the connection URL for your own database.

## Requirements

To follow along with this guide, you will need to create accounts with the following services. Each of these services offers a free tier that you can use to get started:

- **[Koyeb](https://app.koyeb.com/):** We will use Koyeb to deploy, run, and scale the Ghost process.
- **[Aiven](/docs/integrations/databases/aiven):** We will use Aiven to provision a PostgreSQL database to store and manage Grafana's configuration information.
- **[GitHub](https://github.com/):** We will use a GitHub account as a data source to demonstrate querying and visualizations in Grafana.

## Steps

This guide will cover how to deploy a Grafana instance to Koyeb through the following steps:

1. [Create a PostgreSQL database with Aiven](#create-a-postgre-sql-database-with-aiven)
2. [Deploy Grafana to Koyeb](#deploy-grafana-to-koyeb)
3. [Start using Grafana](#start-using-grafana)
   - [Setting up the admin account](#setting-up-the-admin-account)
   - [Creating a GitHub personal access token](#creating-a-git-hub-personal-access-token)
   - [Connecting Grafana with GitHub](#connecting-grafana-with-git-hub)
   - [Testing querying and visualizations with the GitHub data source](#testing-querying-and-visualizations-with-the-git-hub-data-source)

## Create a PostgreSQL database with Aiven

Before we deploy Grafana, we need to provision a database where it can store its data.

Grafana can use a number of different types of relational databases, including an embedded SQLite database by default. In this guide, we will use an external PostgreSQL database to decouple our data from the running service instance, allowing it to scale and redeploy without problems. We will use Aiven as our PostgreSQL provider since they have a free tier that is more than enough for our purposes.

To create a new PostgreSQL database, log into your [Aiven account](https://console.aiven.io/login). In the Aiven console, follow these steps to create a new PostgreSQL database:

1. Click the **Create service** button.
2. On the next screen, select **PostgreSQL**.
3. Select **Free plan** to get started using a free database.
4. Select the region to deploy your database. In this guide, we will select `aws-eu-west-3` to demonstrate deploying resources in Europe, but you should choose the region closest to your users.
5. Ensure that the `Free-1-5gb` plan is selected.
6. Choose a name for your PostgreSQL database. We will use `grafana-postgresql` for this guide.
7. Click the **Create free service** button to begin provisioning your new database.

The following screen will show the connection details for your new database. Click on the copy icon associated with the **Service URI** to copy the connection string and save it to a safe place for later reference. We will use this value when we configure Grafana so that it can connect to and authenticate with the database.

## Deploy Grafana to Koyeb

Now that you have the database connection string, you have everything you need to configure and deploy Grafana to Koyeb.

Begin by logging into your [Koyeb account](https://app.koyeb.com/auth/signin). Follow these steps to deploy the default [Grafana container image](https://hub.docker.com/r/grafana/grafana) to the platform:

1. On the **Overview** tab of the [Koyeb console](https://app.koyeb.com/), click **Create Web Service**.
2. Select **Docker** as your deployment method.
3. Set the **Docker image** to `docker.io/grafana/grafana`. Optionally append an [image tag](https://hub.docker.com/r/grafana/grafana/tags) if you'd like to choose a specific image variant.
4. In the **Environment variables** section, click **Add variable** to create the following variables:
   - `GF_SERVER_HTTP_PORT`: Set to 8000. This is the variable Grafana uses to specify the port to listen on.
   - `GF_DATABASE_TYPE`: Set to `postgres`.
   - `GF_DATABASE_URL`: Set to the connection URI you copied from Aiven.
   - `GF_DATABASE_SSL_MODE`: Set to `require` to force Grafana to connect to the database with encryption.
   - `GF_INSTALL_PLUGINS`: Set to `grafana-github-datasource` to install the GitHub data source.
5. Choose a name for your App and Service and click **Deploy**.

Koyeb will pull the Grafana container image from Docker Hub and use it to provision a new container. The Grafana process will start up, connect to and initialize the database, and begin listening on the port specified in the configuration.

## Start using Grafana

Once Grafana is up and running, you can visit your Koyeb Service's subdomain (you can find this on your Service's page) to connect. It will have the following format:

```
https://<YOUR_APP_NAME>-<KOYEB_ORG_NAME>.koyeb.app
```

### Setting up the admin account

You will be redirected to the Grafana login page:

![Grafana login page](/static/images/tutorials/grafana/grafana_login_page.png)

Enter `admin` for both the username and password to continue.

Next, you'll be asked to choose and confirm a new password for the admin account:

![Grafana change admin password](/static/images/tutorials/grafana/grafana_change_password.png)

Once you've provided a new password, you will be redirected to the default Grafana landing page:

![Grafana landing page](/static/images/tutorials/grafana/grafana_landing_page.png)

From here, you can modify settings and begin configuring your instance.

### Creating a GitHub personal access token

To test that Grafana can connect to and visualize data from a data source, we will connect our instance with a GitHub account.

To do this, you'll first need to create a GitHub personal access token to authenticate to your account.

On GitHub, visit the **Settings** and click the **Developer settings** tab on the left-hand sidebar. Next, open the **Personal access tokens** menu and click **Tokens (classic)**.

To create a new token, click the **Generate new token** button and select **Generate new token (classic)** from the drop down menu. Add a name for the new token and adjust the expiration date to your preference.

In the scopes selection, select the following items:

- `repo`
- `read:packages`
- `read:user`
- `user:email`

Click the **Generate token** button when you're done. Copy the generated token and save it to use for the next step.

### Connecting Grafana with GitHub

Now that we have a GitHub personal access token, we can configure the GitHub data source plugin for Grafana to visualize our data.

In your Grafana dashboard, open the side menu and select **Connections**. In the connections menu, view the **Data sources** page and then click the **Add data source** button:

![Grafana add data source](/static/images/tutorials/grafana/grafana_add_data_source.png)

On the next page, use the filter to search for "GitHub" and then select the plugin to continue:

![Grafana select GitHub source](/static/images/tutorials/grafana/grafana_select_github.png)

On the page that follows, name the connection so that you can identify this connection accurately. In the **Service Account Access** section, paste your GitHub personal access token into the **Access Token** field.

Click the **Save & test** button to validate the connection and save your configuration:

![Grafana save and test plugin](/static/images/tutorials/grafana/grafana_save_and_test.png)

If everything goes well, you should see a message that the data source is working.

### Testing querying and visualizations with the GitHub data source

Now that Grafana is connected to your GitHub account, you can query the data that the GitHub API exposes to visualize changes in repositories, organizations, and more. You can query information about your own repositories as well as any public repositories.

To get started, select **Dashboards** from the side menu, click the **New** button, and select **New Dashboard**:

![Grafana new dashboard](/static/images/tutorials/grafana/grafana_new_dashboard.png)

On the next page click the **Add visualization** button:

![Grafana add visualization](/static/images/tutorials/grafana/grafana_add_visualization.png)

Select your configured GitHub source as the data source:

![Grafana select data source](/static/images/tutorials/grafana/grafana_select_data_source.png)

Towards the bottom of the page, you can configure your query. For this example, we'll use the following values:

- Query Type: Pull Requests
- Owner: `koyeb`
- Repository: `koyeb-cli`
- Query: (blank)
- Time Field: `MergedAt`

Next, above the graph area, adjust the time frame from "Last 6 hours" to "This year so far":

![Grafana adjust time frame](/static/images/tutorials/grafana/grafana_adjust_time.png)

You should see the query run and the visualization populate.

Next, in the side bar, name the visualization "Koyeb CLI PRs" and click the **Apply** button:

![Grafana finalize visualization](/static/images/tutorials/grafana/grafana_finalize_visualization.png)

You should now see the new visualization on the dashboard:

![Grafana dashboard with visual](/static/images/tutorials/grafana/grafana_dashboard_with_visual.png)

Click the save icon in the top row to name your new dashboard. Click the **Save** button when you're finished:

![Grafana save dashboard](/static/images/tutorials/grafana/grafana_save_dashboard.png)

You've now connected your first data source and created a dashboard with some of the data it exposes. You can continue to visualize other data from the same repository, create dashboards for other GitHub data, and connect additional data sources.

**Note:** As you configure additional data sources, be sure to update the `GF_INSTALL_PLUGINS` environment variable to ensure that the plugins are automatically loaded on each deploy.

## Conclusion

In this guide, we installed and configured the Grafana observability platform on Koyeb. We used an Aiven PostgreSQL database to store our data and deploy using Grafana's Docker images to allow for easy updating and scaling.

Grafana is a powerful tool that can help you track the data from many areas of your organization. Just as importantly, it exposes the data in an approachable way so that users can create their own dashboards and gain insight about the information that's most important to them. As your data management gains complexity, Grafana's architecture and Koyeb's high availability features make it simple to scale out by deploying to new regions or adding additional instances.


This tutorial shows you how to deploy a Grafana instance on Koyeb and use it to visualize data from your GitHub repositories.