Upstash Redis and Koyeb

Upstash (opens in a new tab) is a data platform that provides serverless Redis, Kafka, and QStash databases for high performance web applications, functions, and edge computing. Using Upstash, you can quickly deploy databases to multiple regions, scale effortlessly, and benefit from low latency durable storage using standard tooling.

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 (opens in a new tab) to deploy the application. You can optionally install the Koyeb CLI to deploy the application from the command line
• An Upstash account (opens in a new tab) to deploy the database
• Node.js (opens in a new tab) 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.

(opens in a new tab)

Create an Upstash Redis database

To create an Upstash Redis database, sign into your Upstash account (opens in a new tab).

In the Upstash console, select Redis from the top navigation bar. On the Redis page, click Create database:

1. In the Name field, choose a name for your database. In this example, we'll use example-koyeb-upstash.
2. 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.
3. 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)".
4. 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.
5. 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:

import { Redis } from '@upstash/redis'
 
const redis = new Redis({
  url: '<YOUR_UPSTASH_REDIS_REST_URL>',
  token: '<YOUR_UPSTASH_REDIS_REST_TOKEN>',
})
 
const data = await redis.set('foo', 'bar')

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 (opens in a new tab) web framework to build and serve a simple page and Upstash's own @upstash/redis (opens in a new tab) package to connect to the database.

Install the dependencies

Create a new directory for your demo application and navigate to the new location:

mkdir example-koyeb-upstash
cd example-koyeb-upstash

Within the new directory, generate a package.json file for the new project using the default settings:

npm init -y

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:

npm install @upstash/redis express

Create the application file

Now, create a new file called index.js with the following contents:

// Note: if you are using Node.js version 17 or lower,
//       change the first line to the following:
// const { Redis } = require ("@upstash/redis/with-fetch");
const { Redis } = require('@upstash/redis')
const express = require('express')
 
const app = express()
const redis = Redis.fromEnv()
 
app.get('/', async (req, res) => {
  const value = await redis.get('counter')
  await redis.set('counter', parseInt(value || 0) + 1)
  res.send(`Counter: ${value || 0}`)
})
 
const PORT = process.env.PORT || 3000
app.listen(PORT, () => {
  console.log(`Server running on port ${PORT}`)
})

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:

{
  "name": "example-koyeb-upstash",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "dev": "DEBUG=express:* node index.js",
    "start": "node index.js",
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "dependencies": {
    "@upstash/redis": "^1.20.6",
    "express": "^4.18.2"
  }
}

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:

export UPSTASH_REDIS_REST_URL="<YOUR_UPSTASH_REDIS_REST_URL>"
export UPSTASH_REDIS_REST_TOKEN="<YOUR_UPSTASH_REDIS_REST_TOKEN>"

In the same terminal, you should now be able to test your application by typing:

npm run dev

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.

Push the project to GitHub

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:

git init
echo 'node_modules' >> .gitignore
git add .
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 the application to Koyeb using git-driven deployment

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.

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:

Dockerfile
.dockerignore
.git
node_modules
npm-debug.log
/.cache
.env
README.md

Afterwards, create a Dockerfile in your project root directory and copy the content below:

FROM node:18-alpine AS base
 
FROM base AS deps
RUN apk add --no-cache libc6-compat
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
 
FROM base AS runner
WORKDIR /app
RUN addgroup --system --gid 1001 nodejs
RUN adduser --system --uid 1001 nodejs
COPY --from=deps /app/node_modules ./node_modules
COPY . .
USER node
EXPOSE 3000
ENV PORT 3000
CMD ["npm", "run", "start"]

The Dockerfile above provides the minimum requirements to run the sample Node.js application. You can easily extend it depending on your needs.

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 (opens in a new tab), 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 (opens in a new tab), 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.