Password management: .env.example pattern, gitignore, documentation

.env.example

@@ -1,17 +1,16 @@
 # PostgreSQL (internal, for Nextcloud)
-# Users: nextcloud (DB owner), oc_admin (app user — password in config.php)
 POSTGRES_DB=nextcloud
 POSTGRES_USER=nextcloud
-POSTGRES_PASSWORD=t824DwiP5F3uXwU1Z8EL
+POSTGRES_PASSWORD=CHANGE_ME
 
 # Remote PostgreSQL (for external access)
 PG_DB=remotedb
 PG_USER=remoteuser
-PG_PASSWORD=yhkrsCBCpiTIIIGQy8Qu
+PG_PASSWORD=CHANGE_ME
 
 # Nextcloud
 NEXTCLOUD_ADMIN_USER=admin
-NEXTCLOUD_ADMIN_PASSWORD=CHANGE_THIS_PASSWORD
+NEXTCLOUD_ADMIN_PASSWORD=CHANGE_ME
 TRUSTED_DOMAINS=nc.home localhost 127.0.0.1
 
 # Gitea

.gitignore

@@ -0,0 +1,2 @@
+.env
+.session-*

23may2026-Q-server-prototype.md

@@ -111,6 +111,32 @@ Remote access:
 opencode configuration (`opencode.json`):
 - Permission model asks before executing bash or accessing external directories.
 
+## Password management
+
+Secrets are managed through a `.env.example` pattern:
+
+- **`.env.example`** (tracked in git) — template with placeholder values documenting all required variables.
+- **`.env`** (gitignored) — the actual secrets file on hector. A copy lives at `~/selfhosted2/.env` on agge.
+- **Docker volumes** — runtime copies of passwords baked into PostgreSQL and Nextcloud config on first deploy.
+
+Password sources:
+
+| Variable | User | Where it's used | Where it's stored |
+|----------|------|-----------------|-------------------|
+| `POSTGRES_PASSWORD` | `nextcloud` | Internal PostgreSQL (DB owner) | `.env`, Docker volume |
+| — | `oc_admin` | Nextcloud app DB user | Nextcloud config.php |
+| `PG_PASSWORD` | `remoteuser` | Remote PostgreSQL | `.env`, Docker volume |
+| `NEXTCLOUD_ADMIN_PASSWORD` | `admin` | Nextcloud web login | `.env`, personal password manager |
+
+To rotate a password:
+1. Generate: `openssl rand -base64 18`
+2. Update `.env` and sync to agge
+3. Run `ALTER USER <user> WITH PASSWORD '<new>';` in the appropriate PostgreSQL container
+4. If rotating the Nextcloud app user, also update `config.php` via `sed`
+5. Restart the service if needed
+
+Do not commit `.env` to git. The `.env.example` template is the only password-related file that belongs in the repo.
+
 # Session history
 
 **Session ses_21ab382baffej8OpnTkrmaG5UA** — initial prototype deployment: Docker files written, containers configured, applications deployed and verified.
@@ -124,5 +150,6 @@ opencode configuration (`opencode.json`):
 6. Docker port bindings on agge were restricted to `10.0.0.2` to enforce tunnel-only access.
 7. UFW on agge was configured to allow WireGuard UDP 51820.
 8. Gitea SSH port 2222 was added to nginx's TCP stream proxies on raspen, enabling git push over SSH through the VPN tunnel.
+9. PostgreSQL passwords were rotated to strong values; `.env` replaced with `.env.example` pattern and gitignored; password management documented.
 
 All services confirmed operational: Gitea (HTTP 200), Nextcloud (HTTP 302), PostgreSQL (port open), and static page (HTTP 200).