hosting: random Postgres password on fresh installs

Replaces the historical default `POSTGRES_PASSWORD=arcsecond_docker` with
a per-install URL-safe-base64 value (~256 bits of entropy) generated at
first `arcsecond hosting setup`. Existing `.env` files are never
overwritten — the value Postgres baked in at first container boot must
stay in sync with `.env`, so write_env_file preserves any pre-existing
key as it always has.

Defense in depth: bind the db (5432) and broker (6379) services to
127.0.0.1 only. Operators can still `psql -h localhost` from the host;
the backend reaches both over the internal Docker network. Anything on
the LAN is firewalled out.

Includes docs/rotate-postgres-password.md for the three pioneer installs
already running with the old default — Postgres only reads
POSTGRES_PASSWORD on first init, so rotating requires both an ALTER USER
and an .env edit.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: onekiloparsec

arcsecond/hosting/docker/docker-compose.yml

@@ -8,8 +8,12 @@ services:
     image: postgres:16
     container_name: arcsecond-db
     restart: unless-stopped
+    # Bind to localhost only — the backend container reaches the DB over the
+    # internal Docker network (hostname `arcsecond-db`), and operators can
+    # still run `psql -h localhost` / `pg_dump` from the host. Anything on the
+    # LAN is firewalled out.
     ports:
-      - "5432:5432"
+      - "127.0.0.1:5432:5432"
     volumes:
       - arcsecond_postgres_data:/var/lib/postgresql/data
     env_file:
@@ -21,8 +25,10 @@ services:
     image: redis:7.4
     container_name: arcsecond-broker
     restart: unless-stopped
+    # Localhost-only as well — Redis with no auth on a LAN-exposed port is a
+    # well-known foot-gun. Backend reaches it over the Docker network.
     ports:
-      - "6379:6379"
+      - "127.0.0.1:6379:6379"
 
   # Arcsecond backend (REST APIs). Can be used for API calls and external pipelines, scripts etc.
   backend:

arcsecond/hosting/local.py

@@ -5,12 +5,14 @@
 import click
 
 from arcsecond.options import basic_options
-from .utils import _get_encryption_key, _get_random_secret_key
+from .utils import _get_encryption_key, _get_random_postgres_password, _get_random_secret_key
 
 ENV_FILENAME = ".env"
 
+# Stable across installs — operators connect with this username when running
+# manual psql / pg_dump commands. The actual security boundary is the password
+# (generated per-install) and the network exposure (localhost-only).
 POSTGRES_USER = "arcsecond_docker"
-POSTGRES_PASSWORD = "arcsecond_docker"
 POSTGRES_DB = "arcsecond_docker"
 
 
@@ -39,7 +41,11 @@ def _required_env_values():
         "FIELD_ENCRYPTION_KEY": _get_encryption_key(),
         "SHARED_DATA_PATH": prompt_shared_data_path(),
         "POSTGRES_USER": POSTGRES_USER,
-        "POSTGRES_PASSWORD": POSTGRES_PASSWORD,
+        # Per-install random; never overwritten on repeat runs (see write_env_file).
+        # Postgres only reads this on first container boot to bootstrap the role,
+        # so the .env value and the live DB password must stay in sync — that's
+        # why we never regenerate it after the .env exists.
+        "POSTGRES_PASSWORD": _get_random_postgres_password(),
         "POSTGRES_DB": POSTGRES_DB,
     }
 

arcsecond/hosting/utils.py

@@ -11,3 +11,14 @@ def _get_random_secret_key():
 
 def _get_encryption_key():
     return base64.urlsafe_b64encode(os.urandom(32)).decode('UTF8')
+
+
+def _get_random_postgres_password():
+    """Generate a strong, shell- and URL-safe Postgres password.
+
+    Uses URL-safe base64 (``[A-Za-z0-9_-]``) so the value never needs
+    quoting in the .env file or any future connection string. 32 random
+    bytes → 43 chars, ~256 bits of entropy. Trailing '=' padding is
+    stripped because it triggers shell parsing weirdness in some setups.
+    """
+    return base64.urlsafe_b64encode(os.urandom(32)).decode('UTF8').rstrip('=')

