Guides: Cloudflare Workers


Before We Get Started

You will need the following before continuing:

Create a Cloudflare RavenDB Worker project

There are two primary ways to get started:

  • Using the Cloudflare Deploy with Workers wizard
  • Using npm to initialize an empty template

Using Deploy with Workers wizard

Using Deploy with Workers step-by-step wizard is the simplest method but requires a GitHub account and authorized access, which may not be applicable in all situations.
For example, this method will not work with GitLab or GitHub Enterprise.

Screenshot of Deploy with Cloudflare Wizard

Screenshot of Deploy with Cloudflare Wizard

The wizard will guide you through deploying a Worker and hooking up a new repo with continuous deployment through GitHub actions. It will also automatically set up your repository secrets.

Forking the Template

The deployment wizard will fork the GitHub repository into your GitHub user account (not an organization).
You will want to manually rename the repository and unmark it as a "Template" in the repository settings before cloning it.

Using npm to initialize an empty template

If you do not want to use the wizard, you can use npm and Cloudflare's create-cloudflare package to create a new Worker using the RavenDB template:

npm init cloudflare my-project https://github.com/ravendb/template-cloudflare-worker

This will generate all the required code and run npm install for you to set up a new project on your computer.
You can then push to GitHub or any other source provider from there.

Test the template locally

By default, the template is set up to connect to the RavenDB Live Test cluster.

You can run the template locally to test the connection:

npm run dev

First-Time Wrangler Setup

If this is the first time you are connecting using the Wrangler CLI, it will open a browser window for you to authenticate using your Cloudflare account.
After you sign in, you can return to the terminal.

