Setting up locally

This chapter provides a comprehensive guide for developers to set up and run diy-analytics locally. By following these steps, you will be able to customize, contribute, and gain a deeper understanding of the project.

Prerequisites

Ensure the following tools are installed on your system before proceeding:

• Node.js & npm: Version 18 or later is recommended.
• Git: For cloning the repository and version control.
• PostgreSQL Database: PostgreSQL 14 or later. You can use a local PostgreSQL server or a cloud database (Vercel Postgres, Neon, Supabase, etc.).

Local Setup Steps

1. Clone the Repository

Open your terminal and execute:

2. Install the dependencies

3. Configure your environment

Copy the example environment file and fill in your own values:

Then edit .env.local:

See Environment Variables for what each of these does. Note that authentication is database-backed — there's no global admin password to configure, you'll sign up for a workspace account the first time you open the app.

4. Apply Database Migrations

Your database is empty until you run this — it creates the tables diy-analytics needs (projects, pageviews, events, and so on) using Drizzle ORM, the library that manages the database schema:

If migrating from an existing MongoDB deployment, run the one-time data migration script:

See Migrating from MongoDB for detailed migration instructions.

5. Start the Development Server

With everything in place, you can now start the application.

This command fires up a local, hot-reloading server at http://localhost:3000.

6. Run the test suite (optional)

The project uses Jest for tests:

7. Build for production (optional)

To verify a production build compiles cleanly: