# How to Update TaxHacker to the Latest Version: A Complete Docker Upgrade Guide

> Easily update TaxHacker to the latest version with this Docker guide. Follow simple steps to back up data and restart your application with the newest release.

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

---

**To update TaxHacker to the latest version, back up your data via the UI, modify the `image` tag in [`docker-compose.yml`](https://github.com/vas3k/TaxHacker/blob/main/docker-compose.yml) to `ghcr.io/vas3k/taxhacker:latest`, then run `docker compose pull && docker compose up -d` to fetch and restart with the new release.**

TaxHacker is distributed as a Docker image via GitHub Container Registry, making updates straightforward for self-hosted instances. Since the application persists all data in PostgreSQL and provides built-in backup functionality, you can safely update TaxHacker to the latest version without risking your financial records. This guide covers the standard upgrade workflow, verification steps, and edge cases for the vas3k/TaxHacker repository.

## Back Up Your Data Before Updating

Always create a backup before updating TaxHacker to the latest version. Navigate to **Settings → Backups** in the web interface and download a data archive. This archive contains your complete database state and protects against accidental data loss during the container restart.

The backup mechanism exports everything stored in the PostgreSQL database defined in your [`docker-compose.yml`](https://github.com/vas3k/TaxHacker/blob/main/docker-compose.yml), ensuring no transaction history is lost when the application container is replaced.

## Standard Upgrade Process

Follow these steps to update TaxHacker when running a standard Docker Compose deployment.

### 1. Update the Docker Compose Configuration

Open [`docker-compose.yml`](https://github.com/vas3k/TaxHacker/blob/main/docker-compose.yml) in your deployment directory. Locate the `app` service definition and change the image reference to the latest tag:

```yaml
services:
  app:
    image: ghcr.io/vas3k/taxhacker:latest  # Line 3: Update this tag

    # ... remaining configuration

```

According to the source code at [[`docker-compose.yml`](https://github.com/vas3k/TaxHacker/blob/main/docker-compose.yml)](https://github.com/vas3k/TaxHacker/blob/main/docker-compose.yml), line 3 controls which container image version is deployed. Switching from a specific version tag (e.g., `0.5.4`) to `latest` ensures you always pull the most recent stable release.

### 2. Pull the New Image and Restart Containers

Execute the following commands in the directory containing your [`docker-compose.yml`](https://github.com/vas3k/TaxHacker/blob/main/docker-compose.yml):

```bash

# Fetch the latest image from GitHub Container Registry

docker compose pull

# Restart services with the new image

docker compose up -d

```

Alternatively, for a completely clean start that removes the old container before creating a new one:

```bash
docker compose down && docker compose up -d

```

The [`docker-compose.yml`](https://github.com/vas3k/TaxHacker/blob/main/docker-compose.yml) already defines the required environment variables and volume mounts for PostgreSQL data persistence, so no additional configuration changes are necessary during routine updates.

### 3. Verify the Update

Confirm you are running the latest version by checking the application version identifier. You can inspect [[`package.json`](https://github.com/vas3k/TaxHacker/blob/main/package.json)](https://github.com/vas3k/TaxHacker/blob/main/package.json) in the repository (currently showing `"version": "0.5.5"`) or open the TaxHacker UI at `http://localhost:7331` and look for the version display in the interface.

## Troubleshooting Large Request Errors After Updating

If you encounter a "request entity too large" error when uploading documents after updating TaxHacker to the latest version, you must increase the server actions payload limit.

Edit [[`next.config.ts`](https://github.com/vas3k/TaxHacker/blob/main/next.config.ts)](https://github.com/vas3k/TaxHacker/blob/main/next.config.ts) and modify the `bodySizeLimit` value. The default configuration sets this to `256mb`:

```typescript
// next.config.ts
const nextConfig = {
  experimental: {
    serverActions: {
      bodySizeLimit: '256mb',  // Increase this value if needed
    },
  },
};

```

Change `256mb` to a higher value (e.g., `512mb`) and restart the application container:

```bash
docker compose restart app

```

## Migrating From Legacy Versions (v0.3 to v0.5)

If you are updating TaxHacker from v0.3 to v0.5 or later, you must perform a database migration because the application switched from SQLite to PostgreSQL.

Follow the four-step process documented in [[`docs/migrate-0.3-0.5.md`](https://github.com/vas3k/TaxHacker/blob/main/docs/migrate-0.3-0.5.md)](https://github.com/vas3k/TaxHacker/blob/main/docs/migrate-0.3-0.5.md):

1. Update your [`docker-compose.yml`](https://github.com/vas3k/TaxHacker/blob/main/docker-compose.yml) to use the final v0.3 image tag temporarily
2. Create a backup archive from the Settings page while running v0.3
3. Switch the image tag to `ghcr.io/vas3k/taxhacker:latest` (v0.5+)
4. Restore the backup onto the new PostgreSQL instance through the UI

This migration path ensures your SQLite data transfers correctly into the new PostgreSQL schema used by current versions.

## Summary

- **TaxHacker updates are Docker-based**: Pull the `ghcr.io/vas3k/taxhacker:latest` image and restart containers to update TaxHacker to the latest version.
- **Backup first**: Export your data via Settings → Backups before any upgrade to protect against data loss.
- **Configuration files matter**: Modify [`docker-compose.yml`](https://github.com/vas3k/TaxHacker/blob/main/docker-compose.yml) line 3 to change versions, and adjust [`next.config.ts`](https://github.com/vas3k/TaxHacker/blob/main/next.config.ts) if you encounter upload size limits.
- **Major versions require migration**: When moving from v0.3 to v0.5+, follow the SQLite-to-PostgreSQL migration guide in [`docs/migrate-0.3-0.5.md`](https://github.com/vas3k/TaxHacker/blob/main/docs/migrate-0.3-0.5.md).

## Frequently Asked Questions

### Will updating TaxHacker delete my existing financial data?

No. TaxHacker stores all data in a PostgreSQL database defined as a separate service in your [`docker-compose.yml`](https://github.com/vas3k/TaxHacker/blob/main/docker-compose.yml). When you run `docker compose pull` to update the `app` container image, the database volume persists unchanged. However, always create a backup via **Settings → Backups** before updating as a safety precaution against unlikely failure scenarios.

### How do I know if I am running the latest version of TaxHacker?

Check the version string displayed in the TaxHacker web interface after logging in. You can also compare your running instance against the version declared in the repository's [[`package.json`](https://github.com/vas3k/TaxHacker/blob/main/package.json)](https://github.com/vas3k/TaxHacker/blob/main/package.json), which contains the canonical version number (e.g., `"0.5.5"`).

### What should I do if I get an error when uploading files after upgrading?

If you see "request entity too large" errors, the default `bodySizeLimit` in [`next.config.ts`](https://github.com/vas3k/TaxHacker/blob/main/next.config.ts) is insufficient for your files. Edit [`next.config.ts`](https://github.com/vas3k/TaxHacker/blob/main/next.config.ts) to increase the `bodySizeLimit` value from the default `256mb` to `512mb` or higher, then run `docker compose restart app` to apply the change.

### Can I automate TaxHacker updates without manually editing docker-compose.yml?

Yes. If your [`docker-compose.yml`](https://github.com/vas3k/TaxHacker/blob/main/docker-compose.yml) already references `ghcr.io/vas3k/taxhacker:latest`, you can automate updates by running `docker compose pull && docker compose up -d` on a schedule using cron or a similar task scheduler. Ensure you have automated backups configured before enabling automatic updates.