Open the browser by pressing the "B" key (e.g. http://localhost:7071) and you should see a screen like this:

Successfully connected to RavenDB welcome screen from Cloudflare

Successfully connected to RavenDB welcome screen from Cloudflare (unauthenticated)

This means you have successfully connected to your RavenDB database.

Updating Database Connection Settings

The wrangler.toml file contains configuration for the worker. Here's an example:

name = "ravendb-worker"
main = "./src/index.ts"
node_compat = true
compatibility_date = "2022-05-03"

# mtls_certificates = [
#  { binding = "DB_CERT", certificate_id = "<CERTIFICATE_ID>" } 
# ]

# Define top-level environment variables
# under the `[vars]` block using
# the `key = "value"` format
[vars]
DB_URLS = ""
DB_NAME = ""

# Override values for `--env production` usage
[env.production]
name = "ravendb-worker-production"
[env.production.vars]
DB_URLS = ""
DB_NAME = ""

The node_compat = true setting is required for the RavenDB Node.js SDK to operate correctly.
If this is false or missing, you will experience runtime exceptions.

There are two variables defined that are used by the template:

  • DB_URLS -- These are the node URLs for your RavenDB instance (Cloud or self-hosted).
    The values are comma-separated.
  • DB_NAME -- This is the default database to connect to.

When left blank, the Live Test connection settings are used. The defaults are under [vars] and overridden in [env.production.vars].

wrangler.toml overrides on deployment

You can also define settings within the Cloudflare worker dashboard. The values in the wrangler.toml will overwrite those values on new deployment. Keep this in mind when deciding where to define the variables!

Make sure the named database exists

For brand new projects, the database you connect to may not exist yet.
Follow the create database procedure to create a new database, otherwise you will encounter a DatabaseDoesNotExist exception on startup.

Variables defined here, including the DB_CERT mTLS binding, will be exposed as process.env variables you can access in the worker at runtime. You'll use the mTLS binding when connecting to an authenticated cluster using your client certificate.

Connecting to an Authenticated RavenDB Cluster

Client certificate authentication is handled through Cloudflare mTLS authentication for Workers.
You will need to upload your certificate to your Cloudflare account so that it can be accessed and bound to your Worker.

Obtain RavenDB certificate

First, download the RavenDB client certificate package you will use to authenticate.
Follow the guides for either Cloud certificates or for self-hosted certificates.
It is recommended to generate a new client certificate with limited access rights instead of a ClusterAdmin-level certificate.
This also ensures the Worker is using a dedicated certificate that can be managed separately.

Once extracted to a folder, you'll need the paths to the .crt and .key files for the next step.

Do not copy certificate files to the project

For Cloudflare Workers, you do not store your certificate files in your project directory.
Certificates are password-equivalents. Take care not to accidentally commit them to source control.
Keep them outside the project directory for this next step.

Upload certificate using wrangler

You will use Cloudflare's wrangler CLI to upload your .crt and .key files as an mTLS certificate.
You only need to do this once (and each time the certificate needs to be renewed).

wrangler global vs. local usage

This guide will use npx to execute wrangler to ensure the commands work across platforms.
You can also choose to install wrangler globally using npm i wrangler -g to use without npx, but you will need to keep it updated. Read more about Installing and updating Wrangler

In the project directory, run:

npx wrangler mtls-certificate upload --cert path/to/db.crt --key path/to/db.key --name ravendb_cert

This will display output like:

Uploading mTLS Certificate ravendb_cert...
Success! Uploaded mTLS Certificate ravendb_cert
ID: <CERTIFICATE_ID>
Issuer: CN=...
Expires on ...

Copy the <CERTIFICATE_ID> in the output for the next step.

Setup mTLS binding in wrangler

Cloudflare Workers use the wrangler.toml file for configuration. You will need to add a "binding" so that the certificate is made available and used by the Worker at runtime.

Edit your wrangler.toml file to update the following:

mtls_certificates = [
  { binding = "DB_CERT", certificate_id = "<CERTIFICATE_ID>" } 
]

It is important to maintain the DB_CERT name here as it is expected by the template.
Replace <CERTIFICATE_ID> with the Certificate ID you copied from the previous step.

Be sure to also update the DB_URLS and DB_NAME variables for your cluster.

For a deeper dive on what this is doing, you can read more about how mTLS bindings work in Cloudflare Workers.

Testing Certificate Authentication Locally

Once the certificate binding is added, you will be able to start the Worker locally and test the certificate authentication.

npm run dev

This will launch wrangler in development mode. It may require you to sign in to your Cloudflare account before continuing.

The env.DB_CERT binding will not be available in local mode (--local), this is a known issue with Wrangler.
The template is configured to start Wrangler in non-local mode.

You should see the following message in the console:

A bound cert was found and will be used for RavenDB requests.

Once started, the Worker will be running on a localhost address.

Open the browser by pressing the "B" key (e.g. http://localhost:7071) and you should see a screen like this:

Successfully connected to RavenDB welcome screen from Cloudflare

Successfully connected to RavenDB welcome screen from Cloudflare (authenticated)

If you see a green check and the correct connection details, this means you have successfully connected to your RavenDB database.

Deploying to Production

Automated Deployment

If you have used the Deploy with Workers wizard, your GitHub repository is already set up for continuous integration and deployment to Cloudflare.

If you have manually initialized the template, once pushed to GitHub you can enable GitHub action workflows.

You will also need to add two repository secrets:

  • CF_ACCOUNT_ID -- Your Cloudflare global account ID
  • CF_API_TOKEN -- An API token with the "Edit Workers" permission

Once these secrets are added, trigger a workflow manually or push a commit to trigger a deployment.

Manual Deployment

You can also deploy a Worker manually using:

npm run deploy

If your Worker account is not yet set up, Wrangler will walk you through the steps.

Verifying Production Worker

In your Cloudflare Dashboard, the Worker should be deployed.
You can find your Worker URL in the dashboard under "Preview URL" and open it to test the connection is working.

Preview URL shown in the Cloudflare Worker dashboard

Preview URL shown in the Cloudflare Worker dashboard

If it is not working, verify the Wrangler settings are being applied.

Using RavenDB in the Worker

The RavenDB Cloudflare template uses the itty-router package to provide basic routing and middleware support.

Each routing handler is passed a request and env argument.
A document session is opened per-request and accessible through env.db.

Example: Load user on route

router.get("/users/:id", async (request: IRequest, env: Env) => {
    const user = await env.db.load("users/" + request.params.id);

    return new Response(JSON.stringify({ user }), { status: 200 });
});

Tutorial Video

Watch our Using Cloudflare Workers with RavenDB tutorial: