Deploy Your Own Time Tracker with Docker

Time Tracker can run as an independent Docker deployment on your own computer. You do not need to set up a web server, database server, or VPS to use it locally.

What you need

• Docker Desktop (Windows or macOS), or Docker Engine with the Compose plugin (Linux)
• Git
• permission to access the private Time Tracker repository

Download and configure the app

Open a terminal and clone the repository:

git clone https://github.com/FrozzenPeas/timetracker.git
cd timetracker
cp .env.example .env

Open .env in a text editor and set APP_TIMEZONE to your local IANA time zone. For example:

APP_TIMEZONE=America/Vancouver

Other common choices include America/Regina, America/Toronto, and Europe/London. This setting controls how entry times and day/week boundaries are shown in the application.

Start Time Tracker

Build and start the application:

docker compose up -d --build

Open http://127.0.0.1:8080 in your browser. The app should be ready to use.

To confirm that the container is running, use:

docker compose ps
curl --fail http://127.0.0.1:8080/healthz

The health-check command returns successfully without printing an error when the app is available.

Everyday Docker commands

Run these commands from the timetracker folder:

# Stop the application
docker compose stop
 
# Start it again later
docker compose up -d
 
# Watch application logs while diagnosing a problem
docker compose logs -f app

Press Ctrl+C to stop following logs; the application will continue running.

Update to a newer version

Before an upgrade, export anything you want to retain using the application’s CSV or JSON export options. Then download the latest code, rebuild, and start the updated container:

git pull --ff-only
docker compose build --pull
docker compose up -d
docker compose ps
curl --fail http://127.0.0.1:8080/healthz

If git pull --ff-only reports local changes, do not force the update. Review those changes first with git status and git diff, or ask the person who set up the deployment for help.

A note about the proxy configuration

Use the normal compose.yaml file for this local setup. The included compose.proxy.yaml override is only for a VPS that already has a Docker-based Cloudflare Tunnel connected to an external proxy network. It is not needed for a personal copy running at 127.0.0.1:8080.

If it does not open

First check whether Docker is running, then run:

docker compose ps
docker compose logs --tail=100 app

If port 8080 is already in use, change HOST_PORT in .env to another unused port, such as 8081, then restart the app:

docker compose up -d

You would then open http://127.0.0.1:8081. If you change APP_TIMEZONE, recreate the container with the same docker compose up -d command so the new setting takes effect.

That is the complete local deployment: clone the repository, choose a time zone, start Docker Compose, and open the local address.