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:
    • CLI 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.

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.json — Written by goodmem init when --save-config is enabled (default). Stores the server address, API key, user ID, and initialization timestamp.
• ~/.goodmem/bin/ — Fallback location used by goodmem upgrade when the original install path is not writable; the updater drops platform-specific binaries here.

Installer Footprint

Running the installer (curl -s https://get.goodmem.ai | bash) creates ~/.goodmem with Docker assets and helper scripts:

• .env — Environment file containing database connection variables and the DATA_DIR_BASE path.
• 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.debug.yml — Optional overlay that exposes the database port in debug mode.
• docker-compose.macos-arm64.yml — Overlay automatically added on Apple Silicon hosts for volume performance tweaks.
• reinstall.sh / uninstall.sh — Maintenance scripts fetched from the installer CDN.
• data/pgdata/ — Local PostgreSQL data directory created when you choose the bundled database.

The installer honors the GOODMEM_DIR environment variable. If you set it, all of the files above are rooted in that custom location instead of ~/.goodmem.

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.