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


## Introduction

GitHub Actions are a great way to automate parts of your development and release workflows by running jobs in response to repository events. While native runners are available to execute these jobs on GitHub, often self-hosting your runners can provide a better price-performance ratio.

In our [guide on running GitHub runners on Koyeb](/tutorials/deploying-github-actions-self-hosted-runners-on-koyeb), we demonstrated how to configure Koyeb GitHub runners to execute GitHub Actions for an example application. This configuration lets us choose the appropriate performance profile for our tasks while saving money compared to the higher-tier native GitHub runners. One problem, however is that you don't necessarily need the runners operating at all times. When no jobs are being run, this needlessly increases costs without providing any value.

In this guide, we'll show you how to improve the Koyeb GitHub runner configuration by taking advantage of a companion project, [`koyeb-github-runner-scheduler`](https://github.com/koyeb/koyeb-github-runner-scheduler). Instead of deploying a continuously-running, high-performance GitHub runner on Koyeb directly, you can deploy a smaller scheduler app that dynamically spins up GitHub runners as necessary to complete jobs. The Koyeb Scheduler can be used to dispatch jobs for either an entire organization or for a specific repository. We'll be configuring our Scheduler to run for a specific repository in this demonstration.

## How the scheduler works

The scheduler is a small application that you can deploy on Koyeb to manage GitHub Actions job requests. It listens for jobs from GitHub and dispatches them to an appropriate runner on Koyeb. If a runner is not available, the scheduler provisions a new one and hands the job over once it is running. It automatically spins down the GitHub runners that have been idle for a configurable period of time.

This system allows you to run a small, always-on application and dynamically provision high-performance resources to execute your jobs when needed. You can configure the scheduler to receive requests from an entire organization or a single repository.

The basic order of operations that occurs when a GitHub Action, like a unit test, is triggered is as follows:

1. Your GitHub repository sends a webhook to the Koyeb Scheduler.
2. The Koyeb Scheduler checks if an appropriate runner is available to run the job. If one is not found, it initiates a new runner instance on Koyeb, tailored to your pre-defined size and geographic location requirements.
3. The Koyeb Scheduler dispatches the job to the matching GitHub runner.

After a pre-configured timeout, the Koyeb Scheduler shuts down the runner if no new jobs are initiated. This timeout is adjustable, offering you further control over cost and performance.

## Requirements

To follow along with this guide, you'll need:

