Getting Started

This guide takes you from zero to a deployed, working analytics dashboard in a few minutes — no prior familiarity with the codebase required.

Prerequisites

You need two things before deploying: a database and a place to host the app.

1. Create a PostgreSQL database

diy-analytics needs a PostgreSQL database to store your analytics data — this is separate from the app itself, which is why it's the first thing you set up. Any PostgreSQL 14+ database works:

• Cloud options: Vercel Postgres, Neon, Supabase, or Railway.
• Self-hosted / local: Any standard PostgreSQL instance.

Get your connection string (URI) in the format: postgres://user:password@host:5432/diy-analytics?sslmode=require

Keep this URI handy — it becomes your DATABASE_URL environment variable. If you're on Neon or Supabase, use the pooled connection string, not the direct one — see Database Setup for the exact settings each provider needs. See Environment Variables for the full list of variables the app reads.

2. Sign up for a free Vercel account

Vercel is the recommended way to host your dashboard. It's also the only option that supports the public tracking endpoint out of the box — see why in Database Setup if you're considering another host.

• Go to Vercel's signup page and create a free account.
• You'll use this account to deploy and manage your analytics dashboard.

Deploying your dashboard

Step 1: Start the deployment

Step 2: Configure the deployment in Vercel

• Sign up or log in when prompted.
• Choose a repository name — Vercel will create a copy of the diy-analytics codebase under your own GitHub account with this name (e.g. my-website-analytics) so you have your own deployable copy of the project.
• You'll then see the Environment Variables section. Set the following:

Step 3: Set up the database tables

Your database is currently empty — it doesn't yet have the tables diy-analytics needs to store projects, pageviews, and events. This command creates them for you:

Run it once, from your own computer, with DATABASE_URL in .env.local pointed at the database you created in step 1 (see Setting Up Locally if you haven't cloned the project yet). You only need to run this again in the future if you update diy-analytics and it ships new tables.

Step 4: Point NEXT_PUBLIC_SITE_URL at your real URL

Go to your Vercel project's Settings → Environment Variables, set NEXT_PUBLIC_SITE_URL to your production URL (e.g. https://my-website-analytics.vercel.app, no trailing slash), and redeploy. This value is used when generating project tracking snippets.

Daily rollup cron

A "cron job" is just a task that runs automatically on a schedule, without you triggering it. diy-analytics uses one to compress yesterday's raw pageview data into faster daily summaries and clean up old data — this is already configured for you in vercel.json and runs once a day (03:00 UTC) with no setup required. Optionally, set CRON_SECRET to a random string in your environment variables to stop anyone outside Vercel from triggering this job manually.

Create your account and first project

diy-analytics uses database-backed authentication. Open your live URL, sign up to create your workspace owner account, then create your first project. Open the project and go to Settings → Tracking Snippet to get your script.

What's next