# How to Set Up a Development Environment for TaxHacker: A Complete Guide

> Set up a TaxHacker development environment easily. Clone the repo, install Node.js, configure PostgreSQL, run migrations, and start the Next.js dev server. Follow this complete guide.

- Repository: [Vasily Zubarev/TaxHacker](https://github.com/vas3k/TaxHacker)
- Tags: getting-started
- Published: 2026-04-01

---

**To set up a TaxHacker development environment, clone the `vas3k/TaxHacker` repository, install Node.js 20+ dependencies, configure your PostgreSQL 17 database in `.env`, run Prisma migrations, and start the Next.js dev server on port 7331.**

TaxHacker is a self-hosted, AI-powered accounting application built with Next.js 15 and Prisma 6. Whether you are contributing to the open-source project or customizing the app for personal use, this guide provides the exact steps to configure a working local development environment using either native tooling or Docker.

## Prerequisites

Before installing TaxHacker, ensure your system meets these requirements:

- **Node.js ≥20** (LTS) – Required to run the Next.js 15 application and build scripts.
- **PostgreSQL ≥17** – Relational database for storing users, transactions, and file metadata.
- **GraphicsMagick** and **Ghostscript** – System dependencies for converting PDF receipts to images before AI processing.
- **Docker** (optional) – For containerized development if you prefer not to install PostgreSQL locally.

On macOS, install the system dependencies using Homebrew:

```bash
brew install node postgresql graphicsmagick ghostscript

```

## Step-by-Step Local Installation

### Clone the Repository

Start by cloning the official repository and navigating into the project directory:

```bash
git clone https://github.com/vas3k/TaxHacker.git
cd TaxHacker

```

The repository root contains the core configuration files, including [`package.json`](https://github.com/vas3k/TaxHacker/blob/main/package.json), [`tsconfig.json`](https://github.com/vas3k/TaxHacker/blob/main/tsconfig.json), and [`next.config.ts`](https://github.com/vas3k/TaxHacker/blob/main/next.config.ts), which define the TypeScript and Next.js 15 runtime environment.

### Install Node Dependencies

Install the required packages listed in [`package.json`](https://github.com/vas3k/TaxHacker/blob/main/package.json), which include Next.js, Prisma 6, LangChain, and Better-Auth:

```bash
npm install

```

### Configure Environment Variables

Copy the example environment file and edit the required values:

```bash
cp .env.example .env

```

Edit `.env` to include these minimal required variables:

```dotenv

# Server configuration

PORT=7331
SELF_HOSTED_MODE=true
UPLOAD_PATH="./data/uploads"

# Database connection (adjust credentials to match your PostgreSQL instance)

DATABASE_URL="postgresql://postgres:postgres@localhost:5432/taxhacker"

# Authentication secret (must be at least 16 random characters)

BETTER_AUTH_SECRET="your-random-secret-min-16-chars"

```

The `BETTER_AUTH_SECRET` secures JWTs and session cookies handled in [`lib/auth.ts`](https://github.com/vas3k/TaxHacker/blob/main/lib/auth.ts). Additional optional variables for OpenAI, Google Gemini, Mistral, Stripe, and Resend can be added later; see `.env.example` for the full list consumed by [`lib/config.ts`](https://github.com/vas3k/TaxHacker/blob/main/lib/config.ts).

### Initialize the Database

Generate the Prisma client and apply the schema migrations to your PostgreSQL instance:

```bash
npx prisma generate
npx prisma migrate dev --name init

```

These commands read the schema definitions from `prisma/schema.prisma` and create the necessary tables for `User`, `Transaction`, `Category`, and other entities used by the application.

### Start the Development Server

Launch the Next.js development server with Turbopack enabled:

```bash
npm run dev

```

The script defined in [`package.json`](https://github.com/vas3k/TaxHacker/blob/main/package.json) (`"dev": "next dev -p 7331 --turbopack"`) starts the application on **http://localhost:7331**.

## Docker-Based Development

If you prefer a containerized workflow, TaxHacker includes a [`docker-compose.yml`](https://github.com/vas3k/TaxHacker/blob/main/docker-compose.yml) file that orchestrates the application and a PostgreSQL 17 instance:

```bash
docker compose up

```

This pulls the pre-built image from `ghcr.io/vas3k/taxhacker:latest`, mounts the `./data` directory for persistent uploads, and exposes the application on port 7331. Review the compose configuration in [`docker-compose.yml`](https://github.com/vas3k/TaxHacker/blob/main/docker-compose.yml) to customize volume mounts or environment variables.

## Key Configuration Files

Understanding these core files helps you debug and extend the setup:

- **`prisma/schema.prisma`** – Defines the database models, relations, and indexes used by Prisma.
- **[`lib/config.ts`](https://github.com/vas3k/TaxHacker/blob/main/lib/config.ts)** – Centralizes access to `process.env` with validation and default values.
- **[`lib/auth.ts`](https://github.com/vas3k/TaxHacker/blob/main/lib/auth.ts)** – Implements Better-Auth for password-less authentication and session management.
- **[`lib/llm-providers.ts`](https://github.com/vas3k/TaxHacker/blob/main/lib/llm-providers.ts)** – Wraps LangChain integrations for OpenAI, Google Gemini, and Mistral.
- **[`next.config.ts`](https://github.com/vas3k/TaxHacker/blob/main/next.config.ts)** – Contains Next.js runtime configuration, including rewrites and environment exposure.

## Verify Your Installation

Open your browser to `http://localhost:7331` and confirm the following:

- The TaxHacker UI loads without errors.
- You can register a new account (auto-login works when `SELF_HOSTED_MODE=true`).
- You can upload a receipt image (PDF, PNG, or JPG) to the `./data/uploads` path.
- If you configured an AI provider API key, the application can trigger document analysis via the providers defined in [`lib/llm-providers.ts`](https://github.com/vas3k/TaxHacker/blob/main/lib/llm-providers.ts).

Check the console output for specific errors if any step fails; common issues include incorrect `DATABASE_URL` strings or missing `BETTER_AUTH_SECRET` values.

## Summary

- **Prerequisites:** Node.js 20+, PostgreSQL 17, GraphicsMagick, and Ghostscript are required for native development.
- **Configuration:** Copy `.env.example` to `.env`, set `DATABASE_URL` and a 16+ character `BETTER_AUTH_SECRET`, and adjust `PORT` if needed.
- **Database:** Run `npx prisma generate` followed by `npx prisma migrate dev` to initialize the schema from `prisma/schema.prisma`.
- **Development:** Execute `npm run dev` to start the Next.js server with Turbopack on port 7331.
- **Docker:** Use `docker compose up` for a containerized stack that includes the database and persistent storage.

## Frequently Asked Questions

### What are the minimum environment variables required to start TaxHacker?

You must define `DATABASE_URL` for PostgreSQL connectivity, `BETTER_AUTH_SECRET` with at least 16 random characters, `SELF_HOSTED_MODE=true` for local authentication, and `UPLOAD_PATH` for file storage. See [`lib/config.ts`](https://github.com/vas3k/TaxHacker/blob/main/lib/config.ts) for validation logic and `.env.example` for the full template.

### Can I use Docker instead of installing PostgreSQL locally?

Yes. Running `docker compose up` from the repository root uses the official [`docker-compose.yml`](https://github.com/vas3k/TaxHacker/blob/main/docker-compose.yml) to launch both the TaxHacker application and a PostgreSQL 17 container, mounting `./data` for uploads. This eliminates the need to install Node.js or PostgreSQL natively on your host machine.

### Which version of Node.js is required for TaxHacker development?

TaxHacker requires **Node.js 20 or higher** (LTS). The [`package.json`](https://github.com/vas3k/TaxHacker/blob/main/package.json) specifies compatibility with Next.js 15, which relies on modern Node.js features. Using older versions will result in dependency installation or runtime errors.

### Where is the database schema defined in the TaxHacker codebase?

The schema is defined in **`prisma/schema.prisma`**, which contains model definitions for `User`, `Transaction`, `Category`, and other entities. Prisma reads this file during `npx prisma generate` and `npx prisma migrate dev` to create the corresponding PostgreSQL tables and TypeScript client types.