dubinc · general-adhoc · Jun 2, 2026 · coderabbitai · Jun 3, 2026 · general-adhoc
diff --git a/docs/local-development.mdx b/docs/local-development.mdx
@@ -15,9 +15,9 @@

 ## Introduction

 Dub's codebase is set up in a monorepo (via [Turborepo](https://turbo.build/repo)) and is fully [open-source on GitHub](https://github.com/dubinc/dub).

 Here's the monorepo structure:

 ```
 apps
@@ -44,10 +44,10 @@
 - `cli`: A CLI for easily shortening URLs with the Dub API.
 - `email`: Dub's email application with function to send emails and templates.
 - `embeds`: A package used embed Dub's referral dashboard.
 - `prisma`: Prisma Configuration for Dub's web-app.
 - `stripe-app`: The Stripe app for dub conversions.
 - `tailwind-config`: The Tailwind CSS configuration for Dub's web app.
 - `tinybird`: Dub's Tinybird configuration.
 - `tsconfig`: The TypeScript configuration for Dub's web app.
 - `ui`: Dub's UI component library.
 - `utils`: A collection of utility functions and constants used across Dub's codebase.
@@ -80,7 +80,7 @@
 - An [Upstash](https://upstash.com/) account
 - A [PlanetScale](https://planetscale.com/)-compatible MySQL database

 Watch this video from our friends at Tinybird to learn how to set up Dub locally:

 <iframe
  width="100%"
@@ -143,9 +143,9 @@

 </Steps>

 ## Step 2: Set up Tinybird Clickhouse database

 Next, you'll need to set up the [Tinybird](https://tinybird.co) Clickhouse database. This will be used to store time-series click events data.

 <Steps>

@@ -163,34 +163,43 @@
 
   <Step title="Install Tinybird CLI and authenticate">
 
-In your newly-cloned Dub repo, navigate to the `packages/tinybird` directory.
+    In your newly-cloned Dub repo, navigate to the `packages/tinybird` directory.
 
-    If you have `brew`, install `pipx` by running `brew install pipx`. If not, you can check [installation guide](https://pipx.pypa.io/stable/installation/) for other options. After that, install the Tinybird CLI with `pipx install tinybird-cli` (requires Python >= 3.8).
+    Install the Tinybird CLI:
 
-    Run `tb auth --interactive` and paste your `admin` Auth Token.
+    ```bash Terminal
+    curl https://tinybird.co | sh
+    ```
+
+    Then authenticate with Tinybird:
+
+    ```bash Terminal
+    tb login
+    ```
 
   </Step>
 
   <Step title="Publish Tinybird datasource and endpoints">
 
-    Run `tb deploy` to publish the datasource and endpoints in the `packages/tinybird` directory. You should see the following output (truncated for brevity):
+    Run `tb --cloud deploy` to publish the datasource and endpoints to your Tinybird Cloud workspace.
 
     ```bash Terminal
-    $ tb deploy
-
-    ** Processing ./datasources/click_events.datasource
-    ** Processing ./endpoints/clicks.pipe
-    ...
-    ** Building dependencies
-    ** Running 'click_events'
-    ** 'click_events' created
-    ** Running 'device'
-    ** => Test endpoint at https://api.us-east.tinybird.co/v0/pipes/device.json
-    ** Token device_endpoint_read_8888 not found, creating one
-    ** => Test endpoint with:
-    ** $ curl https://api.us-east.tinybird.co/v0/pipes/device.json?token=p.ey...NWeaoTLM
-    ** 'device' created
-    ...
+    tb --cloud deploy
+    ```
+
+    You should see output like this when the deployment is live:
+
+    ```bash Terminal
+    Deployment URL: https://cloud.tinybird.co/aws/us-east-1/<workspace-name>/deployments/<deployment-id>
+    Job API URL: https://api.us-east.aws.tinybird.co/v0/jobs/<job-id>
+    Jobs URL: https://cloud.tinybird.co/aws/us-east-1/<workspace-name>/jobs
+
+    * Deployment submitted. It will be auto-promoted when ready.
+    » Waiting for deployment to be ready...
+    ✓ Deployment is ready
+    » Waiting for deployment to be promoted...
+    ✓ Deployment promoted
+    ✓ Deployment #1 is live!
     ```
 
   </Step>
@@ -199,23 +208,23 @@
 
     You will then need to update your [Tinybird API base URL](https://www.tinybird.co/docs/api-reference/api-reference.html#regions-and-endpoints) to match the region of your database.
 
-    From the previous step, take note of the **Test endpoint** URL. It should look something like this:
+    From the previous step, take note of the **Job API URL** in the deployment output. It should look something like this:
 
     ```bash Terminal
-    Test endpoint at https://api.us-east.tinybird.co/v0/pipes/device.json
+    Job API URL: https://api.us-east.aws.tinybird.co/v0/jobs/<job-id>
     ```
 
-    Copy the base URL and paste it as the `TINYBIRD_API_URL` environment variable in your `.env` file.
+    Copy the base URL before `/v0/jobs` and paste it as the `TINYBIRD_API_URL` environment variable in your `.env` file.
 
     ```bash Terminal
-    TINYBIRD_API_URL=https://api.us-east.tinybird.co
+    TINYBIRD_API_URL=https://api.us-east.aws.tinybird.co
     ```
 
   </Step>

 </Steps>

 ## Step 3: Set up Upstash Redis database

 Next, you'll need to set up the [Upstash](https://upstash.com) Redis database. This will be used to cache link metadata and serve link redirects.

@@ -223,9 +232,7 @@
 
   <Step title="Create Upstash database">
 
-In your [Upstash account](https://console.upstash.com/), create a new database.
-
-For better performance & read times, we recommend setting up a global database with several read regions.
+In your [Upstash account](https://console.upstash.com/), create a new database in the `us-east-1` region.
 
 <Frame>![Upstash Redis database](/images/upstash-create-db.png)</Frame>
 
@@ -237,23 +244,23 @@
 
 <Frame>![Upstash Redis tokens](/images/upstash-redis-tokens.png)</Frame>
 
-Navigate to the [QStash tab](https://console.upstash.com/qstash) and copy the `QSTASH_TOKEN`, `QSTASH_CURRENT_SIGNING_KEY`, and `QSTASH_NEXT_SIGNING_KEY` from the **Request Builder** section into your `.env` file.
+Navigate to the [QStash tab](https://console.upstash.com/qstash) and copy `QSTASH_TOKEN`, `QSTASH_CURRENT_SIGNING_KEY`, and `QSTASH_NEXT_SIGNING_KEY` into your `.env` file. You don't need to copy `QSTASH_URL` for local Dub setup.
 
 <Frame>![Upstash QStash tokens](/images/upstash-qstash-tokens.png)</Frame>
 
   </Step>
 
   <Step title="Optional: Set up Ngrok tunnel">
 
-    If you're planning to run Qstash-powered background jobs locally, you'll need to set up an Ngrok tunnel to expose your local server to the internet.
+    If you're testing features that enqueue QStash background jobs locally, you'll need to set up an Ngrok tunnel to expose your local server to the internet. Dub uses QStash for workflows like imports, exports, webhooks, payouts, and other `/api/cron/*` jobs. Without a tunnel, QStash won't be able to call back into your local app.
 
     Follow [these steps](https://ngrok.com/docs/getting-started/) to setup `ngrok`, and then run the following command to start an Ngrok tunnel at port `8888`:
 
     ```bash Terminal
     ngrok http 8888
     ```
 
-    Copy the `https` URL and paste it as the `NEXT_PUBLIC_NGROK_URL` environment variable in your `.env` file.
+    Copy the `https` URL and paste it as the `NEXT_PUBLIC_NGROK_URL` environment variable in your `.env` file. If you're using a free Ngrok account, this URL can change when you restart Ngrok, so make sure to update `NEXT_PUBLIC_NGROK_URL` whenever it changes.
 
   </Step>
 
@@ -322,8 +329,8 @@
 </Steps>

 <Tip>
  The docker-compose setup includes Mailhog, which acts as a mock SMTP server
  and shows received emails in a web UI. You can access the Mailhog web
  interface at [http://localhost:8025](http://localhost:8025). This is useful
  for testing email functionality without sending real emails during local
  development.
@@ -380,13 +387,13 @@

 </Steps>

 ## Step 5: Set up Mailhog

 To view emails sent from your application during local development, you'll need to set up [Mailhog](https://github.com/mailhog/MailHog).

 <Note>
  If you've already run `docker compose up` as part of the database setup, you
  can skip this step. Mailhog is included in the Docker Compose configuration
  and should already be running.
 </Note>

@@ -460,7 +467,7 @@
 pnpm dev
 ```

 The web app (`apps/web`) will be available at [localhost:8888](http://localhost:8888). Additionally, you may access Prisma Studio to manage your MySQL database at [localhost:5555](http://localhost:5555).

 ### Logging into the application

@@ -494,9 +501,9 @@

 </Steps>

 ### Testing your shortlinks locally

 Use the following url structure to ensure event tracking is working, and to populate analytics data, replacing `<shortlink-key>` with the shortlink key you've created.

 ```
 http://dub.localhost:8888/<shortlink-key>

diff --git a/images/upstash-create-db.png b/images/upstash-create-db.png
diff --git a/images/upstash-qstash-tokens.png b/images/upstash-qstash-tokens.png
diff --git a/images/upstash-redis-tokens.png b/images/upstash-redis-tokens.png