Start a demo GUAC with Docker Compose

If you’d prefer, you can set up GUAC with Kubernetes with the experimental Helm charts provided by Kusari. Note that these helm charts are still experimental and are hosted in a third-party repo and may not be synchronized with the GUAC repo.

This tutorial will walk you through how to deploy a demo-level GUAC, using Docker Compose, so that you get just enough components to complete all the GUAC demos.

Setup video

A video format of these setup instructions is available here:

Table of contents

• Start a demo GUAC with Docker Compose
  • Setup video
  • Prerequisites
  • Optional - Verify images and binaries
  • Step 1: Download GUAC
  • Step 2: Start the GUAC server
    • GUAC Ports
  • Step 3: Start Ingesting Data
  • Step 4: Check that everything is ingesting and running
  • What is running?
  • Next steps

Prerequisites

• Docker
• Docker Compose
• jq

Optional - Verify images and binaries

• Follow Verification of the GUAC images and binaries

Step 1: Download GUAC

1. Download the GUAC CLI guacone binary for your machine’s OS and architecture from the latest GUAC release if you have not already done so. For example:

   • Linux x86_64 : guacone-linux-amd64
   • MacOS x86_64 : guacone-darwin-amd64
   • Windows x86_64 : guacone-windows-amd64.exe

2. Rename the binary to guacone, mark it executable if necessary, and add it to your shell’s path.

3. Download the compose yaml from the latest GUAC release.

4. Optional: If you want test data to use, download and unzip GUAC’s test data.

Step 2: Start the GUAC server

1. From the directory you downloaded the guac-demo-compose.yaml, run:

   docker compose -f guac-demo-compose.yaml up --force-recreate
   

2. Verify that GUAC is running:

   docker compose ls --filter "name=guac"
   

   You should see:

   NAME                STATUS              CONFIG FILES
   guac                running(7)          /Users/lumb/go/src/github.com/guacsec/guac/docker-compose.yml
   

   If you don’t see the above, run docker compose down and try starting up GUAC again. Because Docker Compose caches the containers used, the unclean state can cause issues.

GUAC Ports

Port Number	GUAC Component	Note
8080	GraphQL server	To see the GraphQL playground, visit http://localhost:8080
2782	Collector Subscriber	This service is notified whenever you run a collector, such as guacone collect files below. Then subscribers can collect more data on any packages ingested.

Step 3: Start Ingesting Data

You can run the guacone collect files ingestion command to load data into your GUAC deployment. For example we can ingest the sample guac-data data. However, you may ingest what you wish to here instead.

guacone collect files guac-data-main/docs

Switch back to the compose window and you will soon see that the OSV certifier recognized the new packages and is looking up vulnerability information for them.

Step 4: Check that everything is ingesting and running

Run:

curl 'http://localhost:8080/query' -s -X POST -H 'content-type: application/json' \
  --data '{
    "query": "{ packages(pkgSpec: {}) { type } }"
  }' | jq

You should see the types of all the packages ingested

{
  "data": {
    "packages": [
      {
        "type": "oci"
      },
...

What is running?

Congratulations, you are now running a full GUAC deployment! Taking a look at the docker-compose.yaml we can see what is actually running:

• Collector-Subscriber: Helps communicate to the collectors when additional information is needed.
• GraphQL Server: Serves GUAC GraphQL queries and stores the data. As the in-memory backend is used, no separate backend is needed behind the server.
• Deps.dev Collector: Gathers further information from Deps.dev for supported packages.
• OSV Certifier: Gathers OSV vulnerability information from osv.dev about packages.

Next steps

This compose configuration is suitable to leave running in an environment that is accessible to your environment for the GUAC demos and further GUAC ingestion, discovery, analysis, and evaluation. Keep in mind that the in-memory backend is not persistent. Explore the types of collectors available under the guacone collect command and see what will work for your build, ingestion, and SBOM workflow. These collectors can be run as another service that watches a location for new documents to ingest. If you’re curious about the various GUAC components and what they do, see How GUAC components work together.