Guides: Cloudflare Workers

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

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.

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

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.

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].

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.

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.

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).

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.

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.

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

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

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 });
});