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. The bundled database listens on the Docker network but is not published to the host; remote databases use the port in DB_URL.

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.
  • Always requires the shared secret header X-GoodMem-Metrics-Key; a missing or incorrect value returns HTTP 401.
  • Configure the secret via one of:
    • Server flag --metrics-scrape-secret
    • System property goodmem.metrics.secret
    • Environment variable 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 drives readiness, gRPC health, and background job processor intake. The drain operation stops new work; there is currently no resume operation, so restart the server to return it to READY.

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. The --ocr-render-engine and --page-render-parallelism flags apply only to PDF rendering. Memory page images for Microsoft Office documents (DOCX, PPTX, XLSX) are produced by a built-in Java renderer that does not use PDFium or PDFBox; it renders at the same 200 DPI and is unaffected by those flags. Office extraction and XLSX page-image rendering are instead governed by the process-wide OOXML safety policy. 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. The help output lists flags and defaults; use the table above for environment-variable names.

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.
• If the current binary is not writable, goodmem upgrade stages the replacement in the system temporary directory and prints the command needed to move it into place.

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, TLS, and optional server overrides such as GOODMEM_OOXML_LIMITS_JSON 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.

Restart an installer-managed server

Use goodmem system stop and goodmem system start to manage an entire installed profile. To restart only the GoodMem server container while leaving its bundled database running, first find the profile name with goodmem system info, then run:

docker restart goodmem-<profile-name>-server

Running docker compose --profile local-db up -d from the installation directory starts stopped services and reconciles configuration, but it does not guarantee that an unchanged, running server container is restarted.

Change an installer-managed OOXML policy in that .env file, then stop and start the profile for the new process-wide policy to take effect. See OOXML Processing Limits for the schema and rollout steps.

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.