readme for portable server

README.md

@@ -34,6 +34,17 @@ To connect a client to a second server instance, override its gRPC endpoint:
 GRPC_ENDPOINT='http://[::1]:50052' cargo watch-client
 ```
 
+## Server database builds
+
+| Build | PostgreSQL | Intended use |
+|---|---|---|
+| `cargo build --release --package server` | Upstream embedded | Development and compatible Linux targets |
+| `nix build '.?submodules=1#portable-server'` | Musl embedded | Portable x86-64 Linux deployment |
+| `cargo build --release --package server --no-default-features` | External | Separately managed PostgreSQL |
+
+All builds contain and apply the SQLx migrations. See
+[`server/README.md`](server/README.md) for configuration.
+
 Client with tracing:
 
 ```

packaging/musl/README.md

@@ -2,8 +2,7 @@
 
 This build produces one `x86_64` Linux server executable with embedded
 PostgreSQL. The Rust program is statically linked against musl. PostgreSQL is
-compiled against musl without optional host-library dependencies and is stored
-inside the executable by `postgresql_embedded`.
+compiled against musl and stored inside the executable.
 
 PostgreSQL itself remains dynamically loadable so the `btree_gist` extension
 used by the migrations works. Its musl loader is included in the embedded
@@ -17,17 +16,25 @@ Build directly through the repository's Nix flake:
 nix build '.?submodules=1#portable-server'
 ```
 
-The `submodules=1` flag includes the workspace's nested Rust repositories. The
-artifact is available as `result/bin/server`. The derivation initializes a
-temporary cluster, creates `btree_gist`, sets the timezone to `UTC`, and checks
-that the final Rust executable has no ELF interpreter.
+Output: `result/bin/server`.
 
 The resulting executable is intended for 64-bit Linux kernels. Run it normally:
 
 ```sh
+cp .env_template .env
+# Replace JWT_SECRET in .env before starting.
 ./result/bin/server server
 ```
 
+Required: `JWT_SECRET`.
+
+Optional: `KOMP_AC_POSTGRES_DIR` selects the persistent PostgreSQL directory.
+`DATABASE_URL` and `RUST_DB_*` are not required in embedded mode.
+
+The portable binary can still use a separately managed PostgreSQL server at
+runtime. Set `RUST_DB_MODE=external` and provide `RUST_DB_USER`,
+`RUST_DB_PASSWORD`, `RUST_DB_HOST`, `RUST_DB_PORT` and `RUST_DB_NAME`.
+
 Use the external PostgreSQL build on NixOS when preferred:
 
 ```sh