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

To update TaxHacker to the latest version, back up your data via the UI, modify the image tag in 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, 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 in your deployment directory. Locate the app service definition and change the image reference to the latest tag:

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), 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:

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

docker compose down && docker compose up -d

The 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) 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) and modify the bodySizeLimit value. The default configuration sets this to 256mb:

// 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:

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):

1. Update your 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 line 3 to change versions, and adjust 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.

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. 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), 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 is insufficient for your files. Edit 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 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.

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