From d62812274b36c39f92576ce1708a452f55815db3 Mon Sep 17 00:00:00 2001
From: Piotr Oleszczyk <piotr@oleszczyk.eu>
Date: Sat, 28 Feb 2026 20:24:38 +0100
Subject: [PATCH] fix(docs): correct Debian 13 deployment steps

- Switch to Node.js 24 LTS via nvm
- Install uv to /usr/local/bin via UV_INSTALL_DIR for system-wide access
- Install pnpm as standalone binary from GitHub releases (not corepack
  shim which breaks when copied out of its nvm directory)
- Add libpq5 to apt deps (psycopg3 requires libpq at runtime)
- Add GEMINI_API_KEY and GEMINI_MODEL to backend .env template
- Add ORIGIN to frontend .env.production (SvelteKit CSRF protection)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 README.md                         |  2 +-
 docs/DEPLOYMENT.md                | 37 +++++++++++++++++++++++++------
 systemd/innercontext-node.service |  2 +-
 3 files changed, 32 insertions(+), 9 deletions(-)

diff --git a/README.md b/README.md
index a83d516..0e2b13d 100644
--- a/README.md
+++ b/README.md
@@ -33,7 +33,7 @@ API docs available at `http://localhost:8000/docs`.
 
 ## Frontend quick start
 
-**Requirements:** Node.js 22+, [pnpm](https://pnpm.io/)
+**Requirements:** Node.js 24 LTS+, [pnpm](https://pnpm.io/)
 
 ```bash
 cd frontend
diff --git a/docs/DEPLOYMENT.md b/docs/DEPLOYMENT.md
index fe6f0dc..36084bd 100644
--- a/docs/DEPLOYMENT.md
+++ b/docs/DEPLOYMENT.md
@@ -53,23 +53,43 @@ pct enter 200   # or SSH into the container
 
 ```bash
 apt update && apt upgrade -y
-apt install -y git nginx curl ca-certificates gnupg lsb-release
+apt install -y git nginx curl ca-certificates gnupg lsb-release libpq5
 ```
 
 ### Python 3.12+ + uv
 
 ```bash
 apt install -y python3 python3-venv
-curl -LsSf https://astral.sh/uv/install.sh | sh
-source $HOME/.local/bin/env   # or re-login
+curl -LsSf https://astral.sh/uv/install.sh | UV_INSTALL_DIR=/usr/local/bin sh
 ```
 
-### Node.js 22 + pnpm
+Installing to `/usr/local/bin` makes `uv` available system-wide (required for `sudo -u innercontext uv sync`).
+
+### Node.js 24 LTS + pnpm
 
 ```bash
-curl -fsSL https://deb.nodesource.com/setup_22.x | bash -
-apt install -y nodejs
-npm install -g pnpm
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.4/install.sh | bash
+. "$HOME/.nvm/nvm.sh"
+nvm install 24
+```
+
+Copy `node` to `/usr/local/bin` so it is accessible system-wide
+(required for `sudo -u innercontext` and for systemd).
+Symlinking into `/root/.nvm/` won't work — other users can't traverse `/root/`.
+Use `--remove-destination` to replace any existing symlink with a real file:
+
+```bash
+cp --remove-destination "$(nvm which current)" /usr/local/bin/node
+```
+
+Install pnpm as a standalone binary from GitHub releases — self-contained,
+no wrapper scripts, works system-wide. Do **not** use `corepack enable pnpm`
+(the shim requires its nvm directory structure and breaks when copied/linked):
+
+```bash
+curl -fsSL "https://github.com/pnpm/pnpm/releases/latest/download/pnpm-linux-x64" \
+  -o /usr/local/bin/pnpm
+chmod 755 /usr/local/bin/pnpm
 ```
 
 ### Application user
@@ -132,6 +152,8 @@ sudo -u innercontext uv sync
 ```bash
 cat > /opt/innercontext/backend/.env <<'EOF'
 DATABASE_URL=postgresql+psycopg://innercontext:change-me@<pg-lxc-ip>/innercontext
+GEMINI_API_KEY=your-gemini-api-key
+# GEMINI_MODEL=gemini-flash-latest  # optional, this is the default
 EOF
 chmod 600 /opt/innercontext/backend/.env
 chown innercontext:innercontext /opt/innercontext/backend/.env
@@ -183,6 +205,7 @@ cd /opt/innercontext/frontend
 ```bash
 cat > /opt/innercontext/frontend/.env.production <<'EOF'
 PUBLIC_API_BASE=http://innercontext.lan/api
+ORIGIN=http://innercontext.lan
 EOF
 chmod 600 /opt/innercontext/frontend/.env.production
 chown innercontext:innercontext /opt/innercontext/frontend/.env.production
diff --git a/systemd/innercontext-node.service b/systemd/innercontext-node.service
index 6f82e10..785d5dd 100644
--- a/systemd/innercontext-node.service
+++ b/systemd/innercontext-node.service
@@ -10,7 +10,7 @@ WorkingDirectory=/opt/innercontext/frontend
 Environment=PORT=3000
 Environment=HOST=127.0.0.1
 EnvironmentFile=/opt/innercontext/frontend/.env.production
-ExecStart=/usr/bin/node /opt/innercontext/frontend/build/index.js
+ExecStart=/usr/local/bin/node /opt/innercontext/frontend/build/index.js
 Restart=on-failure
 RestartSec=5