Koyeb
Integrate a serverless Upstash Redis database with your Koyeb applications. Combine the serverless features of Koyeb on the application side and Upstash for your key-value storage to deploy and scale applications globally with ease.
This guide explains how to connect an Upstash Redis data store as a database cache with an application running on Koyeb. To successfully follow this documentation, you will need to have:
- A Koyeb account to deploy the application. You can optionally install the Koyeb CLI to deploy the application from the command line
- An Upstash account to deploy the database
- Node.js and
npm
installed on your local machine to create the demo application.
If you already have a freshly created Upstash Redis database running and want to quickly preview how to connect your Upstash database to an application running on Koyeb, use the Deploy to Koyeb button below.
Make sure to replace the UPSTASH_REDIS_REST_URL
and UPSTASH_REDIS_REST_TOKEN
environment variables with the values for your Upstash database.
Create an Upstash Redis database
To create an Upstash Redis database, sign into your Upstash account.
In the Upstash console, select Redis from the top navigation bar. On the Redis page, click Create database:
- In the Name field, choose a name for your database. In this example, we’ll use
example-koyeb-upstash
. - Select the Type of deployment you want. Because this is demo does not have global requirements, we will use “Regional” in this guide to limit the choices we have to make.
- In the Region drop-down menu, choose a location that’s geographically convenient for your database and users. We use “N. Virginia (us-east-1)“.
- Select your preferred options. In this example, we will select “TLS (SSL) Enabled” so that connections to the database are encrypted and “Eviction” so that older data will be purged when we run out of space.
- Click Create to provision the Redis database.
Retrieve your Upstash URL and token
On your Upstash Redis page, scroll down to the REST API section of the page.
Click on the UPSTASH_REDIS_REST_URL
and UPSTASH_REDIS_REST_TOKEN
buttons to copy their respective values to your clipboard. Paste the copied values to a safe location so that you can reference them later when testing and deploying your application.
Alternatively, you can click on the @upstash/redis
tab to view a code snippet:
When you copy the code block using the provided copy button, the code snippet, along with your database’s URL and access token will be copied to your clipboard. While this works well for private or demonstration code, it generally isn’t good practice to hard-code sensitive data like tokens within your application. To avoid this, we will configure the application to get these values from the environment instead.
Create a demo application
Next, you can create a simple Node.js application that uses your Upstash Redis database. The application will use the Express web framework to build and serve a simple page and Upstash’s own @upstash/redis
package to connect to the database.
Install the dependencies
Create a new directory for your demo application and navigate to the new location:
Within the new directory, generate a package.json
file for the new project using the default settings:
Next, install the @upstash/redis
package so that you can connect to your Redis database from within the application and the express
package so that we can build a basic web application:
Create the application file
Now, create a new file called index.js
with the following contents:
Note: If you are running Node.js version 17 or lower, you need to adjust the first line of the app to import from the @upstash/redis/with-fetch
instead of @upstash/redis
. Node.js versions prior to 18 did not natively support fetch
API, so you need to change the import path in order to access that functionality.
This above code will introduce a simple counter
key to your Redis database. It will use this key to store the number of times the page has been accessed and display that value on the page.
Add the run scripts
Finally, edit the package.json
file to define the scripts used to run the application. The dev
script runs the application in debug mode while the start
script starts the application normally:
Run the demo application locally
Now that the project is set up, you can run the application locally verify that it functions correctly.
In your shell, set and export the variables you copied from your Upstash Redis page:
In the same terminal, you should now be able to test your application by typing:
The application server should start in debug mode, printing information about the process to the display. In your browser, navigate to 127.0.0.1:3000
to see your application. It should show the counter and number of visits you’ve made: “Counter: 0”. The number should increase by one every time you refresh the page.
Press CTRL-c to stop the application when you are finished.
Deploy the application to Koyeb using git-driven deployment
Once you’ve verified that the project runs locally, create a new Git repository to save your work.
Run the following commands to create a new Git repository within the project’s root directory, commit the project files, and push changes to GitHub. Remember to replace the values of <YOUR_GITHUB_USERNAME>
and <YOUR_REPOSITORY_NAME>
with your own information:
You can deploy the demo application to Koyeb and connect it to the Upstash Redis database using the control panel or via the Koyeb CLI.
Via the Koyeb control panel
To deploy the using the control panel, follow these steps:
- Click Create App in the Koyeb control panel.
- Select GitHub as the deployment option.
- Choose the GitHub repository and branch containing your application code.
- Name your service, for example
upstash-service
. - Click Advanced to view additional options. Under Environment variables, click Add Variable to add two new variables called
UPSTASH_REDIS_REST_URL
andUPSTASH_REDIS_REST_TOKEN
. Populate them with the values you copied for your Upstash Redis database. - Name the App, for example
upstash-demo
. - Click the Deploy button.
A Koyeb App and Service will be created. Your application will be built and deployed to Koyeb. Once the build has finished, you will be able to access your application running on Koyeb by clicking the URL ending with .koyeb.app
.
Via the Koyeb CLI
To deploy the example application using the Koyeb CLI, run the following command in your terminal:
Make sure to replace <YOUR_GITHUB_USERNAME>/<YOUR_REPOSITORY_NAME>
with your GitHub username and repository name and replace <YOUR_UPSTASH_REDIS_REST_URL>
and <YOUR_UPSTASH_REDIS_REST_TOKEN>
with the values copied from your Upstash Redis page.
Access deployment logs
To track the app deployment and view the build logs, execute the following command:
Access your app
Once the deployment of your application has finished, you can retrieve the public domain to access your application by running the following command:
Access runtime logs
With your app running, you can track the runtime logs by running the following command:
Deploy the application to Koyeb using a pre-built container
As an alternative to using git-driven deployment, you can deploy a pre-built container from any public or private registry. This can be useful if your application needs specific system dependencies or you need more control over how the build is performed.
To dockerize the application, start by adding a file called .dockerignore
to the project’s root directory. Paste the following contents to limit the files copied to the Docker image:
Afterwards, create a Dockerfile
in your project root directory and copy the content below:
The Dockerfile above provides the minimum requirements to run the sample Node.js application. You can easily extend it depending on your needs.
Be sure to set the UPSTASH_REDIS_REST_URL
and UPSTASH_REDIS_REST_TOKEN
environment variables to the values you copied from the Upstash console when you deploy the container in the Koyeb control panel.
To build and push the Docker image to a registry and deploy it on Koyeb, refer to the Deploy an app from a Docker image documentation.
A Koyeb App and Service will be created. Your Docker image will be pulled and deployed to Koyeb. Once the deployment has finished, you will be able to access your application running on Koyeb by clicking the URL ending with .koyeb.app
.
Delete the example application and Upstash Redis database
To delete the example application and the Upstash Redis database and avoid incurring any charges, follow these steps:
- From the Upstash console, select your Redis database and scroll to the bottom of the Details page. Click Delete this database and follow the instructions.
- From the Koyeb control panel, select your App. Click the Settings tab, and click the Danger Zone. Click Delete App and follow the instructions. Alternatively, from the CLI, you can delete your Koyeb App and service by typing
koyeb app delete example-koyeb-upstash
.
Was this page helpful?