docs/rotate-postgres-password.md

@@ -0,0 +1,78 @@
+# Rotating the Postgres password on an existing self-hosted install
+
+Until version 3.10, `arcsecond hosting setup` wrote a default Postgres password
+(`arcsecond_docker`) into `.env`. New installs now generate a per-install
+random password automatically, but **existing installs keep the original weak
+password until you rotate it manually** — Postgres only reads
+`POSTGRES_PASSWORD` at first container boot to bootstrap the role, so changing
+the value in `.env` after the fact does nothing on its own.
+
+This guide rotates the password in three coordinated places: the live database
+role, the `.env` file, and the running containers.
+
+## 1. Pick a new password
+
+```bash
+NEW_PG_PASSWORD=$(python3 -c "import os, base64; print(base64.urlsafe_b64encode(os.urandom(32)).decode().rstrip('='))")
+echo "$NEW_PG_PASSWORD"
+```
+
+Keep this in your shell session — you will paste it into two places.
+
+## 2. Change the password in the live DB
+
+```bash
+docker exec -it arcsecond-db psql \
+  -U arcsecond_docker \
+  -d arcsecond_docker \
+  -c "ALTER USER arcsecond_docker WITH PASSWORD '$NEW_PG_PASSWORD';"
+```
+
+The role's password is now updated in Postgres. The backend container is
+holding open connections that authenticated under the old password — they will
+keep working until restart, which is fine; we restart in step 4.
+
+## 3. Update `.env`
+
+Replace the `POSTGRES_PASSWORD=...` line in your `.env` (next to
+`docker-compose.yml`) with the new value. Keep the same `POSTGRES_USER` and
+`POSTGRES_DB` values — only the password changes.
+
+```bash
+sed -i.bak "s/^POSTGRES_PASSWORD=.*/POSTGRES_PASSWORD=$NEW_PG_PASSWORD/" .env
+```
+
+(macOS `sed` writes a `.env.bak` backup. Inspect, then delete the backup
+once you've confirmed the rewrite worked.)
+
+## 4. Restart the stack
+
+```bash
+docker compose restart backend worker beat
+```
+
+Backend, worker, and beat re-read `.env` and pick up the new password. The
+`db` container itself does **not** need a restart — its data was already
+updated in step 2, and a `db` restart would not re-read `POSTGRES_PASSWORD`
+anyway (it only does so on first init of an empty volume).
+
+## 5. Verify
+
+```bash
+docker compose logs --tail 50 backend | grep -i 'database'
+curl -fsS http://localhost:8800/healthcheck/
+```
+
+If `healthcheck/` returns 200, you're done.
+
+## File permissions
+
+While you're in `.env`, lock it down so other local users can't read it:
+
+```bash
+chmod 600 .env
+```
+
+The file holds the Postgres password, the Django `SECRET_KEY`, the field
+encryption key, and the JWT signing keys. None of them are useful to an
+attacker on their own, but defense in depth is cheap.

tests/test_hosting_local.py

@@ -7,6 +7,7 @@ def test_write_env_file_includes_jwt_signing_keys(tmp_path, monkeypatch):
     monkeypatch.chdir(tmp_path)
     monkeypatch.setattr(local, "_get_random_secret_key", lambda: "test-secret")
     monkeypatch.setattr(local, "_get_encryption_key", lambda: "test-encryption")
+    monkeypatch.setattr(local, "_get_random_postgres_password", lambda: "test-pg-password")
     monkeypatch.setattr(local, "prompt_shared_data_path", lambda: "/tmp/shared-data")
 
     local.write_env_file()
@@ -17,12 +18,40 @@ def test_write_env_file_includes_jwt_signing_keys(tmp_path, monkeypatch):
     assert "AGENT_JWT_SIGNING_KEY=test-secret" in env_contents
     assert "FIELD_ENCRYPTION_KEY=test-encryption" in env_contents
     assert 'SHARED_DATA_PATH="/tmp/shared-data"' in env_contents
+    # Fresh installs get a per-install random password, never the historical default.
+    assert "POSTGRES_PASSWORD=test-pg-password" in env_contents
+    assert "POSTGRES_PASSWORD=arcsecond_docker" not in env_contents
+
+
+def test_write_env_file_generates_strong_password_on_fresh_install(tmp_path, monkeypatch):
+    """End-to-end: when the helper is not stubbed, the generated value
+    actually has the entropy / character set we expect."""
+    monkeypatch.chdir(tmp_path)
+    monkeypatch.setattr(local, "_get_random_secret_key", lambda: "x")
+    monkeypatch.setattr(local, "_get_encryption_key", lambda: "x")
+    monkeypatch.setattr(local, "prompt_shared_data_path", lambda: "/tmp/p")
+
+    local.write_env_file()
+
+    env_contents = (Path(tmp_path) / ".env").read_text(encoding="utf-8")
+    pg_line = next(line for line in env_contents.splitlines() if line.startswith("POSTGRES_PASSWORD="))
+    pg_password = pg_line.split("=", 1)[1]
+    assert pg_password != "arcsecond_docker"
+    assert len(pg_password) >= 32, f"too weak: {pg_password!r}"
+    # URL-safe base64 alphabet: never needs quoting in shells or connection strings.
+    allowed = set("abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-_")
+    assert set(pg_password) <= allowed
 
 
 def test_write_env_file_preserves_existing_values_and_adds_missing(tmp_path, monkeypatch):
+    """Critical for upgrades: rewriting POSTGRES_PASSWORD in .env after
+    Postgres has been initialized would lock the operator out — the live
+    DB still uses the original password baked in at first boot. Existing
+    keys must never be touched."""
     monkeypatch.chdir(tmp_path)
     monkeypatch.setattr(local, "_get_random_secret_key", lambda: "generated-secret")
     monkeypatch.setattr(local, "_get_encryption_key", lambda: "generated-encryption")
+    monkeypatch.setattr(local, "_get_random_postgres_password", lambda: "freshly-generated-but-unused")
     monkeypatch.setattr(local, "prompt_shared_data_path", lambda: "/tmp/generated-shared")
 
     env_path = Path(tmp_path) / ".env"
@@ -31,6 +60,7 @@ def test_write_env_file_preserves_existing_values_and_adds_missing(tmp_path, mon
             [
                 "SECRET_KEY=existing-secret",
                 "POSTGRES_USER=existing-user",
+                "POSTGRES_PASSWORD=existing-pg-password",
                 "",
             ]
         ),
@@ -42,11 +72,13 @@ def test_write_env_file_preserves_existing_values_and_adds_missing(tmp_path, mon
 
     assert "SECRET_KEY=existing-secret" in env_contents
     assert "POSTGRES_USER=existing-user" in env_contents
+    # The pre-existing Postgres password is preserved verbatim — never overwritten.
+    assert "POSTGRES_PASSWORD=existing-pg-password" in env_contents
+    assert "POSTGRES_PASSWORD=freshly-generated-but-unused" not in env_contents
     assert "AUTH_JWT_SIGNING_KEY=generated-secret" in env_contents
     assert "AGENT_JWT_SIGNING_KEY=generated-secret" in env_contents
     assert "FIELD_ENCRYPTION_KEY=generated-encryption" in env_contents
     assert 'SHARED_DATA_PATH="/tmp/generated-shared"' in env_contents
-    assert "POSTGRES_PASSWORD=arcsecond_docker" in env_contents
     assert "POSTGRES_DB=arcsecond_docker" in env_contents