- A [Koyeb account](https://app.koyeb.com/auth/signup) to deploy and run the Koyeb Scheduler.
- A [GitHub account](https://github.com/) to store your repositories and configure the GitHub Actions behavior.

## Steps

In this guide, we'll deploy the Koyeb Scheduler on Koyeb and configure GitHub to pass GitHub Actions jobs to it through the following steps:

1. [Clone the Koyeb GitHub runner scheduler demo application](#clone-the-koyeb-git-hub-runner-scheduler-demo-application)
2. [Create a GitHub personal access token](#create-a-git-hub-personal-access-token)
3. [Create a Koyeb personal access token](#create-a-koyeb-personal-access-token)
4. [Deploy the Koyeb GitHub Scheduler on Koyeb](#deploy-the-koyeb-git-hub-scheduler-on-koyeb)
5. [Configure a webhook for the GitHub repository](#configure-a-webhook-for-the-git-hub-repository)
6. [Test the Scheduler](#test-the-scheduler)

## Clone the Koyeb GitHub runner scheduler demo application

To get started, visit the [Koyeb GitHub runner scheduler demo application repository](https://github.com/koyeb/koyeb-github-runner-scheduler-demo) and clone it to your account.

The repository contains the same code from the [Koyeb GitHub runner demo application](https://github.com/koyeb/koyeb-github-runner-demo), but with a different GitHub Actions definition:

```yaml
name: Run unittests

on:
  push:
    branches:
      - '*'

jobs:
  run-tests-in-frankfurt:
    runs-on: koyeb-fra-small
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
      - name: Run tests
        run: |
          echo "Hello from a Small Koyeb Instance in Frankfurt!"
          python -m unittest
```

Rather than targeting a runner based on the `koyeb-runner` label, this action uses the format expected by the Scheduler:

```
koyeb-<REGION>-<INSTANCE_TYPE>
```

You can find the available values for [regions](/docs/reference/regions#core-regions) and [instance types](/docs/reference/instances#instance-types) in the Koyeb documentation. This allows the Scheduler to spin up different runners of various sizes in different locations depending on what the job requires.

## Create a GitHub personal access token

Before we can deploy the Koyeb Scheduler on Koyeb, we need to generate a new personal access token in GitHub.

On GitHub, click your user icon in the top right corner and go to [**Settings**](https://github.com/settings/profile). From there, go to [**Developer settings**](https://github.com/settings/apps) at the bottom of the left hand navigation menu and select [**Fine-grained tokens**](https://github.com/settings/tokens?type=beta) under the **Personal access tokens** section. Click [**Generate new token**](https://github.com/settings/personal-access-tokens/new) to access the token creation form.

Give the token a name and set the expiration date as you'd like. In the **Repository access** section, choose **Only select repositories** and then choose the project repository. In this tutorial, we focus on configuring the token for a single repository, but you can check the [`koyeb-github-runner-scheduler` repository](https://github.com/koyeb/koyeb-github-runner-scheduler#repository-or-organization-runner) for instructions on configuring for an entire organization.

In the **Permissions** section, expand the **Repository permissions** category. In the drop down menu for the **Administration** permission, select **Read and write**.

When you are finished, click **Generate token**. Copy the token value and store it in a safe location so we can use it later. This value cannot be retrieved later, so the token will have to be recreated if you lose it.

## Create a Koyeb personal access token

In order to spin up resources on your Koyeb, the Koyeb Scheduler needs a token that authorizes it to do so.

To get started, in the [Koyeb control panel](https://app.koyeb.com/), click your user icon in the top right corner and click [**Account settings**](https://app.koyeb.com/user/settings). Click the [**Personal Access Tokens**](https://app.koyeb.com/user/settings/api) item in the left-hand menu.

Give your new token a recognizable name and a useful description and then click **Create API Access Token**. Copy the token value and store it in a safe location so that we can use it in the next step. This value cannot be retrieved later, so the token will need to be recreated if you lose it.

## Deploy the Koyeb GitHub Scheduler on Koyeb

Now that we have the GitHub and Koyeb tokens, we can deploy the [Koyeb GitHub Scheduler](https://hub.docker.com/r/koyeb/github-runner-scheduler) to our account.

Click the "Deploy to Koyeb" button to configure the deployment. Be sure to alter the `GITHUB_TOKEN`, `KOYEB_TOKEN`, and `API_SECRET` environment variables to reflect your own values:

[![Deploy to Koyeb](/static/images/deploy/button.svg)](https://app.koyeb.com/deploy?name=github-runner-scheduler&type=docker&image=docker.io/koyeb/github-runner-scheduler&env[GITHUB_TOKEN]=CHANGE_ME&env[KOYEB_TOKEN]=CHANGE_ME&env[API_SECRET]=CHANGE_ME&env[MODE]=repository&env[DISABLE_DOCKER_DAEMON]=true&ports=8000;http;/)

If you'd like to deploy manually, on the **Overview** tab of the [Koyeb control panel](https://app.koyeb.com/), click **Create Web Service** to get started:

1. Select **Docker** as the deployment method.
2. Enter `github.io/koyeb/github-runner-scheduler` as the **Docker image**.
3. In the **Environment variables** section, create the following variables:
   - `GITHUB_TOKEN`: The personal access token you generated on GitHub.
   - `KOYEB_TOKEN`: The personal access token you generated on Koyeb.
   - `API_SECRET`: A random secret used to authenticate requests from GitHub webhooks. You will need to provide the same value when configuring the webhook on GitHub afterwards. A good way to generate this secret is by using the output of this command: `openssl rand -base64 30`.
   - `MODE`: Set this to `repository` since we're configuring the Scheduler for a single repository (if we were [configuring for an organization](https://github.com/koyeb/koyeb-github-runner-scheduler#repository-or-organization-runner), this would instead be set to `organization`).
     Additionally, you may also want to set the following optional variables depending on your needs:
   - `DISABLE_DOCKER_DAEMON`: Set this to `true` if you do not need to start a Docker daemon to run your jobs. Disabling this will reduce both the startup time and memory usage for your runners. If you're using the Python application from the previous guide, you can safely set this to `true`.
   - `RUNNERS_TTL`: You can optionally set this to the number of minutes after the most recent job that you want to wait before spinning down the GitHub runners. The default behavior is to wait 120 minutes (2 hours).
4. When you are ready, click **Deploy** to start up the Koyeb GitHub Scheduler on your account.

On the Service page, copy the **Public URL** for your Scheduler. You'll need it when configuring the webhook in the next step.

## Configure a webhook for the GitHub repository

Now that the Scheduler is up and running, you can finish the integration by configuring a webhook for the repository.

On your GitHub repository page, click the **Settings** tab and select **Webhooks**. Click **Add webhook** to begin the configuration.

Paste the public URL you copied from your Koyeb Scheduler into the **Payload URL** field. For the **Content type**, select `application/json`. In the **Secret** field, paste the same secret you used as the value for the `API_SECRET` environment variable when deploying the Scheduler.

In answer to the question **Which events would you like to trigger this webhook?**, choose **Let me select individual events.** In the list that follows:

- **De-select** the **Pushes** item
- **Select** the **Workflow jobs** item

Click **Add webhook** when you are finished.

## Test the Scheduler

Once you push your new changes to GitHub, the workflows should begin to execute using the new Scheduler system.

If you visit the runtime logs of the Koyeb GitHub Scheduler app in the Koyeb control panel, there should be messages indicating that a new job has been received from GitHub. They'll look for GitHub runners with the appropriate label and, finding none, will provision the new instance:

![Koyeb Scheduler event logs](/static/images/tutorials/koyeb-github-scheduler/koyeb-scheduler-logs.png)

If you go back to the main [Koyeb Apps list](https://app.koyeb.com/), a new GitHub runner Service should be in the process of deploying in Frankfurt:

![Koyeb new GitHub runner services](/static/images/tutorials/koyeb-github-scheduler/koyeb-new-runner-services.png)

Next, visit the **Actions** tab in your GitHub repository. You should see the test run history. If you click through the jobs, you'll a new job defined by your workflow:

![GitHub Actions test run results](/static/images/tutorials/koyeb-github-scheduler/github-actions-results.png)

The GitHub Actions were successfully executed by runners that the Scheduler dynamically provisioned. After the idle timeout is reached, the Scheduler will delete the runner, saving you money when it is not being used.

## Conclusion

In this guide, we improved a self-hosted GitHub runners set up by replacing our always-on GitHub runners with Koyeb Scheduler, a small application that can dynamically provision runners as needed. We configured the GitHub repository to send webhook messages to the Scheduler when GitHub Actions jobs occur and modified the workflow file to use the Scheduler label syntax.

By replacing the GitHub runner with the Scheduler, we are able to more easily control costs by only running instances when required by our GitHub jobs. By adjusting the time-to-live value for runners, we can confidently use higher performance instances without having to worry about paying for unnecessary usage.

To learn more about using the Koyeb Scheduler for your projects, check out the [Koyeb Scheduler repository on GitHub](https://github.com/koyeb/koyeb-github-runner-scheduler) and the [Scheduler image on Docker Hub](https://hub.docker.com/r/koyeb/github-runner-scheduler).


In this tutorial, we'll demonstrate how to configure the Koyeb GitHub Scheduler to dynamically provision GitHub Action runners on Koyeb.

Dynamically Start GitHub Action Runners on Koyeb

Enjoy blazing-fast deployments for your apps with Koyeb. No credit card required.

Turbocharge your Turso and Drizzle apps

In this tutorial, we show how to create a web app using a Turso SQLite database, the Drizzle ORM, and Express and run it on Koyeb.

Build and Run a Web App using Turso, Drizzle ORM, and Express on Koyeb

Run Uptime Kuma across multiple regions. No credit card required.

Global Uptime Kuma

In this tutorial, we show how to deploy Uptime Kuma to configure monitoring and status pages for your services.  We use Litestream to replicate all changes to our database to a remote object storage bucket for resiliancy.

Monitor your Websites and Apps using Uptime Kuma

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.

Deploy Grafana on Koyeb and Build a Dashboard to Visualize GitHub Data

This guide explains how to use the node-schedule library to email users the top Hacker News posts on a cron-like schedule.

How to Use Node-Schedule to Build and Deploy a Hacker News Aggregator


## Introduction

[Metabase](https://www.metabase.com/) is an open-source business intelligence platform that can connect with many different data sources to offer insight into your organization's key functions. Metabase makes it possible to integrate all of your data into a single platform and offer data exploration tools to teams with varying levels of technical expertise. You can create dashboards to visualize changes, create models to simplify access to information, and run saved or ad hoc queries to find the data that matters most to you.

In this guide, we will show you how to set up a new Metabase instance on [Koyeb](/) in order begin gathering insights from your organization's data. Metabase provides a [Docker image](https://hub.docker.com/r/metabase/metabase) that we can use to get the platform up and running without needing to manage its Java runtime and dependencies directly. We will use [Neon](https://neon.tech/) to provision a PostgreSQL database where Metabase can store information about users, questions, dashboards, and more. Deploying with an external database allows Metabase to scale horizontally and redeploy seamlessly without losing data.

## Account requirements

To follow along with this guide, you will need to create accounts with the following services:

- **[Koyeb](https://app.koyeb.com/):** We will use Koyeb to deploy, run, and scale the Metabase application.
- **[Neon](/docs/integrations/databases/neon):** We will use Neon as our database provider. We will spin up a PostgreSQL database to store data like users, dashboards, and saved questions.

We will go over how to set up the resources we need from each of the above providers throughout the guide.

## Create a PostgreSQL database with Neon

Before we can deploy Metabase, we need to provision a database where it can store its data. Metabase can use a number of different backing databases, including a local [H2 database](https://www.h2database.com/html/main.html). Since we want our data to persist across deployments and be available from any number of application instances, we will opt for an external PostgreSQL database provisioned on [Neon](https://neon.tech/).

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. Click the **Create a project** link.
2. On the next screen, choose a name for the new database. We'll use `metabase` for this guide.
3. Leave the version set at 15.
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. Since Metabase is written in Java, in the drop-down menu, select **Java**. Copy the [JDBC](https://en.wikipedia.org/wiki/Java_Database_Connectivity) connection URI displayed so that we can use it later when we configure Metabase. It should look similar to this:

```
jdbc:postgresql://<NEON_HOST_PREFIX>.neon.tech/neondb?ssl=require&user=<NEON_USER>&password=<DB_PASSWORD>
```

## Deploy Metabase to Koyeb

Now we have the database connection URI, we can deploy Metabase to Koyeb.

Begin by logging into your [Koyeb account](https://app.koyeb.com/auth/signin). Follow these steps to deploy Metabase 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/metabase/metabase`. If you'd prefer, append an [image tag](https://hub.docker.com/r/metabase/metabase/tags) to the value.
4. In the **Instance** selection, select **Medium** or larger. Metabase recommends [allocating at least 1GB memory to Metabase](https://discourse.metabase.com/t/what-are-metabase-minimum-resources/21470/2) and [an additional 1-2GB of memory outside of Java](https://www.metabase.com/docs/latest/troubleshooting-guide/running.html#metabase-fails-to-start-due-to-heap-space-outofmemoryerrors).
5. In the **Environment variables** section, click **Add variable** and create two new variables. Create a variable called `MB_DB_CONNECTION_URI` and paste the JDBC connection URI you copied from Neon as the value. Next, add a variable called `JAVA_OPTS` with a value of `-Xmx1g` to set the Java heap size to 1GB of memory.
6. In the **Exposed ports** section, change the existing entry to use port **3000**.
7. Choose a name for your App and Service and click **Deploy**.

Koyeb will pull the Metabase Docker image from Docker Hub and start a container based from it based on your configuration. The Metabase process will start up, connect to and initialize the database, and prepare for its first run.

## Start using Metabase

To access your new Metabase instance, visit your Koyeb Service's subdomain (you can find this on your Service's page). It will have the following format:

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

You will be greeted by the Metabase setup page:

![Metabase default landing page](/static/images/tutorials/metabase/metabase_default_landing_page.png)

Click **Let's get started** to begin initial account creation process.

On the next page, select your preferred language:

![Metabase select language](/static/images/tutorials/metabase/language_selection.png)

Click **Next** to continue.

Fill out the information for your new user account:

![Metabase user account information](/static/images/tutorials/metabase/user_information.png)

Click **Next** to move on.

The next section let's you select what type of data you want to connect with Metabase and enter the associated connection details:

![Metabase connect data source](/static/images/tutorials/metabase/connect_data.png)

For now, just click **I'll add my data later** link to continue.

Select whether you want to send anonymous usage data back to Metabase:

![Metabase usage data](/static/images/tutorials/metabase/usage_data.png)

Make your selection and click **Finish** to wrap up.

Before you continue, you'll have the option to sign up for the Metabase newsletter:

![Metabase newsletter](/static/images/tutorials/metabase/subscribe_to_newsletter.png)

Click **Subscribe** if you'd like updates. Click **Take me to Metabase** to access your new Metabase instance.

You will be taken to Metabase's primary dashboard:

![Metabase dashboard](/static/images/tutorials/metabase/metabase_dashboard.png)

Click on any of the sample "x-rays" to view different examples of how to use Metabase as applied to the included sample database:

![Metabase sample x-ray](/static/images/tutorials/metabase/metabase_sample_x-ray.png)

To see the sample database itself, click **Browse data** under the **DATA** heading in the side navigation bar.

You can add additional data sources at any time by clicking the **Add your own data** item in the sidebar.

## Conclusion

In this guide, we covered how to deploy Metabase to Koyeb with their default Docker container. We used a PostgreSQL database provisioned through Neon to store the platform's information about users, views, questions, and other data. This configuration allows us to easily update the application and scale out as our requirements change.

As you add different data sources to your Metabase instance, check in with the application logs on the Deployment page in the [Koyeb control panel](https://app.koyeb.com/) to make sure everything is running smoothly. If you need additional resources, you can easily scale out your Deployment to better serve your users.


This guide explains how to deploy Metabase, an open-source business intelligence and data visualization platform to Koyeb.

Deploy the Metabase Business Intelligence Platform to Koyeb


## Introduction

[Ghost](https://ghost.org/) is a modern open-source content management system (CMS) and blogging platform for publishing content, newsletters, and more. You can use Ghost to design and build your website, launch free or paid content services, manage user memberships, and track performance.

In this guide, we will go over how to set up a Ghost blog on [Koyeb](/) to launch a new site. We will deploy Ghost using the project's official [Docker image](https://hub.docker.com/_/ghost/), backed by a MySQL database. We will configure Ghost to use Cloudinary, a digital asset management platform, so that assets like images are accessible after redeploying or scaling out. We will also configure a transaction email provider so that Ghost can send out account-oriented emails to subscribers and other users of your service.

## Account 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 as our database provider. We need a MySQL database for Ghost to store post content, user information, and more.
- **[Cloudinary](https://cloudinary.com/):** Cloudinary is a digital asset management (DAM) platform that we will use to persistently host uploaded media like images and video.
- **[Mailgun](https://www.mailgun.com/):** We will use Mailgun to send transactional and bulk emails to users.

We will go over how to set up the resources we need from each of the above providers throughout the guide.

You can deploy and preview the Java application from this guide using the [Deploy to Koyeb](https://koyeb.com/docs/build-and-deploy/deploy-to-koyeb-button) button below:

[![Deploy to Koyeb](/static/images/deploy/button.svg)](https://app.koyeb.com/deploy?name=koyeb-ghost&type=git&repository=koyeb%2Fexample-ghost&branch=main&builder=dockerfile&env%5Burl%5D=REPLACE_ME&env%5Bdatabase__connection__host%5D=REPLACE_ME&env%5Bdatabase__connection__port%5D=REPLACE_ME&env%5Bdatabase__connection__user%5D=REPLACE_ME&env%5Bdatabase__connection__password%5D=REPLACE_ME&env%5Bmail__options__auth__user%5D=REPLACE_ME&env%5Bmail__options__auth__pass%5D=REPLACE_ME&env%5BCLOUDINARY_URL%5D=REPLACE_ME&ports=2368%3Bhttp%3B%2F)

**Note:** Be sure to set the environment variables to your own information according to the [deployment instructions](#deploy-ghost-to-koyeb). You can consult the [repository on GitHub](https://github.com/koyeb/example-ghost) to find out more about the example application that this guide uses.

## Create a MySQL database with Aiven

Before we can deploy Ghost, we need to provision a database where it can store its data. Ghost uses MySQL to store post content, account information, emails, sessions, and more.

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

1. Click the **Create service** button.
2. On the next screen, select **MySQL**.
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 MySQL database. We will use `ghost-mysql` 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. Copy down the following information to use later when you deploy Ghost:

- Host
- Port
- User
- Password

These values will be mapped to environment variables that Ghost reads like this:

| Aiven MySQL info | Ghost environment variable       | Example                                   |
| ---------------- | -------------------------------- | ----------------------------------------- |
| Host             | `database__connection__host`     | `ghost-mysql-account-fe75.aivencloud.com` |
| Port             | `database__connection__port`     | 16361                                     |
| User             | `database__connection__user`     | `avnadmin`                                |
| Password         | `database__connection__password` | `AVNS_XSxMGFOgWCrFHiyYFgm`                |

## Copy the Cloudinary environment variable

Next, you need to retrieve an API URL from your Cloudinary account. Ghost will use this to authenticate with Cloudinary to upload and optimize images and other assets used by your blog.

To find the URL, log into your [Cloudinary account](https://cloudinary.com/users/login). In the side navigation pane, select the **Programmable Media** view and then click **Dashboard**.

Next, click the copy icon associated with the **API Environment variable**. This will copy your Cloudinary URL needed to authenticate to your account to upload and retrieve media.

The copied value includes a `CLOUDINARY_URL=` prefix that would be useful for setting a local environment variable. When setting this on Koyeb, remember to not include that as part of the value.

| Cloudinary account info  | Ghost environment variable | Example                                                              |
| ------------------------ | -------------------------- | -------------------------------------------------------------------- |
| API Environment variable | `CLOUDINARY_URL`           | `cloudinary://362737766187248:oD-ldl09ZgKPK0AmGcAoDNb8Bmg@dyn2flngo` |

## Copy the Mailgun SMTP information

Next, you need to copy the SMTP information for your Mailgun account. Ghost uses this to send transactional and bulk email as part of its account management lifecycle and subscription services.

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

On the domain settings page, click on the **SMTP credentials** tab. Copy the **Login** value and save it for later. This will be the username we use to authenticate to Mailgun's SMTP service.

**Note:** The following step will reset your SMTP password. If you are currently using this for other purposes, you will need to update the password in those contexts.

Next, click the **Reset password** button. A message will appear confirming that your password has been reset. Click the copy icon on the message to copy the new password to your clipboard. Save this value for later.

| Mailgun SMTP info | Ghost environment variable  | Example                                                          |
| ----------------- | --------------------------- | ---------------------------------------------------------------- |
| Login             | `mail__options__auth__user` | `postmaster@sandboxbac59f0e6dac45cdab38e53aee4e1363.mailgun.org` |
| Password          | `mail__options__auth__pass` | `e627704d99111f00c7aedf3805961383-262b123e-66b6979f`             |

## Create a Dockerfile for Ghost

Now that we have the credentials for our deployment, we need to define how Ghost should run.

The [official Ghost Docker image](https://hub.docker.com/_/ghost) unfortunately does not include the [Cloudinary storage adapter](https://github.com/eexit/ghost-storage-cloudinary). It can only store pictures and other uploaded media to the local filesystem. Since we don't want our deployment tied to one machine's local filesystem, we need to modify the base image to include the adapter.

Luckily, the Cloudinary storage adapter includes [instructions for creating an image with the adapter added](https://github.com/eexit/ghost-storage-cloudinary#install-on-docker). We will use this as a basis for our own deployment.

On your local computer, create a new directory to hold your project files and navigate inside:

```bash
mkdir ghost-blog
cd ghost-blog
```

Here, create a new `Dockerfile` with the following contents:

```dockerfile
FROM ghost:5-alpine as cloudinary
RUN apk add g++ make python3
RUN su-exec node yarn add ghost-storage-cloudinary

FROM ghost:5-alpine
COPY --chown=node:node --from=cloudinary $GHOST_INSTALL/node_modules $GHOST_INSTALL/node_modules
COPY --chown=node:node --from=cloudinary $GHOST_INSTALL/node_modules/ghost-storage-cloudinary $GHOST_INSTALL/content/adapters/storage/ghost-storage-cloudinary
# Here, we use the Ghost CLI to set some pre-defined values.
RUN set -ex; \
    su-exec node ghost config storage.active ghost-storage-cloudinary; \
    su-exec node ghost config storage.ghost-storage-cloudinary.upload.use_filename true; \
    su-exec node ghost config storage.ghost-storage-cloudinary.upload.unique_filename false; \
    su-exec node ghost config storage.ghost-storage-cloudinary.upload.overwrite false; \
    su-exec node ghost config storage.ghost-storage-cloudinary.fetch.quality auto; \
    su-exec node ghost config storage.ghost-storage-cloudinary.fetch.cdn_subdomain true; \
    su-exec node ghost config mail.transport "SMTP"; \
    su-exec node ghost config mail.options.service "Mailgun";
```

The instructions here use the `ghost:5-alpine` image as a starting point for customization. The only changes that are introduced to the base image are to download and build the `ghost-storage-cloudinary` package and copy it to the location where Ghost expects to find storage adapters. After that, it uses the included [Ghost CLI](https://ghost.org/docs/ghost-cli/) to set some basic configuration options.

When you are finished, you can initialize a Git repository in the directory and add the `Dockerfile`. This file is all you need to deploy the customized Ghost image to Koyeb.

**Note:** Be sure to change `<YOUR_GITHUB_USERNAME>` and `<YOUR_REPOSITORY_NAME>` to match your own values in the commands below.

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

## Deploy Ghost to Koyeb

Now we have everything we need to deploy Ghost to Koyeb.

Begin by logging into your [Koyeb account](https://app.koyeb.com/auth/signin). Follow these steps to deploy your Ghost image to the platform:

1. On the **Overview** tab of the [Koyeb console](https://app.koyeb.com/), click **Create Web Service**.
2. Choose **GitHub** as the deployment method.
3. Select the GitHub repository with your Ghost `Dockerfile`. Alternatively, use the public [example Ghost repo](https://github.com/koyeb/example-ghost) in the **Public GitHub repository**: `https://github.com/koyeb/example-ghost`.
4. In the **Builder** section, select **Dockerfile**.
5. Towards the bottom, choose a name for your App and Service. When setting the `url` environment variable later, use the following format if you do not have a custom domain: `https://<YOUR_APP_NAME>-<KOYEB_ORG_NAME>.koyeb.app`.
6. In the **Environment variables** section, click the **Add variable** button to add the following variables:

| Variable name                    | Description                    | Example                                                              |
| -------------------------------- | ------------------------------ | -------------------------------------------------------------------- |
| `url`                            | Full base URL to access Ghost. | `https://<YOUR_APP_NAME>-<KOYEB_ORG_NAME>.koyeb.app`                 |
| `database__connection__host`     | Aiven MySQL database host      | `ghost-mysql-account-fe75.aivencloud.com`                            |
| `database__connection__port`     | Aiven MySQL database port      | `16361`                                                              |
| `database__connection__user`     | Aiven MySQL database user      | `avnadmin`                                                           |
| `database__connection__password` | Aiven MySQL database password  | `AVNS_XSxMGFOgWCrFHiyYFgm`                                           |
| `mail__options__auth__user`      | Mailgun SMTP login             | `postmaster@sandboxbac59f0e6dac45cdab38e53aee4e1363.mailgun.org`     |
| `mail__options__auth__pass`      | Mailgun SMTP password          | `e627704d99111f00c7aedf3805961383-262b123e-66b6979f`                 |
| `CLOUDINARY_URL`                 | Cloudinary API connection URL  | `cloudinary://362737766187248:oD-ldl09ZgKPK0AmGcAoDNb8Bmg@dyn2flngo` |

7. In the **Exposed ports** section, change the exposed port to **2368**.
8. Click the **Deploy** button.

Koyeb will pull the Ghost `Dockerfile` from GitHub repository and use it to build a Docker image. It will then provision a container based on the image to start Ghost. The Ghost process will start up, configuring the database and performing initialization routines before serving the page.

## Start using Ghost

To access your Ghost blog, visit your Koyeb Service's subdomain (you can find this on your Service's page). It will have the following format:

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

You will be able to see the default landing page:

![Ghost default landing page](/static/images/tutorials/ghost/ghost_default_landing_page.png)

You can verify that the Mailgun configuration is working properly by clicking the **Subscribe** button on your site:

![Ghost test subscription](/static/images/tutorials/ghost/ghost_subscribe.png)

If your SMTP settings are configured correctly, the sign up procedure will not hang and you will receive an email verifying the subscription.

To log into Ghost and begin configuring your blog, visit the `/ghost` route on your blog:

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

You will be asked to enter details about the site and will be able to create an admin account:

![Ghost blog admin creation page](/static/images/tutorials/ghost/ghost_admin_setup.png)

Once you have logged in, you can create a new post and include an image to test the Cloudinary integration:

![Ghost blog create post with image](/static/images/tutorials/ghost/ghost_post_with_image.png)

After publishing, if you click on the post and open the image in a new tab, the URL should be served from a Cloudinary URL instead of directly from your blog's domain:

![Image served from Cloudinary](/static/images/tutorials/ghost/cloudinary_blog_image.png)

Serving media from a Cloudinary URL means that you can redeploy or scale your blog without losing your assets.

## Conclusion

In this guide we covered how to deploy Ghost to Koyeb in a reliable and scalable way. We created a basic `Dockerfile` to configure Ghost's storage adapter to save media off disk, set up a remote MySQL database, and configured transactional and bulk email delivery for account management and user messaging.

Because our deployment is distributed and does not rely on local resources, it continues to work across redeployments and can scale easily. By offloading persistent data to remote databases and a digital asset management platform, you can manage the blog process and configuration separately from our data.


This guide explains how to deploy Ghost, a modern blogging platform, to Koyeb.

Deploy a Ghost Blog in Production to Koyeb


## Introduction

[Celery](https://github.com/celery/celery) is an open-source distributed task queue that focuses on real-time processing and task scheduling. It coordinates tasks through a backing message broker, typically [Redis](https://redis.io/) or [RabbitMQ](https://www.rabbitmq.com/), making it straightforward to scale as demand increases. While Celery is written in Python, its messaging protocols are not language specific, allowing for clients in any language.

In this guide, we will go over how to deploy a Celery worker on the [Koyeb](/) serverless platform using git-driven deployment. We will create a repository with Celery and its dependencies installed, deploy RabbitMQ to act as our backing message broker, and then connect our GitHub account to Koyeb to automatically deploy the Celery worker to the platform.

At the end of this guide, you should have a Celery worker deployed to Koyeb that you can automatically update by pushing changes to your GitHub account.

## Requirements

To follow along with this guide, you will need the following:

- Python 3 installed on your local machine
- A [Koyeb account](https://app.koyeb.com/) to deploy and run your Celery worker and RabbitMQ message broker
- A [GitHub account](https://github.com/) to store your application code and trigger deployments via repository changes

## Steps

This guide will cover how to deploy a Celery worker to Koyeb through the following steps:

1. [Create a Python Virtual Environment](#create-a-python-virtual-environment)
2. [Install Celery](#install-celery)
3. [Create a Basic Celery Application](#create-a-basic-celery-application)
4. [Push the Celery Project to GitHub](#push-the-celery-project-to-git-hub)
5. [Deploy RabbitMQ on Koyeb](#deploy-rabbit-mq-on-koyeb)
6. [Deploy the Celery Worker on Koyeb](#deploy-the-celery-worker-on-koyeb)
7. [Testing the Celery Worker](#testing-the-celery-worker)

## Create a Python Virtual Environment

To get started, we will create a Python virtual environment on our local machine to isolate our project's dependencies from the rest of the system packages. Python provides this functionality natively through the standard [`venv` module](https://docs.python.org/3/library/venv.html).

Start by creating a new directory to store our project files.

```shell
mkdir ~/celery-koyeb
```

Next, create the virtual environment within the project directory by typing:

```shell
python3 -m venv ~/celery-koyeb/venv
```

This will create a directory called `venv` within the `~/celery-koyeb` containing initialization scripts, copies of essential tools like `pip`, and links to the local Python interpreters.

To tell Python to use the virtual environment, activate it by sourcing the initialization script:

```shell
source ~/celery-koyeb/venv/bin/activate
```

Your shell prompt will change to reflect that the virtual environment is active for this session. Python will now use this directory structure in place of the system's standard Python file locations, allowing us to isolate dependencies.

## Install Celery

Next, we need to install Celery within the virtual environment using `pip`, the Python package manager:

```shell
pip install celery
```

Python will download Celery and its dependencies and install them within the virtual environment filesystem.

Along with the Python modules, the installation also includes a small wrapper script called `celery` that lets you interact with it from the command line. Use the command now to verify that the installation was successful:

```shell
celery --version
```

The command should show the version as expected. The exact version returned does not matter, so long as the command returns successfully:

```
5.2.7 (dawn-chorus)
```

With Celery installed, record the project's dependencies by typing:

```shell
pip freeze > ~/celery-koyeb/requirements.txt
```

## Create a Basic Celery Application

Next, we'll create a basic Celery application in our project directory.

Create a file called `tasks.py` within the `~/celery-koyeb` directory with the following content inside:

```python
import os
from celery import Celery


# Fail if the `BROKER_HOST` environment variable is not defined
BROKER_HOST = os.environ.get('BROKER_HOST', None)
if BROKER_HOST is None:
    raise Exception("BROKER_HOST environmental variable is not defined")
broker_url = 'pyamqp://guest@' + BROKER_HOST + '//'

app = Celery('tasks', broker=broker_url, backend='rpc://')

@app.task
def add(x, y):
    return x + y
```

Let's talk a bit about what is happening in the code above.

After importing the `os` module and the `Celery` class, the code above sets the location of the backing RabbitMQ message broker based on the value of the `BROKER_HOST` environment variable. If this variable is not set, we will error out to avoid accidentally deploying misconfigured instances.

Next, we create an instance of the `Celery` class called `app`. We pass `tasks` as the name of the main module and include the broker and backend configuration to allow Celery to connect to the RabbitMQ instance indicated by the environment variable mentioned earlier.

Finally, we create a function with the `@app.task` decorator to add it to Celery's task registry. Our function adds two numbers together and returns the result.

Save and close the file when you are finished.

## Push the Celery Project to GitHub

Next, we will commit our project to `git` and push our changes to our GitHub account.

In your project directory, initialize a `git` repository to get started:

```shell
cd ~/celery-koyeb
git init
```

Add the `tasks.py` application and the `requirements.txt` file to the staging area. You can also create a minimal `.gitignore` file to make sure your virtual environment does not accidentally get committed. Commit the changes when you are done:

```shell
echo 'venv' >> .gitignore
git add tasks.py requirements.txt .gitignore
git commit -m 'Initial commit'
```

Create a [new repository](https://github.com/new) within your GitHub account. This can be either public or private. Add the GitHub repository address as the `origin` of your project and push your changes to the repository:

```shell
git remote add origin git@github.com:<YOUR_GITHUB_USERNAME>/<YOUR_GITHUB_REPOSITORY>.git
git branch -M main
git push -u origin main
```

If you refresh the GitHub repository page in your browser, your project files will appear.

## Deploy RabbitMQ on Koyeb

Before we deploy our Celery worker, we need to deploy a RabbitMQ instance for Celery to use as a message broker. We will use the [official RabbitMQ image on DockerHub](https://hub.docker.com/_/rabbitmq) for this purpose.

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

1. Select **Docker** as the deployment method.
2. In the **Docker image** field, enter `docker.io/rabbitmq`.
3. In the **Exposed ports** section, change the port number to 5672 and deselect the **Public** option. This will allow other services within this application (like our Celery application) to access the message broker using its service name without exposing the service to the internet.
4. Click the **Deploy** button.

Your new application will be created and the RabbitMQ service will begin to deploy within it. In a few minutes, the RabbitMQ container will finish deploying to Koyeb and the service will be marked as healthy.

Before moving on, copy the **Private domain** of your RabbitMQ deployment. We will need this later as we configure the Celery worker service.

## Deploy the Celery Worker on Koyeb

Now that the RabbitMQ service is deployed, we can deploy the Celery application from our GitHub repository.

In the **Apps** tab of the [Koyeb control panel](https://app.koyeb.com/), click the app that contains your RabbitMQ service. Click the **Create Service** button to deploy a new service to the app alongside the RabbitMQ container:

1. Choose **GitHub** as the deployment method.
2. Select the repository for your Celery application from the list.
3. In the **Service type** section, select **Worker**.
4. In the **Builder** section, click the **Override** toggle associated with the **Run command** and enter `celery --app=tasks.app worker` in the field.
5. In the **Environment variables** section, create a new variable called `BROKER_HOST` to tell the Celery worker where to find the RabbitMQ instance. Set the value to the **Private domain** you copied from the RabbitMQ service. It will follow this format: `<YOUR_SERVICE_NAME>.<YOUR_APP_NAME>.koyeb`.
6. Click the **Deploy** button.

The Celery application will be pulled from your GitHub repository and deployed. In a few minutes, the Celery worker will begin running within the service and be available for work.

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

## Testing the Celery Worker

Unlike a web application, Celery does not have a web interface to easily show you that the deployment succeeded. We can, however, use Koyeb's built-in Console to test that the worker is running, able to connect with RabbitMQ, and can process tasks.

In the [Koyeb control panel](https://app.koyeb.com/), click the Celery service and then select the **Console** tab.

In the console window, start a `bash` session by typing:

```shell
/bin/bash
```

Next, source the environment configuration file so that Python can find the modules associated with our application:

```shell
source .profile.d/python.sh
```

Start a Python session so that we can interact with the Celery application:

```shell
python
```

First, import our `tasks` module:

```python
import tasks
```

Next, we can run the `add` function using [Celery's `delay` method](https://docs.celeryq.dev/en/stable/reference/celery.app.task.html#celery.app.task.Task.delay):

```python
results = tasks.add.delay(93, 80)
```

We can then use the `results` object to check on the task's progress. Call the [`ready` method](https://docs.celeryq.dev/en/stable/reference/celery.result.html#celery.result.AsyncResult.ready) to see if it has been processed yet:

```python
results.ready()
True
```

You can check the answer returned by the function using the [`get` method](https://docs.celeryq.dev/en/stable/reference/celery.result.html#celery.result.AsyncResult.get). It's usually a good idea to set a timeout so that it won't hang waiting if the result is not available yet:

```python
results.get(timeout=1)
173
```

While this test uses trivial calculations, the results validate that the system is working as intended and able to communicate with RabbitMQ using Koyeb's [service mesh](/docs/reference/service-mesh-and-discovery).

When you are finished, exit the Python session by typing:

```python
exit()
```

You can then close the bash session by typing:

```shell
exit
```

## Conclusion

In this guide, we covered how to deploy a Celery worker on Koyeb using git-driven deployment. Because Celery requires a message broker for coordination, we also discussed how to deploy a RabbitMQ container on Koyeb using Docker-based deployment.

By deploying both of these services within a single application, we were able to configure Celery to connect with RabbitMQ over Koyeb's service mesh with minimal configuration. Our Celery deployment is backed by a GitHub repository, so it will automatically redeploy whenever new changes are pushed to the branch it is tracking. This makes it easy to change your running Celery worker configuration by modifying your project's code.

Questions or suggestions to improve this guide? Join us on the [community platform](https://community.koyeb.com/) to chat!


Dynamically scale your Celery workers with ease on Koyeb. Run on high-performance infrastructure. No credit card required.

Easy-to-scale Celery workers

This guide explains how to deploy Python Celery Workers using git-driven deployment on Koyeb Serverless Platform.