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

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:

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:

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

The repository root contains the core configuration files, including package.json, tsconfig.json, and next.config.ts, which define the TypeScript and Next.js 15 runtime environment.

Install Node Dependencies

Install the required packages listed in package.json, which include Next.js, Prisma 6, LangChain, and Better-Auth:

npm install

Configure Environment Variables

Copy the example environment file and edit the required values:

cp .env.example .env

Edit .env to include these minimal required variables:

# 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. 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.

Initialize the Database

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

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:

npm run dev

The script defined in 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 file that orchestrates the application and a PostgreSQL 17 instance:

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 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 – Centralizes access to process.env with validation and default values.
• lib/auth.ts – Implements Better-Auth for password-less authentication and session management.
• lib/llm-providers.ts – Wraps LangChain integrations for OpenAI, Google Gemini, and Mistral.
• 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.

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 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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}