Development environment setup

Try GUAC with a dev container

A development container is a quick way to try GUAC without installing its Go build tools locally. The GUAC repository includes a .devcontainer/devcontainer.json configuration that downloads a published GUAC image and starts the services using Docker Compose.

Choose either of these environments:

GitHub Codespaces: Open the GUAC repository, select Code, Codespaces, then Create codespace on main.
VS Code locally: Install Docker and the Dev Containers extension. Clone https://github.com/guacsec/guac.git, open the repository in VS Code, and select Dev Containers: Reopen in Container from the Command Palette.

The first startup pulls the GUAC release image. On each container start, its postStartCommand launches the in-memory backend using docker-compose.yml and container_files/mem.yaml. Wait for the terminal message GUAC is ready.

Open the forwarded 8080 port to access the GraphQL playground. The REST API is exposed on port 8081, and you can check its health at http://localhost:8081/healthz from inside the dev container (or through the forwarded port).

From a terminal in the GUAC repository, you can manage the services:

# Show service status
docker compose -f docker-compose.yml -f container_files/mem.yaml ps

# Follow logs when debugging startup
docker compose -f docker-compose.yml -f container_files/mem.yaml logs -f

# Stop the services when you are done
docker compose -f docker-compose.yml -f container_files/mem.yaml down

The default backend is in memory, so it is intended for experimentation, not durable storage. For a PostgreSQL-backed setup, replace container_files/mem.yaml with container_files/ent.yaml in the devcontainer’s postStartCommand before reopening the container. See the GraphQL guide for query and ingestion examples.

Install tools for manual development

Ensure you have the following tools installed in your environment

Once you have cloned the repository, make check-tools verifies that the required tools are present and tells you which are missing.

Setting up your git repositories

Clone GUAC to a local directory:

git clone https://github.com/guacsec/guac.git

Optional: If you want test data to use, clone GUAC’s test data:
```
git clone https://github.com/guacsec/guac-data.git
```
Go to your GUAC directory (the rest of the steps need to be done from this directory):
```
cd guac
```

Building the binaries

All steps assume you are in the root of the guac directory.

Build the binaries using make:
```
make
```
Alternatively, you may also build/run the binaries directly with go:
```
go run ./cmd/guacgql --gql-debug
```

Building containers

All steps assume you are in the root of the guac directory.

Build the binaries using make:
```
make container
```

Making changes to GraphQL (optional)

When making changes to the graphQL schema and client operations, you will need to run the graphQL generation code:
```
make generate
```

Making changes to protos (optional)

When making changes to any protocol buffers (e.g. for the [collectsub service]), you will need to run code generation:
```
make proto
```

Creating a PR

Whenever you are ready to contribute, feel free to open a pull request to the repository! Whenever you are updating your branch, please be sure to rebase instead of creating a merge commit.

Next steps

Check out more information about becoming a contributor in the contributor guide.