fix: add APP_VERSION fallback and HOST bind address env var (#952 #953) (#955)

* fix: add APP_VERSION fallback and HOST bind env var (#952 #953)

- Read package.json version when APP_VERSION env var is absent so the
  startup banner shows the correct version for source/Proxmox installs
- Add HOST env var to control the HTTP bind address; only applied when
  set so Docker deployments are unaffected (bind-all-interfaces default)
- Parse PORT as Number() so malformed values like '10.0.0.72:3001' fall
  back to 3001 instead of silently misbehaving
- Document HOST in .env.example, Environment-Variables wiki, and
  Install-Proxmox wiki with explicit warnings against using it in Docker

* fix: correct package.json path in APP_VERSION fallback

index.ts sits at server/src/ — one level up reaches server/package.json,
not two (../../ overshot to the repo root where no package.json exists).

server/.env.example

@@ -1,4 +1,5 @@
 PORT=3001 # Port to run the server on
+# HOST=0.0.0.0 # Bind address for the HTTP server. Only set this when running TREK from sources or via the Proxmox community script — never in Docker (the container handles binding).
 NODE_ENV=development # development = development mode; production = production mode
 # ENCRYPTION_KEY=<random-256-bit-hex>  # Separate key for encrypting stored secrets (API keys, MFA, SMTP, OIDC, etc.)
 # Auto-generated and persisted to ./data/.encryption_key if not set.

server/src/db/migrations.ts

@@ -2222,6 +2222,13 @@ function runMigrations(db: Database.Database): void {
         db.prepare("INSERT OR REPLACE INTO app_settings (key, value) VALUES ('whitespace_migration_collision', 'true')").run();
       }
     },
+    () => {
+      db.exec(`CREATE TABLE IF NOT EXISTS schema_version_new (id INTEGER PRIMARY KEY AUTOINCREMENT,version INTEGER NOT NULL)`)
+      db.exec(`INSERT INTO schema_version_new (version) SELECT version FROM schema_version`)
+      db.exec(`DROP TABLE schema_version`)
+      db.exec(`ALTER TABLE schema_version_new RENAME TO schema_version`)
+      db.exec(`UPDATE app_settings SET value = '${process.env.APP_VERSION || '3.0.15'}' WHERE key = 'app_version'`);
+    },
   ];
 
   if (currentVersion < migrations.length) {

server/src/index.ts

@@ -20,8 +20,11 @@ const app = createApp();
 
 import * as scheduler from './scheduler';
 
-const PORT = process.env.PORT || 3001;
-const server = app.listen(PORT, () => {
+const PORT = Number(process.env.PORT) || 3001;
+const HOST = process.env.HOST;
+const APP_VERSION: string = process.env.APP_VERSION || (require('../package.json') as { version: string }).version;
+
+const onListen = () => {
   const { logInfo: sLogInfo, logWarn: sLogWarn } = require('./services/auditLog');
   const LOG_LVL = (process.env.LOG_LEVEL || 'info').toLowerCase();
   const tz = process.env.TZ || Intl.DateTimeFormat().resolvedOptions().timeZone || 'UTC';
@@ -29,7 +32,8 @@ const server = app.listen(PORT, () => {
   const banner = [
     '──────────────────────────────────────',
     '  TREK API started',
-    `  Version      ${process.env.APP_VERSION}`,
+    `  Version      ${APP_VERSION}`,
+    ...(HOST ? [`  Host:        ${HOST}`] : []),
     `  Port:        ${PORT}`,
     `  Environment: ${process.env.NODE_ENV?.toLowerCase() || 'development'}`,
     `  Timezone:    ${tz}`,
@@ -57,7 +61,11 @@ const server = app.listen(PORT, () => {
   import('./websocket').then(({ setupWebSocket }) => {
     setupWebSocket(server);
   });
-});
+};
+
+const server = HOST
+  ? app.listen(PORT, HOST, onListen)
+  : app.listen(PORT, onListen);
 
 // Graceful shutdown
 function shutdown(signal: string): void {

wiki/Environment-Variables.md

@@ -16,6 +16,7 @@ Complete reference for all environment variables TREK reads.
 | Variable | Description | Default |
 |---|---|---|
 | `PORT` | Server port | `3000` |
+| `HOST` | Bind address for the HTTP server (e.g. `127.0.0.1`, `10.0.0.72`). **Source / Proxmox installs only** — do not set this in Docker or any containerized deployment. See note below. | all interfaces |
 | `NODE_ENV` | Environment (`production` / `development`) | `production` |
 | `ENCRYPTION_KEY` | At-rest encryption key — see resolution order below | auto |
 | `TZ` | Timezone for logs, reminders, and cron jobs (e.g. `Europe/Berlin`) | `UTC` |
@@ -25,6 +26,22 @@ Complete reference for all environment variables TREK reads.
 | `ALLOW_INTERNAL_NETWORK` | Allow outbound requests to private/RFC-1918 IPs. Set `true` if Immich or other integrated services are on your local network. Loopback (`127.x`) and link-local (`169.254.x`) addresses remain blocked regardless. | `false` |
 | `APP_URL` | Public base URL (e.g. `https://trek.example.com`). Required when OIDC is enabled — must match the redirect URI registered with your IdP. Also used as the base URL for email notification links. | — |
 
+### `HOST` — Source and Proxmox installs only
+
+By default TREK binds to all network interfaces (`0.0.0.0`), which is the correct behaviour inside a container because Docker handles port exposure at the host level. Setting `HOST` overrides the bind address at the Node.js level.
+
+**When to use it:** only when running TREK directly on a host (git sources or the [Proxmox community script](Install-Proxmox)) and you need to restrict which interface the server listens on — for example, to expose TREK only on a LAN interface while keeping it off the public-facing one.
+
+**Never set `HOST` in Docker, Docker Compose, Helm, or Unraid deployments.** Use Docker's `-p <host-ip>:<host-port>:<container-port>` syntax or your orchestrator's port binding instead.
+
+```
+# .env — source / Proxmox installs only
+HOST=10.0.0.72   # bind only on this LAN interface
+PORT=3001
+```
+
+When `HOST` is set, the startup banner includes a `Host:` line confirming the bound address.
+
 ### `ENCRYPTION_KEY` — Resolution Order
 
 `server/src/config.ts` resolves the encryption key in this order:

wiki/Install-Proxmox.md

@@ -78,6 +78,17 @@ The environment file is located at `/opt/trek/server/.env` inside the container.
 systemctl restart trek
 ```
 
+### Binding to a specific network interface
+
+If your Proxmox host has multiple network interfaces and you want TREK to listen on only one of them, set the `HOST` variable in `/opt/trek/server/.env`:
+
+```
+HOST=10.0.0.72   # bind only on this LAN interface
+PORT=3001
+```
+
+> **Note:** `HOST` is only relevant for source-based and Proxmox installs. Do not use it in Docker or any containerised deployment.
+
 See [Environment-Variables](Environment-Variables) for the full variable reference.
 
 ## Updating