feat: offer PostgreSQL alongside default SQLite with verified backend switching

.env.example

@@ -1,15 +1,36 @@
 # MeshCore Analyzer — Environment Configuration
-# Copy to .env and customize. All values have sensible defaults.
+# New installation: copy to .env and customize. Existing installation: merge
+# missing keys into your private .env; do not replace paths or credentials.
 #
 # This file is read by BOTH docker compose AND manage.sh — one source of truth.
 # manage.sh setup negotiates and updates only these production managed keys:
 #   PROD_DATA_DIR, PROD_HTTP_PORT, PROD_HTTPS_PORT, PROD_MQTT_PORT, DISABLE_MOSQUITTO
 # Each environment keeps config + data together in one directory:
-#   ~/meshcore-data/config.json, meshcore.db, Caddyfile, theme.json
-#   ~/meshcore-staging-data/config.json, meshcore.db, Caddyfile
+#   ~/meshcore-data/config.json, Caddyfile, theme.json, queues and backups
+#   ~/meshcore-staging-data/config.json, Caddyfile, queues and backups
+# With PostgreSQL selected, its separate persistent directory is not a logical backup.
+
+# --- Storage choice ---
+# SQLite is the default and needs no database service or PostgreSQL credentials.
+# setup offers PostgreSQL explicitly. Once installed, storage-selection.json in
+# the shared state directory is authoritative; ordinary updates keep it.
+# To change engines, use the verified offline storage switch in docs/storage.md.
+# Optional PostgreSQL credentials/directories: merge .env.postgres.example.
+# Do not replace an existing .env or regenerate existing database passwords.
+# Optional container state subdirectory, shared by setup/server/ingestor:
+# CORESCOPE_STATE_DIR=/app/data
+
+# --- Example deployment (docker-compose.example.yml only) ---
+# For upgrades, point DATA_DIR at the existing state directory BEFORE bootstrap.
+# PROD_DATA_DIR and STAGING_DATA_DIR below do not control the example variant.
+DATA_DIR=./data
+HTTP_PORT=80
+# CORESCOPE_IMAGE=<reviewed image tag or digest matching this checkout>
+# Bundled Caddy forwards port 80 to the Go server on 3000 by default. If you
+# explicitly set DISABLE_CADDY=true, your proxy/port mapping must use port 3000.
 
 # --- Production ---
-# Data directory (database, theme, etc.)
+# State directory (config, theme, queues and backups)
 # Default: ~/meshcore-data
 # Used by: docker compose, manage.sh
 PROD_DATA_DIR=~/meshcore-data

.env.postgres.example

@@ -0,0 +1,21 @@
+# OPTIONAL PostgreSQL settings — merge into your existing private .env.
+# Base Compose files need none of these. Add the matching .postgres.yml override.
+# Use a different persistent directory for each production/staging instance.
+# Generate a DIFFERENT value for each blank field: openssl rand -hex 32
+# Keep .env private. Hexadecimal passwords can be safely embedded in the
+# generated container URLs; the initializer enforces at least 32 hex digits.
+# These roles are created only when PostgreSQL's data directory is empty.
+# Editing these values afterward does not change existing database passwords.
+POSTGRES_ADMIN_PASSWORD=
+CORESCOPE_OWNER_PASSWORD=
+CORESCOPE_READER_PASSWORD=
+CORESCOPE_WRITER_PASSWORD=
+CORESCOPE_ACCOUNTS_PASSWORD=
+CORESCOPE_CHANNELS_PASSWORD=
+PROD_POSTGRES_DATA_DIR=~/corescope-postgres
+STAGING_POSTGRES_DATA_DIR=~/corescope-staging-postgres
+# docker-compose.example.yml uses this local default instead:
+POSTGRES_DATA_DIR=./postgres-data
+# Existing installations keep their recorded backend on update. Changing engines
+# requires the offline storage switch in docs/storage.md. Never mount two database
+# servers on one persistent directory.