GUAC Configuration Guide

This document provides an overview of the guac.yaml configuration file used in GUAC deployments. It describes each configuration option, its default value, and scenarios where you might want to change it.

The values below are the ones shipped in guac.yaml, which is tuned for the demo compose setup. Several of them differ from the defaults compiled into the binaries, which apply when you run a GUAC binary without a config file. Where the two differ, the binary default is called out alongside the entry.

The keys that currently differ:

Key	guac.yaml	Binary default
pubsub-addr	nats://localhost:4222	nats://127.0.0.1:4222
interval	20m	5m
gql-debug	true	false
db-address	not set	postgres://guac:guac@0.0.0.0:5432/guac?sslmode=disable

Setting configuration values

Every key on this page can be set three ways. In order of precedence, highest first:

1. A command-line flag, named after the key with a -- prefix — for example --db-address.
2. An environment variable, named GUAC_ followed by the key uppercased with dashes replaced by underscores — for example GUAC_DB_ADDRESS. This is usually the most convenient way to configure GUAC in containers.
3. The guac.yaml file, using the key as written on this page.

So the db-address key, the --db-address flag and the GUAC_DB_ADDRESS environment variable all set the same value, and a flag passed on the command line overrides both of the others:

# these three are equivalent
guacgql --db-address "postgres://guac:guac@localhost:5432/guac?sslmode=disable"

GUAC_DB_ADDRESS="postgres://guac:guac@localhost:5432/guac?sslmode=disable" guacgql

# or in guac.yaml:
#   db-address: postgres://guac:guac@localhost:5432/guac?sslmode=disable

Database Configuration

Ent config

• db-driver: postgres
  • Description: The driver used for the database connection.
  • When to Change: Modify if you need to switch to a different database driver.
• db-address: postgres://guac:guac@postgres:5432/guac?sslmode=disable
  • Description: The address for connecting to the PostgreSQL database. This key is not present in guac.yaml; the value shown is the one used by the compose setup. The binary default is postgres://guac:guac@0.0.0.0:5432/guac?sslmode=disable.
  • When to Change: Update if your database address changes or if you need to enable/disable SSL.
• db-migrate: true
  • Description: Indicates whether database migration is enabled.
  • When to Change: Set to false if you do not want automatic database migration.

Pub/Sub Configuration

• pubsub-addr: nats://localhost:4222 (binary default: nats://127.0.0.1:4222)
  • Description: The address of the NATS server for pub/sub messaging.
  • When to Change: Update if your NATS server is hosted elsewhere or uses a different port.
• publish-to-queue: true
  • Description: Whether to publish messages to the queue.
  • When to Change: Set to false if you do not want to use queue-based messaging.

Blob Store Configuration

• blob-addr: file:///tmp/blobstore?no_tmp_dir=true
  • Description: The address of the blob store.
  • When to Change: Change to use a different storage backend, such as AWS S3 or Google Cloud Storage (examples).

Certifier Configuration

• interval: 20m (binary default: 5m)
  • Description: The interval at which the certifier runs.
  • When to Change: Adjust based on how frequently you need certification checks.
• last-scan: 4
  • Description: The number of hours since the last scan was run. A value of 0 means the scan will run on all packages/sources.
  • When to Change: Set to 0 for a full scan or adjust based on your scanning frequency needs.
• certifier-batch-size: 60000
  • Description: The batch size for the package pagination query.
  • When to Change: Modify to optimize performance based on your system’s capabilities.
• certifier-latency: ""
  • Description: Artificial latency to throttle the certifier.
  • When to Change: Use to introduce delays if needed to manage load.
• add-vuln-metadata: false
  • Description: Whether the OSV certifier adds severity and other metadata to the vulnerabilities it ingests.
  • When to Change: Set to true if you want vulnerability metadata alongside the vulnerabilities themselves.

• Deps.dev Configuration

  • deps-dev-latency: ""
  • Description: Artificial latency to throttle deps.dev.
  • When to Change: Adjust if you need to manage load on deps.dev queries.

Ingestion Configuration

• add-vuln-on-ingest: false
  • Description: Whether to query vulnerabilities during ingestion.
  • When to Change: Set to true if you want to automatically check for vulnerabilities during data ingestion.
• add-license-on-ingest: false
  • Description: Whether to query licenses during ingestion.
  • When to Change: Set to true if you want to automatically check for licenses during data ingestion.
• add-eol-on-ingest: false
  • Description: Whether to query endoflife.date for end-of-life data during ingestion.
  • When to Change: Set to true if you want to automatically check for EOL data during data ingestion.
• add-depsdev-on-ingest: false
  • Description: Whether to query deps.dev for scorecards and source association data during ingestion.
  • When to Change: Set to true if you want to automatically collect deps.dev metadata during data ingestion.

Collector-Subscriber Configuration

• csub-addr: localhost:2782
  • Description: The address for the Collector-Subscriber service.
  • When to Change: Update if your Collector-Subscriber service is hosted on a different address.
• csub-listen-port: 2782
  • Description: The port on which the Collector-Subscriber service listens.
  • When to Change: Change if your Collector-Subscriber service uses a different port.

GraphQL Configuration

• gql-backend: keyvalue
  • Description: The backend used for the GraphQL server.
  • When to Change: Modify if using a different backend for GraphQL.
• gql-listen-port: 8080
  • Description: The port on which the GraphQL server listens.
  • When to Change: Change if your GraphQL server uses a different port.
• gql-debug: true (binary default: false)
  • Description: Whether to enable debug mode for the GraphQL server.
  • When to Change: Set to false in production environments for security.
• gql-addr: http://localhost:8080/query
  • Description: The address of the GraphQL server.
  • When to Change: Update if your GraphQL server is hosted elsewhere.

REST API Configuration

• rest-api-server-port: 8081
  • Description: The port on which the API server listens.
  • When to Change: Change if your API server uses a different port.

Collector Configuration

• service-poll: true
  • Description: Whether the collector should poll services.
  • When to Change: Set to false if polling is not required.
• use-csub: true
  • Description: Whether to use the Collector-Subscriber service.
  • When to Change: Set to false if not using Collector-Subscriber.

Logging Configuration

• log-level: Info
  • Description: The logging level for the application.
  • When to Change: Adjust to Debug for more detailed logs during development or troubleshooting.

Metrics and Observability Configuration

For detailed documentation, see Metrics and Observability.

• enable-prometheus: false
  • Description: Whether to enable the Prometheus metrics endpoint (/metrics).
  • When to Change: Set to true to enable scraping metrics by Prometheus or compatible collectors.
• prometheus-port: 9091
  • Description: The port on which the Prometheus metrics server listens for standalone collectors and ingestors.
  • When to Change: Change if port 9091 conflicts with another service in your environment.
• enable-otel: false
  • Description: Whether to enable OpenTelemetry metrics and distributed tracing.
  • When to Change: Set to true to export traces and metrics to an OpenTelemetry collector.
• OpenTelemetry Environment Variables:
  • OTEL_EXPORTER_OTLP_ENDPOINT: Address of the OTel collector endpoint (e.g. http://localhost:4317).
  • OTEL_EXPORTER_OTLP_INSECURE: Set to true to allow insecure (non-TLS) gRPC connections.
  • OTEL_SERVICE_NAME: Service name identifier attached to exported traces and metrics.