Server Runtime FootprintCopy Anchor Link

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

Network EndpointsCopy Anchor Link

• 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 endpointCopy Anchor Link

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

Trace exportCopy Anchor Link

GoodMem exports server traces through OpenTelemetry. Export is off by default. The OTel metrics and log exporter settings do not connect the existing Micrometer metrics or application logs. See OpenTelemetry support and Export traces from GoodMem.

Lifecycle & Health EndpointsCopy Anchor Link

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 FlagsCopy Anchor Link

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 ConfigurationCopy Anchor Link

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 FootprintCopy Anchor Link

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 to run the server with linux/amd64 emulation.
• .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.
• <profile-name>_goodmem-scratch — Docker-managed named volume mounted at the server's /tmp. This volume lives in Docker's storage, outside the installation directory.

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.

Document-ingestion scratch storageCopy Anchor Link

GoodMem uses temporary disk files during document processing to reduce memory use. The installer configures a Docker named volume for these files automatically:

services:
  server:
    volumes:
      - goodmem-scratch:/tmp

volumes:
  goodmem-scratch:
    driver: local

goodmem-scratch is a volume name, and /tmp is a path inside the container. Docker manages the storage; you do not need to create or mount a host /tmp directory. Each installation profile has its own volume, and each ingestion attempt uses a separate directory within it.

These defaults use disk storage. If you customize Docker's storage or volume settings, keep scratch on disk rather than tmpfs or a RAM disk. To see the volume's location, run docker volume inspect <profile-name>_goodmem-scratch.

Ingestion files live under /tmp/goodmem-ingestion/attempt-<UUID>/. The volume also holds temporary files created by PDF and font libraries.

Cleanup and capacityCopy Anchor Link

Allow space for several jobs at once: expanded documents and rendered images can be much larger than the uploaded files. GoodMem has no global scratch quota, so monitor free disk space. Parsing, rendering, and filesystem caching still use memory; disk storage does not eliminate RAM requirements.

GoodMem removes each attempt directory when processing finishes or fails. After a crash, it cleans up abandoned attempts when processing resumes, though some library-created files may remain. Restarting a profile retains the volume; uninstalling with --yes-delete-data removes it. Scratch files do not need backup because source documents remain in PostgreSQL.

For the standard named volume, leftover scratch can be cleared while the profile is stopped:

goodmem system stop --profile-name <profile-name>
docker volume rm <profile-name>_goodmem-scratch
goodmem system start --profile-name <profile-name>

Run these commands against the same Docker instance used for installation.

Custom deploymentsCopy Anchor Link

When running the server outside the installer, configure the mount shown above or provide your own disk-backed temporary directory. It must be writable by the server's user, UID 65532 in the published image. If you set -Djava.io.tmpdir through JAVA_TOOL_OPTIONS, mount storage at that path instead of /tmp. For existing installer-managed deployments, follow the upgrade procedure.

PostgreSQL source storageCopy Anchor Link

Uploaded source documents remain in PostgreSQL. New sources are stored uncompressed so GoodMem can read them in small pieces. Allow for increased database disk use for compressible files such as CSV.

Existing compressed sources remain readable without conversion. Reprocessing or downloading them requires PostgreSQL memory proportional to the source size and can use temporary database disk space, even for a short download range. For teams that repeatedly process large older sources, the repository's source-storage maintenance guide describes an optional conversion. Use the guide and script from your deployed release.

Database migrations run automatically at startup. If you supply a custom migration directory at /usr/share/goodmem/db/migration, update it to match the server release or remove the override to use the bundled migrations.

Restart an installer-managed serverCopy Anchor Link

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

Compose up -d applies resolved configuration, but it can retain an unchanged running container. Use the profile's stop/start commands when a restart is required.

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.