2026-11-17 20:25:07 +01:00
2026-11-17 20:25:07 +01:00
2026-11-17 20:25:07 +01:00
2026-11-17 20:25:07 +01:00
2026-11-17 20:25:07 +01:00
2026-11-17 20:25:07 +01:00
2026-11-17 20:25:07 +01:00
2026-11-17 20:25:07 +01:00
2026-11-17 20:25:07 +01:00
2026-11-17 20:25:07 +01:00
2026-11-17 20:25:07 +01:00
2026-11-17 20:25:07 +01:00
2026-11-17 20:25:07 +01:00
2026-11-17 20:25:07 +01:00

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.

  1. 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 .
    
  2. Create the stack: Stacks → Add stack → Web editor, and paste docker-compose.portainer.yml.

  3. 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_HOST and a strong POSTGRES_PASSWORD.

    • Check that TRAEFIK_NETWORK, TRAEFIK_ENTRYPOINT and TRAEFIK_CERTRESOLVER match your Traefik setup. To find the network name:

      docker inspect traefik --format '{{json .NetworkSettings.Networks}}'
      
  4. 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 same POSTGRES_* 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 pgdata volume.
  • 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 km column or a miles column, or written as 120 mi. Miles are converted to km.
  • Headers such as km, start, end, licenseplate, country, make/model, location and category are 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 state column (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, huur and privé are recognised too.
  • Dates like 14-10-2026, 09-jan-24, 9 maart 2024 and 2026-10-14 work (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 TZ time 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.

  1. Turn it on in the app. Add a long random HA_TOKEN to the stack's environment variables in Portainer (openssl rand -hex 32 makes one) and redeploy.

  2. 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_odometer and device_tracker.volvo_xc40_location. It shows three blocks: one for configuration.yaml, one for secrets.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 the homeassistant network in the compose file.
    • Same host: http://127.0.0.1:3077. Home Assistant runs with network_mode: host. Uncomment the ports: 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 from http:// 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}}'
    
  3. Add the token to Home Assistant's secrets.yaml:

    kilometer_log_auth: "Bearer <the same token as HA_TOKEN>"
    
  4. 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=off turns the lookup off, and GEOCODER_URL can 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 Authorization header is then used for the password. Instead:
    • In the rest_command, add username: and password:.
    • Send the token as an X-HA-Token: <token> header instead of Authorization.

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.

S
Description
No description provided
Readme
102 KiB
Languages
HTML 81.2%
JavaScript 18.5%
Dockerfile 0.3%