Guides: Cloudflare Workers
- Cloudflare Workers is a serverless platform that allows
you to deploy workloads closer to where your users are with 200+ metro data centers in its CDN network.
Learn more about operating Workers here. - Cloudflare Workers run on the V8 Runtime. The RavenDB Node.js client SDK provides support to query RavenDB resources in RavenDB Cloud or in your own cloud infrastructure.
- In this guide, you will learn how to deploy a Cloudflare Worker using the RavenDB Cloudflare Worker template
that is connected to your RavenDB database.
This guide assumes you are familiar with Node.js development techniques and the basics of Cloudflare Workers.
-
Watch our tutorial video below or on YouTube.
-
In this page:
Before We Get Started
You will need the following before continuing:
- A RavenDB Cloud account or self-hosted client certificate
- A free or paid Cloudflare account
- Git
- Node.js version 16 and above with npm
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
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 (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 (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 IDCF_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
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: