calibertechnology/taxserver repository overview

An http[s] server with a simple API for querying and calculating U.S. payroll withholding taxes. For more information, see https://taxupdate.com⁠. This image includes a demo tax table, which means it has formulas for all the states and most local payroll taxes. The "demo" aspect means the formulas are a few months old.

To run:

docker run -p 8443:8443 calibertechnology/taxserver

Direct your browser to https://localhost:8443⁠ and ignore the security warning (for self-signed certificates). You'll get a description of the service's API and some examples.

If you prefer a regular http service, which will run on port 80:

sudo docker run -p 80:80 calibertechnology/taxserver

The default ports used by the TaxServer container are 80 for HTTP and 8443 for HTTPS. If you wish to use different ports, you can do so by setting the environment variables HTTP_PORT and/or HTTPS_PORT:

export HTTPS_PORT="443"
docker run --env HTTPS_PORT -p 443:443 calibertechnology/taxserver

If you have a TaxUpdate subscription⁠, you can import the latest taxfile at startup. Using your <username> and <password> credentials, run:

export USERNAME="<username>"
export PASSWORD="<password>"
docker run --env USERNAME --env PASSWORD -p 8443:8443 calibertechnology/taxserver

The TaxServer image will attempt to download the latest taxfile. If this fails, you'll see a message on the console, and the image will use the demo tables.

Alternatively, you can load one or more taxfiles by mapping a local directory to /taxes on the image. For example, if the local directory local contains the desired tables, you can start the image using:

docker run -v ./local:/taxes -p 8443:8443 calibertechnology/taxserver

If multiple taxfiles are found, all will be read and merged.

For cloud services such as AWS or Azure, you can set the USERNAME and PASSWORD environment variables for TaxServer using either the CLI or web interface for starting the image. Please remember that this container instance should not be used by third parties except through your licensed product.

On cloud services such as Amazon's ECS/Fargate which do not allow redirection of exposed ports, you may wish to adjust the ports used by this container. You can do so by setting the environment variables HTTP_PORT and/or HTTPS_PORT as described above. The TaxServer application will open the ports as requested.