From afacf00c9ff105238e848a88e47fa381436330a9 Mon Sep 17 00:00:00 2001 From: Maurice Date: Thu, 29 Oct 2026 08:59:13 +0100 Subject: [PATCH] docs: document TREK_SERVICES, TREK_SERVICES_KEY and the daily allowance docker-compose.yml and the Helm chart name the switch and the key (the key in the Secret, never the ConfigMap), and the wiki explains the installation key, what it carries, where it goes and the admin view of the allowance. --- charts/trek/templates/configmap.yaml | 6 +++++ charts/trek/templates/deployment.yaml | 6 +++++ charts/trek/templates/secret.yaml | 6 +++++ charts/trek/values.yaml | 11 +++++++- docker-compose.yml | 2 ++ .../unit/app-config/config-templates.test.ts | 26 +++++++++++++++++++ wiki/Environment-Variables.md | 7 +++-- wiki/TREK-Places-API.md | 23 ++++++++++++++-- 8 files changed, 82 insertions(+), 5 deletions(-) diff --git a/charts/trek/templates/configmap.yaml b/charts/trek/templates/configmap.yaml index fa61189c5..27b84c024 100644 --- a/charts/trek/templates/configmap.yaml +++ b/charts/trek/templates/configmap.yaml @@ -112,6 +112,12 @@ data: {{- if .Values.env.TREK_PLACES_URL }} TREK_PLACES_URL: {{ .Values.env.TREK_PLACES_URL | quote }} {{- end }} + {{- if .Values.env.TREK_SERVICES }} + TREK_SERVICES: {{ .Values.env.TREK_SERVICES | quote }} + {{- end }} + {{- if .Values.env.TREK_SERVICES_HOSTS }} + TREK_SERVICES_HOSTS: {{ .Values.env.TREK_SERVICES_HOSTS | quote }} + {{- end }} {{- if .Values.env.GOOGLE_LIST_DATA_BASE }} GOOGLE_LIST_DATA_BASE: {{ .Values.env.GOOGLE_LIST_DATA_BASE | quote }} {{- end }} diff --git a/charts/trek/templates/deployment.yaml b/charts/trek/templates/deployment.yaml index e37ff5d67..33fd248eb 100644 --- a/charts/trek/templates/deployment.yaml +++ b/charts/trek/templates/deployment.yaml @@ -85,6 +85,12 @@ spec: name: {{ default (printf "%s-secret" (include "trek.fullname" .)) .Values.existingSecret }} key: PLACES_API_KEY optional: true + - name: TREK_SERVICES_KEY + valueFrom: + secretKeyRef: + name: {{ default (printf "%s-secret" (include "trek.fullname" .)) .Values.existingSecret }} + key: TREK_SERVICES_KEY + optional: true - name: AMAP_API_KEY valueFrom: secretKeyRef: diff --git a/charts/trek/templates/secret.yaml b/charts/trek/templates/secret.yaml index fd02abf56..eacc4da4e 100644 --- a/charts/trek/templates/secret.yaml +++ b/charts/trek/templates/secret.yaml @@ -23,6 +23,9 @@ data: {{- if .Values.secretEnv.PLACES_API_KEY }} PLACES_API_KEY: {{ .Values.secretEnv.PLACES_API_KEY | b64enc | quote }} {{- end }} + {{- if .Values.secretEnv.TREK_SERVICES_KEY }} + TREK_SERVICES_KEY: {{ .Values.secretEnv.TREK_SERVICES_KEY | b64enc | quote }} + {{- end }} {{- if .Values.secretEnv.AMAP_API_KEY }} AMAP_API_KEY: {{ .Values.secretEnv.AMAP_API_KEY | b64enc | quote }} {{- end }} @@ -77,6 +80,9 @@ stringData: {{- if .Values.secretEnv.PLACES_API_KEY }} PLACES_API_KEY: {{ .Values.secretEnv.PLACES_API_KEY | quote }} {{- end }} + {{- if .Values.secretEnv.TREK_SERVICES_KEY }} + TREK_SERVICES_KEY: {{ .Values.secretEnv.TREK_SERVICES_KEY | quote }} + {{- end }} {{- if .Values.secretEnv.AMAP_API_KEY }} AMAP_API_KEY: {{ .Values.secretEnv.AMAP_API_KEY | quote }} {{- end }} diff --git a/charts/trek/values.yaml b/charts/trek/values.yaml index 3d05420f3..97980fafb 100644 --- a/charts/trek/values.yaml +++ b/charts/trek/values.yaml @@ -112,6 +112,12 @@ env: # Base URL of a copy of the Places API you run yourself; it has to answer the same /v1 API. Read from # configuration rather than typed by a user, so an in-cluster address works without ALLOW_INTERNAL_NETWORK. # Defaults to https://places.liketrek.com. + # TREK_SERVICES: "off" + # Places search identifies this installation with a key it registers by itself on first use and keeps in the + # database. "off" sends no key; searches then use the shared pool. A key issued to you goes under + # secretEnv.TREK_SERVICES_KEY. Defaults to auto. + # TREK_SERVICES_HOSTS: "" + # Comma-separated hosts that receive the installation key over https. Defaults to places.liketrek.com. # AMAP_API_BASE: "" # Send the Amap (高德地图) calls through an egress proxy, a cache or a gateway that speaks the same API instead of # restapi.amap.com directly. The key itself is a credential and goes under secretEnv.AMAP_API_KEY, or into @@ -164,6 +170,9 @@ secretEnv: # with signing enabled, because such a key rejects every unsigned request. Leave empty # otherwise. The endpoint itself is not a secret and is set under env.AMAP_API_BASE. AMAP_API_SECRET: "" + # Optional key issued for this installation by the TREK services. Wins over the key TREK + # registers by itself and turns that registration off. Leave empty to let TREK register. + TREK_SERVICES_KEY: "" # Optional Web Push key pair, private half (base64url, 32 bytes). Only used together with # env.VAPID_PUBLIC_KEY; a pair whose halves do not belong together, or only one half, turns # push off with an error in the log until it is fixed, and every device stays registered. @@ -179,7 +188,7 @@ generateEncryptionKey: false # If set, the chart renders no Secret of its own and instead reads every secret env # var from this existing Kubernetes secret. Expected keys: ENCRYPTION_KEY (rename via # existingSecretKey), ADMIN_EMAIL, ADMIN_PASSWORD, OIDC_CLIENT_SECRET, -# UNSPLASH_ACCESS_KEY, PLACES_API_KEY, AMAP_API_KEY, AMAP_API_SECRET, +# UNSPLASH_ACCESS_KEY, PLACES_API_KEY, AMAP_API_KEY, AMAP_API_SECRET, TREK_SERVICES_KEY, # VAPID_PRIVATE_KEY, SMTP_PASS, MAPBOX_ACCESS_TOKEN, CARTO_API_KEY, DEMO_ADMIN_PASS. # Missing keys are simply left unset (they are optional), so only provide the ones your # setup needs. diff --git a/docker-compose.yml b/docker-compose.yml index 5c0c97f76..ac6e9c97b 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -61,6 +61,8 @@ services: # - UNSPLASH_ACCESS_KEY= # Optional. Unsplash Access Key for trip-cover / place-image search. Without one, TREK uses Unsplash's unauthenticated endpoint, which some datacenter/VPS IPs are blocked from (#1449). Free key at unsplash.com/developers. Can also be set per-admin in Admin > Settings; the env var overrides that. # - TREK_PLACES_ENABLED=false # Optional. Place search (suggestions, full search, category buttons, Road trip search, import geocoding, offline downloads, and the OpenStreetMap ways and horse routes Tours reads) asks the TREK Places API at https://places.liketrek.com by default, so the server makes outbound requests to that host. Set false to search the way it did before 4.3.0 (OpenStreetMap, or your Google/Amap key) and send nothing there. No switch in the admin panel on purpose: whether searches leave the instance is decided here. (default: true) # - TREK_PLACES_URL=https://places.liketrek.com # Optional. Base URL of a copy of the Places API you run yourself; it has to answer the same /v1 API. Read from configuration rather than typed by a user, so an address on your LAN or Docker network works without ALLOW_INTERNAL_NETWORK. (default: https://places.liketrek.com) +# - TREK_SERVICES=off # Optional. Places search identifies this installation with a key it registers by itself on first use. off sends no key; searches then use the shared pool. (default: auto) +# - TREK_SERVICES_KEY= # Optional. A key issued for this installation; it wins over the stored one and turns self-registration off. # - PLACES_API_KEY= # Optional. Google Maps API key (Places API (New) enabled) for place search, photos, details and Google transit. Overrides the key set in Admin > Settings > API Keys, whose field then shows this variable read-only. # - GOOGLE_LIST_DATA_BASE= # Optional. HTTP(S) base URL of a list-data service. Pasted URLs beginning with this base are imported directly; unset keeps the Google flow. # - AMAP_API_KEY= # Optional. Amap (高德地图) Web 服务 key for place search and geocoding inside mainland China. Overrides the key set in Admin > Settings > API Keys. A Web 端 (JS API) key is a different credential and is rejected with INVALID_USER_KEY. diff --git a/server/tests/unit/app-config/config-templates.test.ts b/server/tests/unit/app-config/config-templates.test.ts index f47e91cb3..382a4bc69 100644 --- a/server/tests/unit/app-config/config-templates.test.ts +++ b/server/tests/unit/app-config/config-templates.test.ts @@ -151,3 +151,29 @@ describe('the Web Push keys in the templates', () => { expect(helmConfigMap).not.toContain(name); }); }); + +describe('the TREK services switches in the templates', () => { + // The installation registers itself by default; an operator who wants it + // off, or who was issued a key, has to find the names where they look. + it('.env.example and docker-compose.yml document the switch and the key', () => { + for (const name of ['TREK_SERVICES', 'TREK_SERVICES_KEY']) { + expect(envExample).toContain(`# ${name}=`); + expect(compose).toContain(`# - ${name}=`); + } + expect(envExample).toContain('# TREK_SERVICES_HOSTS='); + }); + + it('the Helm ConfigMap passes the switch and the hosts, the Secret carries the key', () => { + for (const name of ['TREK_SERVICES', 'TREK_SERVICES_HOSTS']) { + expect(helmValues).toContain(`# ${name}:`); + expect(helmConfigMap).toContain(`${name}: {{ .Values.env.${name} | quote }}`); + } + const name = 'TREK_SERVICES_KEY'; + expect(helmValues).toContain(` ${name}: ""`); + expect(helmSecret).toContain(`${name}: {{ .Values.secretEnv.${name} | b64enc | quote }}`); + expect(helmSecret).toContain(`${name}: {{ .Values.secretEnv.${name} | quote }}`); + expect(helmDeployment).toContain(`- name: ${name}\n valueFrom:\n secretKeyRef:`); + expect(helmDeployment).toContain(`key: ${name}\n optional: true`); + expect(helmConfigMap).not.toContain(name); + }); +}); diff --git a/wiki/Environment-Variables.md b/wiki/Environment-Variables.md index 07889942c..efeb72de2 100644 --- a/wiki/Environment-Variables.md +++ b/wiki/Environment-Variables.md @@ -385,14 +385,17 @@ To get a key: create a free account at [unsplash.com/developers](https://unsplas ## Place Search (TREK Places API) -TREK's own place index, the [TREK Places API](TREK-Places-API), answers the suggestions and, together with OpenStreetMap, the full search in the place form, the category buttons on the trip map, the Road trip search along the drive, import geocoding and the offline download of a trip's surroundings. It needs no key, it is on by default, and there is no switch for it in the admin panel: whether searches leave the instance is set here. +TREK's own place index, the [TREK Places API](TREK-Places-API), answers the suggestions and, together with OpenStreetMap, the full search in the place form, the category buttons on the trip map, the Road trip search along the drive, import geocoding and the offline download of a trip's surroundings. It needs no key to enter, it is on by default, and there is no switch for it in the admin panel: whether searches leave the instance is set here. | Variable | Description | Default | |-----------------------|-------------|---------| | `TREK_PLACES_ENABLED` | Set to `false` to stop asking the index. Search then works as it did before 4.3.0: OpenStreetMap on an install without a key, the keyed provider (Google or Amap) when one is set, the Overpass mirrors for the category buttons and for the OpenStreetMap ways and horse routes Tours reads, and no places downloaded for offline search. It is a boolean switch like the others on this page: `false`, `0`, `off` and `no` in any casing switch it off, a value that is not boolean-like aborts startup, and unset or blank leaves the index on. | on | | `TREK_PLACES_URL` | Base URL of a copy of the service you run yourself; it has to answer the same `/v1` API. Unset or blank uses the public service. A trailing slash is stripped, and a value that is not a full URL aborts startup. It is configuration rather than user input and is not run through the SSRF guard, so an address on your LAN or Docker network works without `ALLOW_INTERNAL_NETWORK`. | `https://places.liketrek.com` | +| `TREK_SERVICES` | `auto` lets the installation register itself with the TREK services on first use and keep its key in the database; `off` sends no key, and searches use the shared pool. See [Installation key and daily allowance](TREK-Places-API#installation-key-and-daily-allowance). | `auto` | +| `TREK_SERVICES_KEY` | A key issued to you for this installation. Wins over the stored key and turns self-registration off. A value that is not a key aborts startup. | none | +| `TREK_SERVICES_HOSTS` | Comma-separated hosts that receive the installation key over https. | `places.liketrek.com` | -On Helm both go under `env:` in `values.yaml`. The chart passes `TREK_PLACES_ENABLED` through whenever it is set at all, so an unquoted `false` or `--set env.TREK_PLACES_ENABLED=false` reaches the container as well. +On Helm these go under `env:` in `values.yaml`, except `TREK_SERVICES_KEY`, which goes under `secretEnv:`. The chart passes `TREK_PLACES_ENABLED` through whenever it is set at all, so an unquoted `false` or `--set env.TREK_PLACES_ENABLED=false` reaches the container as well. --- diff --git a/wiki/TREK-Places-API.md b/wiki/TREK-Places-API.md index 547c545a6..b75514fc4 100644 --- a/wiki/TREK-Places-API.md +++ b/wiki/TREK-Places-API.md @@ -1,6 +1,6 @@ # TREK Places API -The TREK Places API is TREK's own place index. It answers place search, the suggestions under the search box, the details of a place picked from it, the category buttons on the map and the geocoding behind imports, with no API key, no quota and no account. In the app it is called the **TREK API**, and a result that came from it carries a **TREK** mark. +The TREK Places API is TREK's own place index. It answers place search, the suggestions under the search box, the details of a place picked from it, the category buttons on the map and the geocoding behind imports, with no API key to enter and no account. Every installation gets a fair daily allowance, counted by the number of requests only. In the app it is called the **TREK API**, and a result that came from it carries a **TREK** mark. It does not replace OpenStreetMap. A search asks both and shows their results together, because each is good at what the other lacks: the index is strongest on businesses such as restaurants, shops and hotels, and OpenStreetMap is where the temples, bridges, viewpoints and stations are. How the two meet in the search box is described in [Places and Search](Places-and-Search). @@ -63,6 +63,22 @@ What the index returns may be kept. That is what lets TREK store a place you pic The OpenStreetMap layers are kept apart from the place rows and are joined only when an answer is put together, so the share-alike terms of the ODbL stay with the OpenStreetMap data and do not spread to the rest of the index. The service lists all of this at `/v1/attribution`. The name TREK Places API describes the interface, not the origin of the data, and it is not endorsed by the Overture Maps Foundation or the OpenStreetMap Foundation. +## Installation key and daily allowance + +On its first search an installation registers itself with the service in the background: it solves a small proof of work (a few seconds on a Raspberry Pi) and receives a key, which TREK keeps encrypted in its database and renews on its own after 60 of its 90 days. Nobody clicks anything, and the first searches do not wait for it; until the key is there, requests go out the way they always did and are answered from a shared pool. + +The key carries a random installation id and nothing else: no address, no host name, no user. It lets the service give each installation its own daily allowance instead of one pool per network, and it is sent only to the hosts in `TREK_SERVICES_HOSTS` (`places.liketrek.com` by default), never to a copy you run yourself or anywhere else. + +**Admin → Settings → API Keys** shows on the card how this installation stands: connected, setting up its key, on the shared pool, switched off or revoked, with today's use, what is left and when the count starts again. **New identity** drops the key and asks for a new one; use it after cloning an installation onto a second machine, or after the key was revoked. Counting happens per installation id only and is deleted after two days; search terms and coordinates are never logged. + +| Variable | What it does | +|---|---| +| `TREK_SERVICES` | `auto` (default) registers on first use; `off` sends no key, and searches use the shared pool | +| `TREK_SERVICES_KEY` | A key issued to you for this installation. It wins over the stored one, and the installation never registers by itself | +| `TREK_SERVICES_HOSTS` | Comma-separated hosts that receive the key over https | + +An installation pointed at its own copy with `TREK_PLACES_URL`, or with `TREK_PLACES_ENABLED=false`, never registers. + ## What leaves your instance Every request goes out from your TREK server, never from a browser, so the service sees your server's address and nobody else's. @@ -79,10 +95,12 @@ Every request goes out from your TREK server, never from a browser, so the servi | The map view as a box, grown to a 0.05 degree grid | Tours horse routes | | The id of a ski area | Tours ski piste router. No coordinate goes along: the service learns which area a planner loaded, never where anyone clicked. | | An `X-TREK-Instance` header | Every request | +| A `User-Agent` of `TREK/` | Every request | +| The installation key as an `Authorization` header | Every request to a host in `TREK_SERVICES_HOSTS`, once the installation has one | The header carries an opaque token derived from your instance's own address, so the service can rate-limit each instance on its own instead of everyone behind one IP. Set `APP_URL` (or `ALLOWED_ORIGINS`): without either, the token is derived from the port alone, and two unconfigured installs on the same port share one rate-limit bucket. -Who is searching never goes along. No user, account, session, cookie or trip id is sent, and neither is the language TREK is set to or the one picked under **Place names** (see [Language of place names](Places-and-Search#language-of-place-names)). The service's own front page states that queries are not logged, that requests are counted per rate-limit bucket and nothing else, and that the instance token is not stored. +Who is searching never goes along. No user, account, session, cookie or trip id is sent, and neither is the language TREK is set to or the one picked under **Place names** (see [Language of place names](Places-and-Search#language-of-place-names)). The service's own front page states that queries are not logged, that requests are counted per installation and nothing else, and that the instance token is not stored. The requests use Node's default HTTP client, so an outbound proxy set with `HTTPS_PROXY` applies to them, and `NO_PROXY` can exempt the service's host. The official image already turns Node's environment proxy on; a source install needs `NODE_USE_ENV_PROXY=1` as well. See [Environment Variables](Environment-Variables#outbound-https-proxy). @@ -125,6 +143,7 @@ The address is read from your own configuration and is not a URL a user can type |---|---| | `TREK_PLACES_ENABLED` | Whether the index is asked at all | | `TREK_PLACES_URL` | Which copy of the index is asked | +| `TREK_SERVICES`, `TREK_SERVICES_KEY`, `TREK_SERVICES_HOSTS` | The installation key, see [Installation key and daily allowance](#installation-key-and-daily-allowance) | | `NOMINATIM_URL` | The OpenStreetMap half of the full search, right-click reverse geocoding, OpenStreetMap place details and import geocoding | | `OVERPASS_URL`, `OVERPASS_TIMEOUT_MS` | The Overpass mirrors behind the category buttons, the Road trip search and the ways and horse routes of Tours when the index has no answer |