# 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: ```sh 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: ```sh 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: ```sh cp stack.env.example .env # then edit it docker compose up -d --build ``` Then open `https://`. 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): ```sh docker inspect homeassistant --format '{{.HostConfig.NetworkMode}} {{json .NetworkSettings.Networks}}' ``` 3. **Add the token** to Home Assistant's `secrets.yaml`: ```yaml kilometer_log_auth: "Bearer " ``` 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: ` header instead of `Authorization`. ### The API (for other tools) `POST /api/ha/odometer`, with header `Authorization: Bearer ` and a JSON body: ```json {"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: ```sh 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 ```sh 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.