Kilometer Log
Trip log (kilometres, start/end date, license plate with country, location, category) with a statistics page. A Node app and its own PostgreSQL database, served behind your existing Traefik.
Deploy with Portainer
All settings live in the stack's Environment variables in Portainer. No .env file is used.
-
Build the app image on the Docker host, from this folder. The web editor can't build, and the image is not on Docker Hub:
docker build -t kilometer-log:latest . -
Create the stack: Stacks → Add stack → Web editor, and paste
docker-compose.portainer.yml. -
Add the variables: under Environment variables, switch to Advanced mode and paste the lines from
stack.env.example, or use Load variables from .env file with that file.-
Set
APP_HOSTand a strongPOSTGRES_PASSWORD. -
Check that
TRAEFIK_NETWORK,TRAEFIK_ENTRYPOINTandTRAEFIK_CERTRESOLVERmatch your Traefik setup. To find the network name:docker inspect traefik --format '{{json .NetworkSettings.Networks}}'
-
-
Deploy the stack.
How the variables are used:
- Portainer fills them into the compose file, which is how the Traefik labels get your hostname.
- Portainer also writes them to
stack.env, which both containers load. The database and the app read the samePOSTGRES_*values, so you enter them only once.
To update the app later, rebuild the image (step 1) and redeploy the stack, or use Update the stack.
Deploy with the Docker CLI (alternative)
docker-compose.yml builds the image itself and reads the same variables from your shell or a .env file next to it:
cp stack.env.example .env # then edit it
docker compose up -d --build
Then open https://<APP_HOST>.
The database runs in the kilometer-log-db container.
- Its data lives in the
pgdatavolume. - It sits on an internal network, so only the app can reach it, not Traefik or the internet.
- The app creates its table on first start.
Importing your Excel sheet
In Excel, select the rows including the header row, copy them, and choose Import from Excel. Paste the rows there.
- Distances can be in a
kmcolumn or amilescolumn, or written as120 mi. Miles are converted to km. - Headers such as
km,start,end,licenseplate,country,make/model,locationandcategoryare recognised. - Make/model is optional. You can also fill it in afterwards per vehicle on the Admin page.
- The country column is optional. Country names or codes both work (
Norway,NO,N,GB,UK,USA). - For US plates, add a
statecolumn (CA,New York), or write it in the country cell (USA - CA,California). - Without a country column, Dutch-looking plates get NL and other plates are marked with a grey
?. - Categories: the names you set on the Admin page (default
Business,Rental,Personal).PNOD,business,zakelijk,hire,huurandprivéare recognised too. - Dates like
14-10-2026,09-jan-24,9 maart 2024and2026-10-14work (Dutch and English month names), as do decimal commas.
Home Assistant: personal trips from the odometer
Each time the car's odometer changes, Home Assistant sends the new reading to the app. The app adds the distance since the previous reading as a trip:
- Category: personal (you can pick another one in the setup).
- Date: the day of the reading, in the
TZtime zone. - Location: the town where the trip started, looked up from the car's GPS position.
- The departure place is where the car stood at the previous reading.
- Prefer the arrival place? Change Location of these trips in Admin → Home Assistant.
- The town's country becomes the location's country, unless you already set one for that town.
- Plate, country and make/model: copied from the trips already in the log for that plate.
- Tag: these trips show a small HA tag in the trip list. You can edit or delete them like any other trip.
Set it up
Ready-made files are in the home-assistant folder of this zip (see its README); the steps below explain where they go.
-
Turn it on in the app. Add a long random
HA_TOKENto the stack's environment variables in Portainer (openssl rand -hex 32makes one) and redeploy. -
Copy the YAML. On the Admin page, open Home Assistant → Set up Home Assistant. Fill in the plate and your entities, for example
sensor.volvo_xc40_odometeranddevice_tracker.volvo_xc40_location. It shows three blocks: one forconfiguration.yaml, one forsecrets.yaml, and the automation. Paste the automation in Home Assistant under Settings → Automations & scenes → Create automation → Edit in YAML. Choose how Home Assistant reaches the app. An internal route skips Traefik, so no redirects or public domain are involved:- Docker network:
http://kilometer-log:3000. Home Assistant runs in Docker on a network the app is also on, for example your Traefik network. If Home Assistant has its own network, uncomment thehomeassistantnetwork in the compose file. - Same host:
http://127.0.0.1:3077. Home Assistant runs withnetwork_mode: host. Uncomment theports:lines in the compose file; the port is then reachable from the server only. - Public address: through Traefik. Use the exact
https://address, because a redirect fromhttp://turns Home Assistant's POST into a GET and drops the data.
Not sure which one applies? This shows Home Assistant's networks (use your container's name):
docker inspect homeassistant --format '{{.HostConfig.NetworkMode}} {{json .NetworkSettings.Networks}}' - Docker network:
-
Add the token to Home Assistant's
secrets.yaml:kilometer_log_auth: "Bearer <the same token as HA_TOKEN>" -
Restart Home Assistant.
The first reading only sets the starting point; trips start with the second reading. The Admin page shows the last reading per car and what happened with it.
Good to know
- Town names come from OpenStreetMap (Nominatim), in Dutch by default (
GEOCODER_LANG).- The app follows OpenStreetMap's fair-use rules: at most one lookup per 1.5 seconds, a recognisable app name, and places it has already looked up are remembered.
- Only readings that become a trip are looked up.
- If a lookup fails, the zone name from Home Assistant is used ("Home", "Office"); outside a zone the location stays empty. The Admin page shows why.
GEOCODER=offturns the lookup off, andGEOCODER_URLcan point to your own Nominatim server.- The car's position is sent to OpenStreetMap for this; nothing else is.
- Several trips at once: some cars only report a new odometer value now and then. If the reading jumps by several trips at once, they arrive as one trip.
- Ignored readings: readings that are the same or lower than before (for example after a Home Assistant restart) are ignored.
- Large jumps: a jump of more than 5000 km (
HA_MAX_JUMP_KM) is skipped and becomes the new starting point, so a wrong value can't create a huge trip. - Restart button: on the Admin page this forgets a car's last reading. The next reading then becomes the new starting point.
- With Traefik basic auth: the
Authorizationheader is then used for the password. Instead:- In the
rest_command, addusername:andpassword:. - Send the token as an
X-HA-Token: <token>header instead ofAuthorization.
- In the
The API (for other tools)
POST /api/ha/odometer, with header Authorization: Bearer <HA_TOKEN> and a JSON body:
{"plate": "S-123-AB", "odometer": 243950, "unit": "km", "time": "2026-10-22T19:19:47Z", "location": "Home", "category": "personal"}
Only plate and odometer are required. The answer says whether a trip was created.
Protecting it
The app has no login. To add basic auth through Traefik:
htpasswd -nb mitchell 'your-password' | sed -e 's/\$/\$\$/g'
Add the output as BASIC_AUTH_USERS to the stack's environment variables in Portainer. Then uncomment the two middleware labels in docker-compose.yml.
Backup and restore
docker exec kilometer-log-db pg_dump -U kilometerlog kilometerlog > kilometerlog.sql
docker exec -i kilometer-log-db psql -U kilometerlog kilometerlog < kilometerlog.sql
Updating
Replace the files and run docker compose up -d --build. The data in the pgdata volume is kept.