# How to Get Started with TaxHacker for Tax Calculation: Complete Setup Guide

> Learn how to get started with TaxHacker AI for tax calculation. Deploy TaxHacker locally with Docker Compose to extract receipt data and generate CSV exports.

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

---

**Deploy TaxHacker locally using Docker Compose to automatically extract receipt data with AI and generate tax-ready CSV exports.**

TaxHacker is a self-hosted AI-powered accounting application built with Next.js 15+, Prisma, and PostgreSQL. It enables automated extraction of financial data from receipts and invoices using configurable LLM providers, storing structured transaction data for tax filing purposes. This guide covers the complete installation and configuration process based on the source code in `vas3k/TaxHacker`.

## Prerequisites and Architecture

TaxHacker requires **Docker** and **Docker Compose** for the recommended deployment path. The application architecture consists of a Next.js frontend and API routes ([`app/page.tsx`](https://github.com/vas3k/TaxHacker/blob/main/app/page.tsx)), a Prisma ORM layer for database management, and PostgreSQL for persistent storage of transactions, files, and user settings.

The system supports multiple AI providers for document processing, configured in [`lib/llm-providers.ts`](https://github.com/vas3k/TaxHacker/blob/main/lib/llm-providers.ts), including OpenAI, Google Gemini, Mistral, and any OpenAI-compatible endpoint. File uploads are handled via [`lib/uploads.ts`](https://github.com/vas3k/TaxHacker/blob/main/lib/uploads.ts) and stored in the path defined by the `UPLOAD_PATH` environment variable.

## Installation and Configuration

### Clone the Repository

Start by cloning the TaxHacker repository to your local machine:

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

```

### Configure Environment Variables

Copy the example environment file and edit the required variables:

```bash
cp .env.example .env

```

Open `.env` and configure the following critical settings:

- **Set a strong authentication secret**: Define `BETTER_AUTH_SECRET` with at least 16 characters to secure user sessions.
- **Configure the database**: Use `DATABASE_URL="postgres://postgres:postgres@postgres:5432/taxhacker"` for the Docker Compose setup, or point to your existing PostgreSQL instance.
- **Add AI provider API keys**: Include at least one of `OPENAI_API_KEY`, `GOOGLE_API_KEY`, or `MISTRAL_API_KEY` to enable receipt extraction.
- **Enable self-hosted mode**: Set `SELF_HOSTED_MODE=true` to disable public signup and enable automatic admin login.

The central configuration logic resides in [`lib/config.ts`](https://github.com/vas3k/TaxHacker/blob/main/lib/config.ts), which validates these environment variables at runtime and toggles features like self-hosted authentication.

## Running the Application

Execute the Docker Compose stack to start both the application and PostgreSQL database:

```bash
docker compose up -d

```

This command launches two containers as defined in [`docker-compose.yml`](https://github.com/vas3k/TaxHacker/blob/main/docker-compose.yml): the Next.js application and the PostgreSQL service. The app container automatically runs Prisma migrations on startup (`prisma migrate dev`) to initialize the database schema defined in `prisma/schema.prisma`.

For local development without Docker, install dependencies and run the database migrations manually:

```bash
npm install
npx prisma generate && npx prisma migrate dev
npm run dev

```

Navigate to `http://localhost:7331` to access the UI. With `SELF_HOSTED_MODE` enabled, the system automatically logs you in as the first admin user.

## Processing Receipts and Invoices

### Upload and AI Extraction

To begin tax calculation preparation, click the **Upload** button in the interface and drag-and-drop an image or PDF receipt. The backend stores files in the `./data/uploads` directory (configurable via `UPLOAD_PATH`) and processes them through the selected LLM provider.

The extraction pipeline, implemented in the document processing layer, automatically identifies key financial fields including `name`, `merchant`, `total`, `currencyCode`, and `issuedAt`. These fields map to the Transaction model in [`models/transactions.ts`](https://github.com/vas3k/TaxHacker/blob/main/models/transactions.ts), which splits standard fields from user-defined custom fields before persisting to PostgreSQL.

### Programmatic Transaction Creation

You can also create transactions via the REST API for bulk import scenarios:

```typescript
const createTransaction = async (data: TransactionData) => {
  const resp = await fetch('/api/transactions', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: "Office Supplies",
      merchant: "Staples",
      total: 129.99,
      currencyCode: "USD",
      issuedAt: new Date().toISOString(),
      files: ["file-id-123"]
    }),
  });
  if (!resp.ok) throw new Error('Failed to create');
  return await resp.json();
};

```

The server-side implementation delegates to the `createTransaction` function in [`models/transactions.ts`](https://github.com/vas3k/TaxHacker/blob/main/models/transactions.ts), which handles the Prisma database insertion and links uploaded files to transaction records.

## Exporting Data for Tax Filing

Once transactions are captured, use the **Export** button to download CSV or Excel files containing all selected columns, custom fields, and original document attachment links. The export logic in [`lib/export_and_import.ts`](https://github.com/vas3k/TaxHacker/blob/main/lib/export_and_import.ts) respects your filtering criteria and includes multi-currency conversion data essential for accurate tax calculation.

## Summary

- **TaxHacker** is a self-hosted Next.js application that uses AI to extract financial data from receipts for tax preparation.
- **Deployment** requires Docker Compose, PostgreSQL, and at least one LLM provider API key configured in `.env`.
- **Key files**: [`lib/config.ts`](https://github.com/vas3k/TaxHacker/blob/main/lib/config.ts) manages environment settings, [`lib/llm-providers.ts`](https://github.com/vas3k/TaxHacker/blob/main/lib/llm-providers.ts) configures AI backends, and [`models/transactions.ts`](https://github.com/vas3k/TaxHacker/blob/main/models/transactions.ts) handles data persistence.
- **Self-hosted mode** (`SELF_HOSTED_MODE=true`) enables automatic login and disables public registration.
- **Data export** produces CSV files ready for tax filing, preserving original document links and custom metadata.

## Frequently Asked Questions

### Do I need to use Docker to run TaxHacker?

No, Docker is optional but recommended. You can run the application locally by executing `npm install`, running `npx prisma migrate dev` to initialize the database, and starting the dev server with `npm run dev`. However, Docker Compose provides a one-click deployment with automatic database migrations and consistent environment variables.

### Which AI providers does TaxHacker support for receipt extraction?

TaxHacker supports OpenAI, Google Gemini, Mistral, and any OpenAI-compatible API endpoint. The provider selection and configuration are managed in [`lib/llm-providers.ts`](https://github.com/vas3k/TaxHacker/blob/main/lib/llm-providers.ts), allowing you to choose the service that matches your privacy requirements and API key availability.

### What happens to my uploaded files and data in self-hosted mode?

In self-hosted mode, all data remains on your local infrastructure. Files are stored in the path defined by `UPLOAD_PATH` (default `./data/uploads`), and transaction data resides in your PostgreSQL database. This architecture ensures complete data privacy since no information is sent to third-party servers beyond the LLM API calls for text extraction.

### How do I customize the data fields for my specific tax requirements?

TaxHacker supports custom field definitions through the `fields` table managed by [`models/fields.ts`](https://github.com/vas3k/TaxHacker/blob/main/models/fields.ts). You can add custom fields via the UI, which will then be accepted by the transaction creation API alongside standard fields like `total` and `currencyCode`. These custom fields appear in CSV exports and can be filtered in the transactions table.