Deploy Cal.com on Koyeb to Manage Scheduling with Google Calendar
Tags: opensource, coding, productivity, tutorial
Published: 2023-10-10 16:12:49

[Cal.com](nhttps://cal.com/) is a meeting and event scheduling platform designed to make it easy for people to schedule time with you.  By integrating with your existing calendar systems, Cal.com allow people to see your availability and select a time slot that works well for both parties.  Cal.com knows how to handle multiple calendars, can integrate with video conferencing software, offers configurable availability settings, and keep all participants in the loop through email when there are meeting changes.

This guide will cover how to launch and set up a Cal.com instance on [Koyeb](https://www.koyeb.com/) to facilitate meeting creation, invitation, and management for you and your team.  We will deploy a PostgreSQL database backed by [Neon](https://neon.tech/) to store user and configuration data.  We will also use a [Mailgun](https://www.mailgun.com/) account to configure our instance to send transactional emails to both users and non-user attendees.  To demonstrate the calendar integrations, we will connect Cal.com with a Google calendar so that it can provide availability information when scheduling.

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

[![Deploy to Koyeb](https://www.koyeb.com/static/images/deploy/button.svg)](https://app.koyeb.com/deploy?name=cal-com&type=docker&image=docker.io/calcom/cal.com&env[PORT]=8000&env[NEXT_PUBLIC_WEBAPP_URL]=CHANGE_ME&env[DATABASE_URL]=CHANGE_ME&env[NEXTAUTH_SECRET]=CHANGE_ME&env[CALENDSO_ENCRYPTION_KEY]=CHANGE_ME&env[EMAIL_SERVER_HOST]=smtp.mailgun.org&env[EMAIL_SERVER_PORT]=587&env[EMAIL_SERVER_USER]=CHANGE_ME&env[EMAIL_SERVER_PASSWORD]=CHANGE_ME&env[EMAIL_FROM]=CHANGE_ME&ports=8000;http;/)

**Note:** You will need to replace the values of most of the environment variables in the configuration with your own information.  Scroll down to the associated parts of this guide for more details about what is expected.  Additionally, be sure to select an image size of **small** or larger since the application struggles with fewer resources.

## 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 Cal.com instance.
- **[Neon](https://www.koyeb.com/docs/integrations/databases/neon):** We will configure an external PostgreSQL database to persist our data between deploys.
- **[Mailgun](https://www.mailgun.com/):** We will use a Mailgun account to send transactional emails to users and attendees.
- **[Google](https://www.google.com/):** We need a Google account to test and use the Google Calendar integration.  This allows users to authenticate with their Google calendars to check time slot availability and to create new events.

## Steps

This guide will cover how to deploy Cal.com 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. [Generate Cal.com secrets](#generate-cal-com-secrets)
4. [Deploy Cal.com to Koyeb](#deploy-cal-com-to-koyeb)
5. [Set up the Cal.com admin account](#set-up-the-cal-com-admin-account)
6. [Enable two factor authentication](#enable-two-factor-authentication)
7. [Configure Google calendar integration](#configure-google-calendar-integration)
8. [Test the scheduling workflow](#test-the-scheduling-workflow)

## Create a PostgreSQL database with Neon

Cal.com stores user and configuration data in a PostgreSQL database.

By using an external database, we can be sure that all of our important data persists across deployments.  This configuration also makes scaling the service much easier.  We will use Neon as our database provider because they have a generous free tier that's more than enough 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:

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 `calcom` 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.
7. 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 Cal.com 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.  Cal.com uses email to send transactional emails for both users and meeting attendees that your users may schedule with.

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 for Cal.com 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 | Cal.com environment variable | Example                                                          |
|-------------------|------------------------------|------------------------------------------------------------------|
| SMTP hostname     | `EMAIL_SERVER_HOST`          | `smtp.mailgun.org`                                               |
| Port              | `EMAIL_SERVER_PORT`          | 587                                                              |
| Username          | `EMAIL_SERVER_USER`          | `postmaster@sandboxbac59f0e6dac45cdab38e53aee4e1363.mailgun.org` |
| Password          | `EMAIL_SERVER_PASSWORD`      | `e627704d99111f00c7aedf3805961383-262b123e-66b6979f`             |

## Generate Cal.com secrets

Before we can deploy the Cal.com instance, we need to generate some secret values that the application will use:

* `NEXTAUTH_SECRET`: Used to encrypt JavaScript Web Tokens (JWT) and to hash email verification tokens.
* `CALENDSO_ENCRYPTION_KEY`: A 32 byte application key for symmetric encryption and decryption.

You can create both of these secrets with the `openssl rand` command.  The required variables and a command to recommend the recommended format for each is included here:

| Cal.com environment variable | Command to generate value | Example                                        |
|------------------------------|---------------------------|------------------------------------------------|
| `NEXTAUTH_SECRET`            | `openssl rand -base64 32` | `cCwmv+sppk1I54aLYGQGojG7sofkkS2IFQ/KVf30XC0=` |
| `CALENDSO_ENCRYPTION_KEY`    | `openssl rand -base64 24` | `X+OY8WUBaaQnALON+QTVMfHN4i826Twb`             |

Save the generated values and use them when configuring Cal.com in the next step.

## Deploy Cal.com to Koyeb

Now that you have the necessary pieces of information about your services and secrets, you can deploy a Cal.com instance to Koyeb.

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

1. Click the **Create App** button on the [Koyeb console](https://app.koyeb.com/).
2. Select **Docker** as your deployment method.
3. Set the **Image** to `docker.io/calcom/cal.com`. Leave the **Tag** blank to pull the latest image or select the [image tag](https://hub.docker.com/r/calcom/cal.com/tags) you'd like to deploy.
4. In the **Instance** section, select size **Small** or larger.  The application does not run well when given fewer resources.
5. Scroll down to the bottom and set the **App name** to your choice.  Copy the fully qualified app name (it will have the format: `<YOUR_APP_NAME>-<KOYEB_ORG_NAME>.koyeb.app`).
6. Click the **Advanced** button to view additional settings.
7. In the **Environment variables** section, click the **Bulk Edit** button and replace the contents with the following:

    ```
    PORT=8000
    NEXT_PUBLIC_WEBAPP_URL=
    DATABASE_URL=
    NEXTAUTH_SECRET=
    CALENDSO_ENCRYPTION_KEY=
    EMAIL_SERVER_HOST=smtp.mailgun.org
    EMAIL_SERVER_PORT=587
    EMAIL_SERVER_USER=
    EMAIL_SERVER_PASSWORD=
    EMAIL_FROM=
    CALCOM_TELEMETRY_DISABLED=1
    ```

    Set the variable values to reference your own information as follows:
    * `NEXT_PUBLIC_WEBAPP_URL`: Set to `https://` followed by the fully qualified app name you copied from the bottom of the page.  It will have the following format: `https://<YOUR_APP_NAME>-<KOYEB_ORG_NAME>.koyeb.app`.  Make sure that the URL does **not** end with a trailing slash.
    * `DATABASE_URL`: Set to the connection URI you copied from Neon.
    * `NEXTAUTH_SECRET`: Set to the random string you generated with `openssl rand -base64 32`.
    * `CALENDSO_ENCRYPTION_KEY`: Set to the random string you generated with `openssl rand -base64 24`.
    * `EMAIL_SERVER_HOST`: Set the Mailgun SMTP hostname (`smtp.mailgun.org`).
    * `EMAIL_SERVER_PORT`: Set to the Mailgun SMTP port (`587`)
    * `EMAIL_SERVER_USER`: Set to the Mailgun username you copied from the SMTP settings page (will have the format of an email address).
    * `EMAIL_SERVER_PASSWORD`: Set to the Mailgun password you copied from the SMTP settings page.
    * `EMAIL_FROM`: Set to an email address to address emails from.  Usually this is something like `notifcations@` followed by the fully qualified app name you copied from the bottom of the page.
    * `CALCOM_TELEMETRY_DISABLED`: (Optional) Set to `1` to optionally disable sending Cal.com anonymous usage data.
8. Click the **Deploy** button.

Koyeb will pull the Cal.com container image from Docker Hub and use it to provision a new container. The Cal.com application will start up and perform its initialization procedure.  When it is finished it will begin listening on the port specified in the configuration.

Once the Cal.com instance 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 Cal.com admin account

When you visit Cal.com's URL, you will be redirected to an account creation page for the administrative account:

![Cal.com sign up page](https://www.koyeb.com/static/images/tutorials/cal.com/account_creation_page.png)

Fill out the form with your own information.  When you are finished, click **Next Step**.

The next page allows you to choose the license you wish to use:

![Cal.com choose license](https://www.koyeb.com/static/images/tutorials/cal.com/choose_license.png)

Since we are not using a license key, select **AGPLv3 License** and click **Nest Step** to continue.

The next page allows you to choose the Apps you want to enable:

![Cal.com enable apps](https://www.koyeb.com/static/images/tutorials/cal.com/enable_apps.png)

All of the apps are selected by default, but you can choose to disable them here if you'd like.  You can also modify this later through the administrative interface.

When you are done, click **Finish** to complete the initial instance setup.

Next, you'll be redirected to the rest of the user creation flow for the administrative account.  Since you already provided some of the details during the instance configuration, some of the form fields will be pre-populated with your initial responses:

![Cal.com configure initial account](https://www.koyeb.com/static/images/tutorials/cal.com/configure_initial_account.png)

Change the timezone if desired and click **Next Step** to continue.

Next, you'll be asked to connect your calendar:

![Cal.com skip calendar connection](https://www.koyeb.com/static/images/tutorials/cal.com/skip_calendar_connection.png)

We have not yet configured the calendar integrations, so click **I'll connect my calendar later** at the bottom of the page to continue.

The following page will ask about configuring video apps:

![Cal.com skip video apps](https://www.koyeb.com/static/images/tutorials/cal.com/skip_video_apps.png)

Click **Set up later** at the bottom of the page to continue.

Next, you'll be asked to set the days and times you'd like Cal.com to schedule within:

![Cal.com set scheduling windows](https://www.koyeb.com/static/images/tutorials/cal.com/set_scheduling_windows.png)

Modify the time windows to suit your needs.  If you change your mind, you can change this at any time through the web interface.  Click **Next Step** when you are finished.

Finally, you can enter profile information about yourself to give context to people scheduling with you:

![Cal.com profile information](https://www.koyeb.com/static/images/tutorials/cal.com/profile_information.png)

Fill out as much information as you'd like and click **Finish** to continue.

You will be taken to Cal.com dashboard for your account:

![Cal.com main dashboard with warning](https://www.koyeb.com/static/images/tutorials/cal.com/dashboard_with_warning.png)

## Enable two factor authentication

As the note at the top of the screen suggests, the administrative features will be disabled until you configure two factor authentication.

To configure two factor authentication, click **Settings** at the bottom of the left side menu and then click **Two factor auth** under the **Security** section of the settings menu:

![Cal.com two factor authentication page](https://www.koyeb.com/static/images/tutorials/cal.com/2fa_page.png)

Toggle the slider for **two factor authentication** to begin configuring additional authentication.

Enter your password again at the next prompt:

![Cal.com 2fa confirm password](https://www.koyeb.com/static/images/tutorials/cal.com/2fa_confirm_password.png)

Next, you will be given a QR code to set up a second factor for authentication:

![Cal.com QR code](https://www.koyeb.com/static/images/tutorials/cal.com/qr_code.png)

Scan the QR code with your phone's authentication app and the click **Continue**.

The next screen will show an authentication challenge:

![Cal.com authentication challenge](https://www.koyeb.com/static/images/tutorials/cal.com/authentication_challenge.png)

Enter the code from your phone's authenticator app to confirm that your second factor is working correctly and then click **Enable**.

Cal.com will then give you backup codes that you can use in case your second factor is not available:

![Cal.com backup codes](https://www.koyeb.com/static/images/tutorials/cal.com/backup_codes.png)

Click **Copy** or **Download** to save them to a safe location.

Two factor authentication is now configured on your account, but the orange security banner will still be displayed.  To get access to the administrative features, you need to re-login.

Click the **Back** button in the upper left corner to return to the dashboard.  On the dashboard screen, click on your username in the upper left corner and click **Sign out**.  You'll be redirected to the login page where you can authenticate with your email address and password.  Enter your second factor code from your authenticator app when prompted.  When you log back in, you'll have access to all of the administration features without the warning banner:

![Cal.com dashboard without warning](https://www.koyeb.com/static/images/tutorials/cal.com/dashboard_without_warning.png)

## Configure Google calendar integration

Now that the Cal.com administrative account is unlocked, we can configure our calendar integration.  To do so, we need to configure access to our Google account's calendar system.  This involves enabling the associated APIs within Google and then generating authentication details so that Cal.com can authenticate and manage the resource correctly.

### Create a new project

To begin, visit the [Google API console](https://console.cloud.google.com/apis/dashboard) for the Google account you want to integrate with.

In the project selector near the top of the page, click **New Project** to create a new project.

You'll be asked to choose a name for the project and whether you'd like to create the project within the context of an organization:

![Google choose project name](https://www.koyeb.com/static/images/tutorials/cal.com/google_choose_project_name.png)

Click **Create** to continue.

Next, select your new project from the project selector at the top of the page:

![Google select project](https://www.koyeb.com/static/images/tutorials/cal.com/google_select_project.png)

### Enable the calendar API

Click **Enable APIs and Services** to go to the API library:

![Google API library](https://www.koyeb.com/static/images/tutorials/cal.com/google_api_library.png)

In the search box, enter **calendar** to filter the available APIs.  Click **Google Calendar API** on the results page to continue:

![Google choose calendar API](https://www.koyeb.com/static/images/tutorials/cal.com/google_choose_calendar_api.png)

You'll be taken to the API's detail page:

![Google calendar API page](https://www.koyeb.com/static/images/tutorials/cal.com/google_calendar_api_page.png)

Click **Enable** to enable the Google Calendar API.

### Configure the OAuth consent screen

Next, click **OAuth consent screen** in the left sidebar menu.  You'll be taken to a screen where you can configure the details to authenticate your application:

![Google oauth user type](https://www.koyeb.com/static/images/tutorials/cal.com/google_oauth_user_type.png)

Select **External** as the user type and then click **Create** to continue.

Next, you'll need to provide details about your application:

![Google oauth app registration](https://www.koyeb.com/static/images/tutorials/cal.com/google_oauth_app_registration.png)

Fill out the required fields: **app name** to be shown to users, the **user support email** where user inquiries will be directed, and the **developer contact information** where Google can contact you in case of problems.  You can leave the other fields on the page blank.  Click **Save and continue** when you are ready.

On the following page, click **Add or remove scopes**:

![Google oauth add scopes](https://www.koyeb.com/static/images/tutorials/cal.com/google_oauth_add_scopes.png)

In the filter field, type **calendar**:

![Google oauth select scopes](https://www.koyeb.com/static/images/tutorials/cal.com/google_oauth_select_scopes.png)

Check the boxes associated with the `.../auth/calendar.readonly` and `.../auth/calendar.events` scopes.  Scroll down to the bottom of the page and click **Update**.

Click **Save and continue** at the bottom of the page.

On the next page, click **Add users** to add test users:

![Google oauth add test users page](https://www.koyeb.com/static/images/tutorials/cal.com/google_oauth_test_users_page.png)

In the "add users" form, enter the email addresses you'd like to authorize for the application.  Click **Add** to add the test users.

Click **Save and continue** at the bottom of the page to move on.

On the final page, review the details to ensure everything's configured correctly.

### Configure credentials

Next, click **Credentials** in the left sidebar menu to go to the credentials page:

![Google credentials page](https://www.koyeb.com/static/images/tutorials/cal.com/google_credentials_page.png)

Click **Create credentials** at the top of the screen and select **OAuth client ID** from the available options.

On the page that follows, select **Web application** as the application type and then choose a name for the OAuth client:

![Google client ID config](https://www.koyeb.com/static/images/tutorials/cal.com/google_client_id_config.png)

Next, in the **Authorized redirect URIs** section, click **Add URI**.  Add the following URI values, being sure to substitute the base URL for your Cal.com instance's Koyeb subdomain:

* `<YOUR_KOYEB_SERVICE_SUBDOMAIN>/api/integrations/googlecalendar/callback`
* `<YOUR_KOYEB_SERVICE_SUBDOMAIN>/api/auth/callback/google`

For example, if your Cal.com service's name is `calcom` and your Koyeb organization is named `myorg`, the URIs would look like this:

![Google authorized redirects](https://www.koyeb.com/static/images/tutorials/cal.com/google_authorized_redirects.png)

Click **Create** when you are finished to create the new credentials.

On the following page, click **Download JSON** to download the authentication string you'll need to authenticate to the Calendar API:

![Google download credentials](https://www.koyeb.com/static/images/tutorials/cal.com/google_download_credentials.png)

### Redeploy Cal.com to configure the new integration

Next, we need to use the JSON credentials we just downloaded to give Cal.com access to our Google calendar.

In the [Koyeb control panel](https://app.koyeb.com/), select the Cal.com service you deployed and then click **Settings** in the top bar to view the service configuration.

Scroll down to the **Environment variables** section and click **Add variable**.

Add a new variable called `GOOGLE_API_CREDENTIALS` and set its value to the JSON string that you downloaded from Google's credentials page.

When you are finished, click **Apply** at the bottom of the page.

Koyeb will redeploy your Cal.com instance with the additional environment variable.  The service will go through its normal initialization procedure and, when healthy, Koyeb will replace the previously running instance of Cal.com with the new deployment.

Once the new instance is running, revisit the application URL to configure the Google calendar integration.

From your dashboard, click **Apps** in the left sidebar menu:

![Cal.com app store](https://www.koyeb.com/static/images/tutorials/cal.com/app_store.png)

Click **Calendar** to view the available calendar apps.  Scroll to find **Google Calendar** and click **Details**.

On the next page, click **Install App** to install the Google calendar integration.

![Cal.com install integration](https://www.koyeb.com/static/images/tutorials/cal.com/install_integration.png)

You'll be redirected to the Google authorization flow.  Choose one of the accounts you added as a test account during the OAuth consent configuration.

You will likely see a warning page like this indicating that Google has not verified the application in question:

![Google verification warning](https://www.koyeb.com/static/images/tutorials/cal.com/google_verification_warning.png)

Click **Continue** to proceed with the authorization.

Next, you'll be asked to select what permissions to give the integration:

![Google permissions selection](https://www.koyeb.com/static/images/tutorials/cal.com/google_permissions_selection.png)

Check the **Select all** box and then click **Continue**.

After a moment, you'll be taken to the calendar configuration page within Cal.com.  You can select the calendars you want to use to check for conflicts by toggling the associated sliders.

## Test the scheduling workflow

Now that your Google calendar is accessible from your Cal.com instance, you can test that the integration is working as intended by testing the scheduling workflow.

Click **View public page** in the lower part of the left sidebar menu to access your meeting scheduling page.  You'll be taken to the main page that people can use to schedule meetings with you:

![Cal.com main scheduling page](https://www.koyeb.com/static/images/tutorials/cal.com/main_scheduling_page.png)

Click one of the meeting lengths.  You'll be taken to the scheduling interface to select the timeslot to book:

![Cal.com scheduling interface](https://www.koyeb.com/static/images/tutorials/cal.com/scheduling_interface.png)

If you take a look at the available slots, you should be able to confirm that:

* All available slots fit into the scheduling windows you configured for your account.  You can change these windows at any time by clicking **Availability** in the left sidebar menu of your Cal.com user dashboard.
* The available slots take into account the events that are already on your Google calendar.

Select an open timeslot from the list of options.  You can enter your details on the next page to add meeting notes and enter your personal details:

![Cal.com schedule meeting](https://www.koyeb.com/static/images/tutorials/cal.com/schedule_meeting.png)

Click **Confirm** when you are finished to book a new meeting.

You'll get confirmation that the meeting was scheduled successfully:

![Cal.com scheduling confirmation](https://www.koyeb.com/static/images/tutorials/cal.com/scheduling_confirmation.png)

You should be able to confirm the meeting in a number of ways:

* As the owner of the schedule, you should receive an email informing you that someone has added a meeting to your calendar.
* As the person requesting the meeting, you should receive an email confirming the invitation and providing any relevant details.
* The new meeting should appear on your calendar as expected.
* In the Cal.com dashboard, if you select **Bookings** in the left sidebar menu, you should see the event in the **Upcoming** tab.

After confirming the creation was successful, click the **Cancel** button associated with the event on the **Bookings** page:

![Cal.com bookings page](https://www.koyeb.com/static/images/tutorials/cal.com/bookings_page.png)

Provide a reason for the cancellation and click **Cancel event**:

![Cal.com cancel event](https://www.koyeb.com/static/images/tutorials/cal.com/cancel_event.png)

You should be able to confirm the cancellation in the same four places you checked earlier.

## Conclusion

In this guide, we deployed and configured a Cal.com instance to Koyeb.  The scheduling application is backed by a PostgreSQL database provided by Neon and configured to use Mailgun for transactional emails.  Once we launched the application, we configured the Google calendar integration and tested some of the scheduling workflows to confirm that everything works as expected.

You can continue to configure your Cal.com instance by enabling and configuring additional apps in the Cal.com app store.  You can find out the configuration details for some of the most popular options in the [Cal.com documentation on installed apps](https://cal.com/docs/introduction/quick-start/self-hosting/install-apps).  The general process will look much like what we did for the Google calendar integration (create credentials in the associated service, redeploy Cal.com with additional environment variables, and then configure the app).  Because all of the data is stored elsewhere, redeploying your application on Koyeb or upgrading to a larger instance if you need additional performance is simple, allowing you to grow as your needs change.