TaxHacker Prerequisites: Complete Setup Guide for Self-Hosted AI Accounting

To run TaxHacker, you need Node.js ≥20, PostgreSQL 17+, system utilities (Ghostscript and GraphicsMagick), and specific environment variables including DATABASE_URL and BETTER_AUTH_SECRET.

TaxHacker is a self-hosted AI-powered accounting application built with Next.js 15+, Prisma, and PostgreSQL. Before deploying this open-source tool for managing receipts and transactions, you must satisfy several infrastructure and configuration prerequisites for running TaxHacker on your local machine or server.

Runtime and Database Requirements

TaxHacker operates on a modern JavaScript runtime with a relational database backend. The application stack requires specific versions to ensure compatibility with the Prisma ORM and Next.js App Router.

Node.js and Package Manager

The application requires Node.js version 20 or higher to execute the Next.js server and build scripts. According to the Dockerfile, the official Docker image uses node:23-slim as its base image. You can use npm, pnpm, or yarn to install the JavaScript dependencies listed in package.json.

PostgreSQL Database

You must provision a PostgreSQL 17+ instance (or any supported version) to store all transactions, users, custom fields, and application data. The [docker-compose.yml](https://github.com/vas3k/TaxHacker/blob/main/docker-compose.yml#L22-L30) defines a PostgreSQL service that handles persistent storage for the Prisma client.

System Dependencies for PDF Processing

TaxHacker handles receipt and invoice uploads that require server-side PDF rasterization. You must install Ghostscript and GraphicsMagick on your host system to generate preview images from PDF documents.

On macOS, install these via Homebrew:

brew install ghostscript graphicsmagick

On Linux distributions, install equivalent packages using apt or your package manager. The Dockerfile handles this automatically in containerized deployments by running apt-get install for these system libraries.

Required Environment Variables

TaxHacker validates configuration through a Zod-based schema defined in [lib/config.ts](https://github.com/vas3k/TaxHacker/blob/main/lib/config.ts). The following variables are mandatory for a minimal self-hosted setup:

• DATABASE_URL – The full PostgreSQL connection string (e.g., postgresql://user:password@localhost:5432/taxhacker).
• UPLOAD_PATH – Absolute filesystem path where uploaded receipts and PDFs are stored persistently.
• BETTER_AUTH_SECRET – A secret string of at least 16 characters that secures session cookies and JWTs used by the Better Auth system.

Optional Services and API Keys

While the core application functions without external services, several features require additional API credentials configured in your .env file.

LLM Providers for AI Extraction

To enable automatic data extraction from receipts and invoices, obtain API keys for at least one supported provider:

• OpenAI
• Google Gemini
• Mistral

These are configured in [lib/config.ts](https://github.com/vas3k/TaxHacker/blob/main/lib/config.ts#L55-L62) and drive the AI document processing pipeline.

Email Configuration

Password resets and notification emails require a Resend API key, sender address, and optional audience ID. As documented in [lib/config.ts](https://github.com/vas3k/TaxHacker/blob/main/lib/config.ts#L74-L78), these settings enable transactional email delivery.

Payment Processing

If you intend to enable paid "cloud" features, you must provide Stripe credentials including the secret key and webhook secret. These are validated in [lib/config.ts](https://github.com/vas3k/TaxHacker/blob/main/lib/config.ts#L68-L73).

Deployment Options

You can deploy TaxHacker using Docker Compose for a complete stack or run it locally for development.

Docker Compose (Recommended)

The fastest way to satisfy all prerequisites is using the provided compose file, which automatically configures the database and environment:

# Download the compose configuration

curl -O https://raw.githubusercontent.com/vas3k/TaxHacker/main/docker-compose.yml

# Start the stack (app + PostgreSQL)

docker compose up -d

This pulls the pre-built image ghcr.io/vas3k/taxhacker:latest and sets SELF_HOSTED_MODE, UPLOAD_PATH, and DATABASE_URL automatically.

Local Development Setup

For local development with Node.js installed directly:

# Clone the repository

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

# Install dependencies

npm install

# Configure environment variables

cp .env.example .env

# Edit .env to set DATABASE_URL, BETTER_AUTH_SECRET, and UPLOAD_PATH

# Initialize database schema

npx prisma generate
npx prisma migrate dev

# Start development server on port 7331

npm run dev

The development server listens on http://localhost:7331 by default.

Summary

• TaxHacker requires Node.js ≥20 and PostgreSQL 17+ as core infrastructure components.
• System utilities Ghostscript and GraphicsMagick are mandatory for PDF receipt processing and preview generation.
• Three environment variables are critical: DATABASE_URL, UPLOAD_PATH, and BETTER_AUTH_SECRET (minimum 16 characters).
• Optional API keys enable AI extraction (OpenAI/Gemini/Mistral), email delivery (Resend), and payments (Stripe).
• Docker Compose provides the simplest deployment path, automatically handling database provisioning and volume mounts.

Frequently Asked Questions

Can I run TaxHacker without Docker?

Yes, you can run TaxHacker locally by installing Node.js ≥20, PostgreSQL 17+, and the Ghostscript/GraphicsMagick utilities manually. Clone the repository, install dependencies with npm install, initialize the Prisma schema with npx prisma migrate dev, and start the development server with npm run dev.

Is an internet connection required for AI receipt processing?

Yes, the AI extraction features require active API keys for external LLM providers such as OpenAI, Google Gemini, or Mistral. However, the core accounting functionality works offline once the application is running and receipts are uploaded manually without AI processing.

What happens if I don't set the BETTER_AUTH_SECRET?

The application will fail to start. According to [lib/config.ts](https://github.com/vas3k/TaxHacker/blob/main/lib/config.ts#L13-L16), this secret is validated by the Zod schema and is required to secure authentication cookies and JWT tokens. It must contain at least 16 characters to satisfy the minimum length requirement.

Can I use a different database instead of PostgreSQL?

No, TaxHacker is built specifically for PostgreSQL using Prisma's PostgreSQL connector. The schema definitions, migrations, and specific SQL features used in the application require PostgreSQL 17 or a compatible version. Other databases like MySQL or SQLite are not supported.

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