trailofbits-buttercup/guides/MANUAL_SETUP.md

Manual Setup Guide

This guide provides detailed manual setup instructions for the Buttercup CRS system. If you prefer automated setup, use make setup-local instead.

Prerequisites

Before starting manual setup, ensure you have the following dependencies installed:

System Packages

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install -y make curl git

# RHEL/CentOS/Fedora  
sudo yum install -y make curl git
# or
sudo dnf install -y make curl git

# MacOS
brew install make curl git

Docker

curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
# Log out and back in for group changes to take effect

kubectl

curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
sudo install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl

Helm

curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash

Minikube

curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64
sudo install minikube-linux-amd64 /usr/local/bin/minikube

Git LFS (for some tests)

sudo apt-get install git-lfs
git lfs install

Manual Configuration

1. Create configuration file:

cp deployment/env.template deployment/env

2. Configure the environment file (deployment/env):

Look at the comments in the deployment/env.template for how to set variables.

External SigNoz Configuration

If you want to use an external SigNoz instance instead of the default local deployment, you can configure custom OpenTelemetry settings:

1. Disable local SigNoz deployment:

# In deployment/env
export DEPLOY_SIGNOZ=false

2. Configure external OTEL endpoint:

# In deployment/env
export OTEL_ENDPOINT="https://your-signoz-instance.com"
export OTEL_PROTOCOL="http"  # or "grpc"
export OTEL_TOKEN="your-otel-token"  # optional

Start Services Manually

# Start services manually
cd deployment && make up

# Port forward manually
kubectl port-forward -n crs service/buttercup-ui 31323:1323

# Test manually
./orchestrator/scripts/task_crs.sh

Verification

After setup, verify your installation by running:

make status

Troubleshooting

Common Manual Setup Issues

1. Docker permission issues:

sudo usermod -aG docker $USER
# Log out and back in

2. Minikube won't start:

minikube delete
minikube start --driver=docker

3. Helm chart issues:

helm repo update
helm dependency update deployment/k8s/

For additional troubleshooting, see the Quick Reference Guide.