Quickstart

This quickstart walks you through deploying RealReply to your Cloudflare account and getting the core system running.

By the end, you’ll have RealReply deployed, configured, and ready to receive tickets inside your own infrastructure.

Once deployment is complete, continue to the Embedding Guide for instructions on integrating RealReply directly into your application UI.

Prerequisites

• Cloudflare account
• Node.js 18+ installed
• An account with an email provider such as Mailgun, Brevo, Resend, etc.
• An optional custom domain (recommended)

Installation

1) Clone the repo and install dependencies

git clone https://github.com/realreplyhq/realreply.git
cd realreply
npm install

2) Create a wrangler.json file

cp workers/app/wrangler.jsonc.example workers/app/wrangler.json

2) Create the database

npx wrangler d1 create DATABASE --config workers/app/wrangler.jsonc

You may be asked to sign in and have to retry the command. Choose all the default for all questions.

Once completed, edit workers/app/wrangler.jsonc and ensure only one database is defined like this:

{
  "d1_databases": [
    {
      "binding": "DATABASE",
      "database_name": "realreply",
      "database_id": "<YOUR DATABASE UUID>",
      "migrations_dir": "../../drizzle"
    }
  ]
}

Make sure the real UUID is substituted for database_id.

Create the database tables:

npm run db:migrate:remote

3) Configure environment variables

Create workers/app/.env.production.local by copying env.example and adding the following information.

BETTER_AUTH_SECRET=...
BETTER_AUTH_URL=...

MAILGUN_API_KEY=...
MAILGUN_DOMAIN=...

RR_JWT_SECRET=...

Both secrets should be long random numbers. One good way to generated them is via openssl:

openssl rand -hex 16

Another method is to use an online password generator.

The Mailgun secrets can be omitted initially if you are using a different provider. Just note that notifications like welcome, reset password etc. will silently fail.

There are also variables for social logins. These can be left blank.

4) Cloudflare environment variables and secrets.

Add non-secret values to the vars section of workers/app/wrangler.json. There is a commented out example.

{
  "vars": {
    "BETTER_AUTH_URL": "...",
    "MAILGUN_DOMAIN": "mg.yourdomain.com"
  }
}

Add secrets one at a time:

npx wrangler secret put BETTER_AUTH_SECRET -c workers/app/wrangler.jsonc
npx wrangler secret put MAILGUN_API_KEY -c workers/app/wrangler.jsonc
npx wrangler secret put RR_JWT_SECRET=... -c workers/app/wrangler.jsonc

Use the exact values from .env.production.local.

5) Deploy the Next.js worker

npm run dev --workspace workers/app

6) Custom domain

It's possible to use the workers.dev domain that Cloudflare automatically assigns, but it's better to use a custom domain.

The custom domain is added to the worker using the Cloudflare dashboard:

• In Quick Search type ** Workers & Pages** then navigate to that page.
• Select the worker you just uploaded and go to Settings
• Next to Domains & Routes click '+Add'.
• Click 'Custom Domain' and enter your domain, e.g. 'support.yourdomain.com'.
• Click 'Add domain' to complete.

Test it by clicking the 'Visit' button.

Once the custom domain is working you'll see an initial setup card.

7) Setup

Setup only requires you to add an initial user account.
This account will be the owner of the instance and the first admin.

Enter:

• Name
• Email
• Password

Other users are created by:

• Signup - usually you disable this later
• Auto-provisioning when accessed from your site.

8) Configure the websocket worker.

Create a wrangler.json file from the example:

cp workers/ws/wrangler.jsonc.example workers/ws/wrangler.jsonc

Edit workers/ws/wrangler.jsonc and replace under [routes] with your domain. Use the domain you created above keeping the /ws path.

9) Deploy the websocket worker.

npm run deploy --workspace workers/ws