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

152 lines
8.3 KiB
Markdown

# 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://<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):
```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 <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:
```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.