Server Runtime Footprint

Understand which network services GoodMem publishes, how to configure the server, and where supporting files are written on disk.

Network Endpoints

• Port 8080 — REST API served by the embedded Javalin server (default; configurable via --rest-port / GOODMEM_REST_PORT)
• Port 9090 — gRPC API consumed by the CLI and SDKs (default; configurable via --grpc-port / GOODMEM_GRPC_PORT)
• Port 5432 — PostgreSQL database port (exposed only in debug installs)

Both REST and gRPC can run either plaintext or TLS depending on server configuration; see TLS Configuration.

Monitoring endpoint

• GET /metrics — Prometheus scrape endpoint exposed by the REST server.
  • Requires the shared secret header X-GoodMem-Metrics-Key unless explicitly disabled.
  • Configure the secret via one of:
    • Server flag --metrics-scrape-secret
    • Environment variable GOODMEM_METRICS_SECRET
    • System property goodmem.metrics.secret
    • Defaults to goodmem-ambrosia-metrics-token when unset.
  • Return payload is Prometheus’ text exposition format; disable caching when fronting the endpoint with a proxy. Restrict ingress so only the Prometheus server can reach it.

Lifecycle & Health Endpoints

These endpoints reflect the server's lifecycle state and are safe to expose to probes and orchestration tooling.

• GET /livez — Always responds 200 with the current lifecycle state; suitable for liveness checks.
• GET /readyz — Returns 200 only when the lifecycle state is READY, otherwise 503; wire this into readiness probes or load balancer health checks.
• GET /startupz — Returns 200 once the server has finished STARTING; ideal for Kubernetes startup probes.
• grpc.health.v1.Health — The gRPC health service is registered on both the in-process and networked servers and mirrors the lifecycle transitions.
• POST /v1/admin:drain — Triggers drain mode and optionally waits for quiesce at the REST layer (goodmem/server/src/main/java/com/goodmem/rest/AdminServiceRestAdapter.java). The CLI wraps the same RPC via goodmem system drain.

The lifecycle controller now drives readiness, gRPC health, and background job processor intake. Drain and resume controls can be layered on top via ServerLifecycle listeners or new admin RPCs if your deployment requires them.

Server Configuration Flags

Command-line flags take precedence over environment variables. If neither is provided, the default shown below is applied.

For TLS-related flags and defaults, see TLS Configuration.

PDF page rendering for OCR and memory page-image extraction uses 200 DPI by default and is not currently configurable via flags. OCR is optional and not included in the base install. Run the GoodMem OCR add-on service/image and set GOODMEM_OCR_BASE_URL to enable the OCR APIs.

If you explicitly force pdfium, the runtime must satisfy PDFium's requirements: Linux x86_64 plus JVM native access enabled with --enable-native-access=ALL-UNNAMED. In the default auto mode, GoodMem performs that probe at startup and falls back to pdfbox if PDFium is not available.

Use --help or --version for usage information; picocli also renders the environment variable names in the built-in help output.

CLI Configuration

The CLI stores its local state under ~/.goodmem by default.

• ~/.goodmem/config.toml — Stores CLI profiles, the current profile name, server URLs, API keys, and local install metadata.
• ~/.goodmem/bin/ — Fallback location used by goodmem upgrade when the original install path is not writable; the updater drops platform-specific binaries here.

Set GOODMEM_HOME_DIR to move the CLI config directory to a different path.

Installer Footprint

Local installs created by goodmem system install use a per-profile directory under ~/.goodmem/installs/local-docker/<profile-name>/ by default:

• docker-compose.yml — Base stack definition for the server and optional database.
• docker-compose.local-db.yml — Overlay that provisions the bundled PostgreSQL container.
• docker-compose.macos-arm64.yml — Overlay automatically added on Apple Silicon hosts for volume performance tweaks.
• .env — Environment file containing database, image, and TLS settings for that install.
• install-config.json — Metadata that links the local install back to its CLI profile.
• data/pgdata/ — Local PostgreSQL data directory created when you choose the bundled database.

If you install to a custom base directory with goodmem system install --dir <path>, the per-profile install directory is created under that location instead.

With these locations documented, you can confidently point REST clients at the correct base URL, configure gRPC tooling, and manage the files GoodMem places on your workstation or server.