diff --git a/server/.env.example b/server/.env.example index 0541a6dc9..158e18338 100644 --- a/server/.env.example +++ b/server/.env.example @@ -71,7 +71,6 @@ DEMO_MODE=false # Demo mode: resets data hourly # TREK_PLACES_ENABLED=false # Whether place search asks the TREK Places API at https://places.liketrek.com: suggestions, the full search, the category buttons on the map, the Road trip search along the route, import geocoding and offline downloads. It is on by default and has no switch in the admin panel, because whether searches leave the instance is a deployment decision. Set false to search the way it did before 4.3.0 (OpenStreetMap, or your Google/Amap key) and send nothing to that host. (default: true) # TREK_PLACES_URL=https://places.liketrek.com # 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) -# PLACES_API_BASE= # Send the Google Places calls through an egress proxy, a cache or a gateway that speaks the same API instead of places.googleapis.com directly. Unset: Google's own endpoints. # PLACES_API_KEY= # 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. The value never reaches the browser. # AMAP_API_KEY= # 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. @@ -80,9 +79,6 @@ DEMO_MODE=false # Demo mode: resets data hourly # TRANSIT_API_URL=https://api.transitous.org # Base URL of the transit routing API the server proxies to. Point it at your own MOTIS instance to keep transit searches off third-party servers. A trailing slash is stripped. (default: https://api.transitous.org) -# MAPBOX_ACCESS_TOKEN= # Only read with TREK_MANAGED: the public Mapbox token (pk.*) a managed instance ships with, in place of the one in Admin > Settings. It reaches the browser by design, so never a secret token. -# CARTO_API_KEY= # Only read with TREK_MANAGED: the CARTO basemap key a managed instance ships with. Without a key the CARTO tiles carry a watermark. Public like the Mapbox token. - # TREK_PLACE_PHOTO_DIR= # Directory for cached Google place photos, e.g. a dedicated volume. Unset, they live in uploads/photos/google. Read once at startup. (default: uploads/photos/google) # KITINERARY_EXTRACTOR_PATH= # Full path to the kitinerary-extractor binary. Unset, TREK searches /usr/lib/*/libexec/kf6/ and then PATH; the official image pins it. Set it to run a newer extractor than your distribution packages — the version in use is in the startup log and in GET /api/admin/system-info. (default: auto-detected) @@ -120,8 +116,6 @@ DEMO_MODE=false # Demo mode: resets data hourly # TREK_PLUGIN_LOG_BURST=50 # Log lines a plugin may write back to back before the per-second limit applies. (default: 50) # TREK_PLUGIN_LOG_PER_SEC=10 # Sustained log lines per second per plugin. (default: 10) -# TREK_MANAGED=false # Set by hosting providers that administer an instance for its owner. It withholds the settings the provider controls from the instance admin and requires ENCRYPTION_KEY. Leave it unset on a self-hosted install. (default: false) - # UNSPLASH_ACCESS_KEY= # Optional Unsplash Access Key for trip-cover and place-image search. Without one, TREK uses Unsplash's unauthenticated endpoint, which some datacenter/VPS IPs get blocked from (#1449). Get a free key at unsplash.com/developers. Overrides any key set per-admin in Admin > Settings. Can also be configured there instead of here. # Initial admin account — ONLY applied on the first boot, when the database has no diff --git a/server/src/app-config/README.md b/server/src/app-config/README.md index 84317c975..a7834c034 100644 --- a/server/src/app-config/README.md +++ b/server/src/app-config/README.md @@ -117,7 +117,10 @@ variable to a token means moving its field from `derive.ts` to `server/.env.example` names every variable the schema validates except the few in `env-reference.test.ts`'s `NOT_OPERATOR_SETTINGS`; that test fails on -drift in either direction. +drift in either direction. The managed-hosting switches (TREK_MANAGED and the +keys only a managed install sets: MAPBOX_ACCESS_TOKEN, CARTO_API_KEY, +PLACES_API_BASE) are on that list on purpose and stay out of every public +reference. ## Classification: boot-stable vs runtime-toggled diff --git a/server/tests/unit/app-config/env-reference.test.ts b/server/tests/unit/app-config/env-reference.test.ts index baae1f295..7cfba15c7 100644 --- a/server/tests/unit/app-config/env-reference.test.ts +++ b/server/tests/unit/app-config/env-reference.test.ts @@ -12,14 +12,20 @@ import { envSchema } from '../../../src/app-config/env.schema'; const ENV_EXAMPLE = path.join(__dirname, '..', '..', '..', '.env.example'); /** - * Schema entries an operator never sets, with the reason. Everything else in + * Schema entries a self-hoster never sets, with the reason. Everything else in * the schema has a line in .env.example, commented out when it is optional. + * The managed-hosting switches are here on purpose: they stay out of every + * public reference, like TREK_DB_FILE and APP_VERSION. */ const NOT_OPERATOR_SETTINGS: Record = { PATH: 'the OS search path, validated only so the kitinerary probe can resolve its binary', Path: 'the Windows spelling of PATH', APP_VERSION: 'set by the image build; the VERSION file wins over it', TREK_DB_FILE: 'points the Playwright harness at a throwaway database', + TREK_MANAGED: 'managed hosting only, deliberately undocumented for self-hosters', + MAPBOX_ACCESS_TOKEN: 'managed hosting only (read with TREK_MANAGED), deliberately undocumented for self-hosters', + CARTO_API_KEY: 'managed hosting only (read with TREK_MANAGED), deliberately undocumented for self-hosters', + PLACES_API_BASE: "managed hosting's egress gateway for the Places calls, deliberately undocumented for self-hosters", }; /** Every variable named on a `KEY=` line, set or commented out. */