### Setup Frontend Development Environment

Source: https://github.com/buggregator/docs/blob/master/docs/cookbook/docker-install.md

Clone the Buggregator frontend repository, install dependencies, and start the development server.

```bash
git clone git@github.com:buggregator/frontend.git
cd frontend
yarn install
yarn dev
```

--------------------------------

### Start Trap Server with Composer

Source: https://github.com/buggregator/docs/blob/master/docs/trap/getting-started.md

Start the Trap debugging server after installing it via Composer.

```bash
vendor/bin/trap
```

--------------------------------

### Example Prompt for AI Assistant

Source: https://github.com/buggregator/docs/blob/master/docs/llm.md

An example of how to prompt an AI assistant to use the Buggregator documentation index for setup assistance with a Laravel project.

```text
Read https://docs.buggregator.dev/llms.txt and help me set up Buggregator with my Laravel project
```

--------------------------------

### Start Trap Server with Default Settings

Source: https://github.com/buggregator/docs/blob/master/docs/trap/commands.md

Starts the Trap server using all default ports and the console sender. This is the simplest way to get Trap running.

```bash
vendor/bin/trap run
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/buggregator/docs/blob/master/docs/contributing/docs.md

Install the necessary Node.js dependencies for the documentation project after cloning the repository.

```bash
npm install
```

--------------------------------

### Start the Documentation Development Server

Source: https://github.com/buggregator/docs/blob/master/docs/contributing/docs.md

Run this command to start a local development server and preview the documentation site.

```bash
npm run docs:dev
```

--------------------------------

### Start Buggregator with Docker Compose

Source: https://github.com/buggregator/docs/blob/master/docs/cookbook/docker-install.md

Start the Buggregator server and example services using Docker Compose. Access the application at http://localhost:8000.

```bash
make run
```

--------------------------------

### Install Frontend Dependencies

Source: https://github.com/buggregator/docs/blob/master/docs/contributing/frontend.md

Install project dependencies using Yarn.

```bash
yarn install
```

--------------------------------

### Generic PHP Project Monolog Setup

Source: https://github.com/buggregator/docs/blob/master/docs/config/monolog.md

Install Monolog via Composer and configure a Logger instance with SocketHandler and JsonFormatter to send logs to Buggregator.

```bash
composer require monolog/monolog
```

```php
<?php

use Monolog\Logger;
use Monolog\Handler\SocketHandler;
use Monolog\Formatter\JsonFormatter;

$log = new Logger('buggregator');
$handler = new SocketHandler('127.0.0.1:9913');
$handler->setFormatter(new JsonFormatter());
$log->pushHandler($handler);

$log->warning('Foo');
$log->error('Bar');
```

--------------------------------

### Install XHProf Extension

Source: https://github.com/buggregator/docs/blob/master/docs/config/xhprof.md

Install the XHProf PHP extension using PECL. Ensure the pear channel is updated first.

```bash
pear channel-update pear.php.net
pecl install xhprof
```

--------------------------------

### Run Frontend Development Server

Source: https://github.com/buggregator/docs/blob/master/docs/contributing/frontend.md

Start the local development server for the frontend application.

```bash
yarn dev
```

--------------------------------

### Start Trap Server with Web UI

Source: https://github.com/buggregator/docs/blob/master/docs/trap/getting-started.md

Start the Trap server with the --ui flag to enable the web interface, accessible at http://127.0.0.1:8000.

```bash
./trap --ui
```

```bash
vendor/bin/trap --ui
```

--------------------------------

### Run Buggregator Standalone Binary on Linux

Source: https://github.com/buggregator/docs/blob/master/docs/getting-started.md

Download and execute the Buggregator binary for Linux (amd64). This is the recommended method for quick setup without installation.

```bash
curl -sL https://github.com/buggregator/server/releases/latest/download/buggregator-linux-amd64 -o buggregator \
  && chmod +x buggregator \
  && ./buggregator
```

--------------------------------

### Clone Frontend Repository

Source: https://github.com/buggregator/docs/blob/master/docs/contributing/frontend.md

Clone the frontend repository to start development.

```bash
git clone https://github.com/buggregator/frontend.git
```

--------------------------------

### Full Buggregator Server Configuration Example

Source: https://github.com/buggregator/docs/blob/master/docs/config/server.md

A comprehensive example of the buggregator.yaml file, demonstrating settings for HTTP server, database, storage, TCP servers, modules, metrics, authentication, MCP, webhooks, and projects. Supports environment variable substitution.

```yaml
# HTTP server
server:
  addr: ${HTTP_ADDR::8000}
  cors_origins:
    - "*"

# Database (SQLite)
database:
  driver: sqlite
  dsn: ${DATABASE_DSN::memory:}       # ":memory:" or file path like "data.db"

# Attachment storage (SMTP attachments, HTTP dump files)
storage:
  mode: ${STORAGE_MODE:memory}        # "memory" or "filesystem"
  path: ${STORAGE_PATH:./storage}     # Directory for filesystem mode

# TCP servers
tcp:
  smtp:
    addr: ${SMTP_ADDR::1025}
  monolog:
    addr: ${MONOLOG_ADDR::9913}
  var-dumper:
    addr: ${VAR_DUMPER_ADDR::9912}

# Enable/disable modules
modules:
  sentry: true
  ray: true
  var-dump: true
  inspector: true
  monolog: true
  smtp: true
  sms: true
  http-dump: true
  profiler: true

# Prometheus metrics
metrics:
  enabled: ${METRICS_ENABLED:false}
  addr: ${METRICS_ADDR:}              # Separate server, e.g. ":9090". Empty = serve on main HTTP server.

# Authentication (OAuth2/OIDC)
# auth:
#   enabled: false
#   provider: oidc
#   provider_url: https://xxx.us.auth0.com
#   client_id: xxx
#   client_secret: xxx
#   callback_url: http://localhost:8000/auth/sso/callback
#   scopes: openid,email,profile
#   jwt_secret: my-secret-key

# MCP (Model Context Protocol) for AI assistants
# mcp:
#   enabled: false
#   transport: socket                  # "socket" or "http"
#   socket_path: /tmp/buggregator-mcp.sock
#   addr: :8001                        # For HTTP transport
#   auth_token:                        # Bearer token for HTTP transport

# Webhooks
# webhooks:
#   - event: "*"
#     url: https://slack.example.com/webhook
#     headers:
#       Authorization: "Bearer token"
#     verify_ssl: false
#     retry: true

# Pre-defined projects
# projects:
#   - key: my-app
#     name: My Application

```

--------------------------------

### Install Buggregator Using Existing Secrets

Source: https://github.com/buggregator/docs/blob/master/docs/config/helm-chart.md

Demonstrates how to create Kubernetes secrets for sensitive values and reference them during Helm chart installation for enhanced security.

```bash
# Create secrets
kubectl create secret generic buggregator-auth \
  --from-literal=client-id=YOUR_CLIENT_ID \
  --from-literal=client-secret=YOUR_CLIENT_SECRET

# Reference them in values
helm install buggregator oci://ghcr.io/buggregator/helm-chart/buggregator \
  --set auth.existingSecret=buggregator-auth
```

--------------------------------

### Run Buggregator Binary

Source: https://github.com/buggregator/docs/blob/master/docs/cookbook/manual-install.md

Execute the downloaded Buggregator binary to start the server. Access the UI at http://127.0.0.1:8000.

```bash
./buggregator
```

--------------------------------

### Start Trap Server with Web UI Enabled

Source: https://github.com/buggregator/docs/blob/master/docs/trap/commands.md

Starts the Trap server and enables the web-based user interface. The UI provides a visual way to inspect debug data.

```bash
vendor/bin/trap run --ui
```

--------------------------------

### Configure and Use Profiler in PHP

Source: https://github.com/buggregator/docs/blob/master/docs/config/xhprof.md

Set up a WebStorage with a native HTTP client and a Buggregator endpoint. Start and end profiling sessions using the Profiler class.

```php
use SpiralPackages\Profiler\Profiler;
use SpiralPackages\Profiler\DriverFactory;
use SpiralPackages\Profiler\Storage\WebStorage;
use Symfony\Component\HttpClient\NativeHttpClient;

$storage = new WebStorage(
    new NativeHttpClient(),
    'http://127.0.0.1/api/profiler/store',
);

$profiler = new Profiler(
    storage: $storage,
    driver: DriverFactory::detect(),
    appName: 'My app',
    tags: ['env' => 'local'],
);

$profiler->start();

// Your code here

$profiler->end();
```

--------------------------------

### Install Buggregator with SSO

Source: https://github.com/buggregator/docs/blob/master/docs/config/helm-chart.md

Installs the Buggregator Helm chart with SSO enabled. Requires specifying the authentication provider and related credentials.

```bash
helm install buggregator oci://ghcr.io/buggregator/helm-chart/buggregator \
  --set auth.enabled=true \
  --set auth.provider=auth0 \
  --set auth.providerUrl=https://your-tenant.auth0.com \
  --set auth.clientId=YOUR_CLIENT_ID \
  --set auth.clientSecret=YOUR_CLIENT_SECRET \
  --set auth.callbackUrl=https://buggregator.example.com/auth/sso/callback \
  --set auth.jwtSecret=YOUR_JWT_SECRET
```

--------------------------------

### Run Buggregator with Docker

Source: https://github.com/buggregator/docs/blob/master/docs/getting-started.md

Start Buggregator using a Docker container, mapping essential ports for various debugging features. Ensure Docker is installed and running.

```bash
docker run --pull always \
  -p 127.0.0.1:8000:8000 \
  -p 127.0.0.1:1025:1025 \
  -p 127.0.0.1:9912:9912 \
  -p 127.0.0.1:9913:9913 \
  ghcr.io/buggregator/server:latest
```

--------------------------------

### Install Symfony VarDumper

Source: https://github.com/buggregator/docs/blob/master/docs/config/var-dumper.md

Install the Symfony VarDumper component using Composer. This is a development dependency.

```bash
composer require --dev symfony/var-dumper
```

--------------------------------

### Install Trap via Composer

Source: https://github.com/buggregator/docs/blob/master/docs/trap/getting-started.md

Install Trap as a development dependency in your PHP project using Composer.

```bash
composer require --dev buggregator/trap -W
```

--------------------------------

### Install Buggregator with Ingress

Source: https://github.com/buggregator/docs/blob/master/docs/config/helm-chart.md

Installs the Buggregator Helm chart and exposes it via an Ingress controller. Requires specifying the Ingress class and host configuration.

```bash
helm install buggregator oci://ghcr.io/buggregator/helm-chart/buggregator \
  --set ingress.enabled=true \
  --set ingress.className=nginx \
  --set 'ingress.hosts[0].host=buggregator.example.com' \
  --set 'ingress.hosts[0].paths[0].path=/' \
  --set 'ingress.hosts[0].paths[0].pathType=Prefix'
```

--------------------------------

### Run Docker Container with Config File

Source: https://github.com/buggregator/docs/blob/master/docs/config/server.md

Example of running the Buggregator Docker container, mapping a configuration file and ports.

```bash
docker run --pull always \
  -p 127.0.0.1:8000:8000 \
  -p 127.0.0.1:1025:1025 \
  -v ./buggregator.yaml:/buggregator.yaml \
  ghcr.io/buggregator/server:latest
```

--------------------------------

### Run Docker Container with Environment Variables

Source: https://github.com/buggregator/docs/blob/master/docs/config/server.md

Example of running the Buggregator Docker container, mapping ports and setting environment variables for configuration.

```bash
docker run --pull always \
  -p 127.0.0.1:8000:8000 \
  -p 127.0.0.1:1025:1025 \
  -e DATABASE_DSN=data.db \
  -e METRICS_ENABLED=true \
  -v ./data:/data \
  ghcr.io/buggregator/server:latest
```

--------------------------------

### Install Buggregator Standalone

Source: https://github.com/buggregator/docs/blob/master/docs/config/helm-chart.md

Installs the Buggregator Helm chart in a standalone mode using embedded SQLite. No external dependencies are required.

```bash
helm install buggregator oci://ghcr.io/buggregator/helm-chart/buggregator
```

--------------------------------

### Run Buggregator with Custom Config Path

Source: https://github.com/buggregator/docs/blob/master/docs/cookbook/manual-install.md

Start Buggregator using a custom configuration file path, overriding the default location.

```bash
./buggregator --config /etc/buggregator/buggregator.yaml
```

--------------------------------

### Configure Trap Server with Environment Variables

Source: https://github.com/buggregator/docs/blob/master/docs/trap/commands.md

Starts the Trap server using environment variables for port configuration and enabling the web UI. This is useful for automated deployments or CI/CD pipelines.

```bash
TRAP_TCP_PORTS=8888,9999 TRAP_UI_PORT=8080 vendor/bin/trap run --ui
```

--------------------------------

### Start Trap Server on a Specific Port

Source: https://github.com/buggregator/docs/blob/master/docs/trap/commands.md

Starts the Trap server listening on a single, specified port. Use this when you need to control which port Trap occupies.

```bash
vendor/bin/trap run -p 8000
```

--------------------------------

### Start Trap Server with Multiple Senders

Source: https://github.com/buggregator/docs/blob/master/docs/trap/commands.md

Starts the Trap server configured to use both the console and file senders. This allows debug information to be outputted to the console and saved to files simultaneously.

```bash
vendor/bin/trap run --sender=console --sender=file
```

--------------------------------

### Install Laravel XHProf Profiler Package

Source: https://github.com/buggregator/docs/blob/master/docs/config/xhprof.md

Add the XHProf Buggregator Laravel package as a development dependency using Composer.

```bash
composer require --dev maantje/xhprof-buggregator-laravel
```

--------------------------------

### Start Trap Server on Multiple Specific Ports

Source: https://github.com/buggregator/docs/blob/master/docs/trap/commands.md

Starts the Trap server listening on multiple, specified ports. This allows compatibility with various debugging tools that expect specific ports.

```bash
vendor/bin/trap run --port=8888 --port=9999
```

```bash
vendor/bin/trap run -p 8888 -p 9999
```

--------------------------------

### Install Generic PHP Profiler Package

Source: https://github.com/buggregator/docs/blob/master/docs/config/xhprof.md

Add the generic Spiral Packages profiler as a development dependency using Composer for any PHP project.

```bash
composer require --dev spiral-packages/profiler
```

--------------------------------

### Per-Page Markdown URL Example

Source: https://github.com/buggregator/docs/blob/master/docs/llm.md

Access documentation for a specific topic by using the individual page markdown URL. This is useful when you only need help with a particular integration or feature.

```text
https://docs.buggregator.dev/config/sentry.md
```

--------------------------------

### Prometheus Metrics Format Example

Source: https://github.com/buggregator/docs/blob/master/docs/config/metrics.md

This is an example of the Prometheus metrics format that Buggregator exposes. It includes help text, type information, and metric values with labels.

```plaintext
# HELP events The total number of received events.
# TYPE events counter
events{type="sentry"} 10
events{type="smtp"} 1
```

--------------------------------

### Docker Compose Configuration

Source: https://github.com/buggregator/docs/blob/master/docs/config/server.md

Example Docker Compose configuration for Buggregator, including port mappings, environment variables, and volumes.

```yaml
services:
  buggregator:
    image: ghcr.io/buggregator/server:latest
    ports:
      - 127.0.0.1:8000:8000
      - 127.0.0.1:1025:1025
      - 127.0.0.1:9912:9912
      - 127.0.0.1:9913:9913
    environment:
      DATABASE_DSN: data.db
      STORAGE_MODE: filesystem
      STORAGE_PATH: /data/storage
      METRICS_ENABLED: "true"
    volumes:
      - buggregator-data:/data

volumes:
  buggregator-data:
```

--------------------------------

### Install Spiral Framework Profiler Package

Source: https://github.com/buggregator/docs/blob/master/docs/config/xhprof.md

Add the Spiral profiler package as a development dependency using Composer for Spiral Framework integration.

```bash
composer require --dev spiral/profiler:^3.0
```

--------------------------------

### Application Connection Strings

Source: https://github.com/buggregator/docs/blob/master/docs/config/helm-chart.md

Environment variable examples for connecting various applications and logging frameworks to a deployed Buggregator instance using its Kubernetes service name.

```dotenv
# Sentry
SENTRY_LARAVEL_DSN=http://sentry@buggregator.default.svc:8000/1

# Ray
RAY_HOST=buggregator.default.svc
RAY_PORT=8000

# SMTP
MAIL_MAILER=smtp
MAIL_HOST=buggregator.default.svc
MAIL_PORT=1025

# VarDumper
VAR_DUMPER_FORMAT=server
VAR_DUMPER_SERVER=buggregator.default.svc:9912

# Monolog (SocketHandler)
LOG_CHANNEL=socket
LOG_SOCKET_URL=buggregator.default.svc:9913
```

--------------------------------

### Docker Compose for Buggregator with Projects

Source: https://github.com/buggregator/docs/blob/master/docs/config/projects.md

Set up Buggregator in Docker Compose, mounting a `buggregator.yaml` file for project configuration. This example shows how to map ports and volumes.

```yaml
services:
  buggregator:
    image: ghcr.io/buggregator/server:latest
    ports:
      - 127.0.0.1:8000:8000
    volumes:
      - ./buggregator.yaml:/buggregator.yaml
```

--------------------------------

### Build Buggregator Docker Image

Source: https://github.com/buggregator/docs/blob/master/docs/cookbook/docker-install.md

Build the Docker image for the Buggregator server. This command is part of the Docker Compose setup.

```bash
make build
```

--------------------------------

### Run Buggregator with Specific Ports for VarDumper

Source: https://github.com/buggregator/docs/blob/master/docs/getting-started.md

Start Buggregator using Docker, exposing only the ports required for the web UI and VarDumper. This minimizes the attack surface if only these features are needed.

```bash
docker run --pull always \
  -p 127.0.0.1:8000:8000 \
  -p 127.0.0.1:9912:9912 \
  ghcr.io/buggregator/server:latest
```

--------------------------------

### Inspector DSN Configuration with Project Key

Source: https://github.com/buggregator/docs/blob/master/docs/config/projects.md

Configure the Inspector URL to include the project key for routing data to the correct project. This setup is required for Inspector integration.

```dotenv
INSPECTOR_URL=http://inspector:<project_key>@127.0.0.1:8000
INSPECTOR_API_KEY=<secret_key>
```

--------------------------------

### Project Configuration in Docker Compose

Source: https://github.com/buggregator/docs/blob/master/docs/config/projects.md

Example of `buggregator.yaml` content used with Docker Compose to define projects for Buggregator. This snippet shows two distinct projects.

```yaml
projects:
  - key: backend
    name: Backend API
  - key: frontend
    name: Frontend App
```

--------------------------------

### Slack Webhook Configuration in Docker Compose

Source: https://github.com/buggregator/docs/blob/master/docs/config/webhooks.md

Example of a `buggregator.yaml` file used with Docker Compose to configure a webhook specifically for Slack, including content type header.

```yaml
webhooks:
  - event: "*"
    url: https://hooks.slack.com/services/xxx
    headers:
      Content-Type: application/json
```

--------------------------------

### Docker Compose for Buggregator Proxy Setup

Source: https://github.com/buggregator/docs/blob/master/docs/config/http-proxy.md

This Docker Compose configuration sets up the Buggregator server and an application service. The application service is configured to use the Buggregator proxy via the `BUGGREGATOR_PROXY_URL` environment variable.

```yaml
services:
  buggregator:
    image: ghcr.io/buggregator/server:latest
    ports:
      - "8000:8000"
      - "8080:8080"

  app:
    build: .
    environment:
      BUGGREGATOR_PROXY_URL: http://buggregator:8080
    depends_on:
      - buggregator
```

--------------------------------

### Install Buggregator Trap Package

Source: https://github.com/buggregator/docs/blob/master/docs/config/phpstorm-plugin.md

Install the buggregator/trap Composer package as a development dependency in your project.

```bash
composer require --dev buggregator/trap
```

--------------------------------

### Ray Host and Port Configuration with Project Key

Source: https://github.com/buggregator/docs/blob/master/docs/config/projects.md

Configure Ray host and port settings, including the project key, to direct Ray data to the correct project. This is used for Ray integration.

```dotenv
RAY_HOST=ray:<project_key>@127.0.0.1
RAY_PORT=8000
```

--------------------------------

### Download Buggregator Binary for macOS (Intel)

Source: https://github.com/buggregator/docs/blob/master/docs/cookbook/manual-install.md

Use curl to download the standalone Go binary for macOS on Intel architecture and make it executable.

```bash
# macOS (Intel)
curl -L -o buggregator https://github.com/buggregator/server/releases/latest/download/buggregator-darwin-amd64
chmod +x buggregator
```

--------------------------------

### Download Buggregator Binary for Linux (arm64)

Source: https://github.com/buggregator/docs/blob/master/docs/cookbook/manual-install.md

Use curl to download the standalone Go binary for Linux arm64 architecture and make it executable.

```bash
# Linux (arm64)
curl -L -o buggregator https://github.com/buggregator/server/releases/latest/download/buggregator-linux-arm64
chmod +x buggregator
```

--------------------------------

### Configure httpx for HTTP Proxy in Python

Source: https://github.com/buggregator/docs/blob/master/docs/config/http-proxy.md

Initialize an `httpx.Client` with the `proxy` parameter to route requests through an HTTP proxy. `verify=False` disables SSL certificate verification.

```python
import httpx

client = httpx.Client(
    proxy='http://127.0.0.1:8080',
    verify=False,
)

response = client.get('https://api.example.com/users')
```

--------------------------------

### Download Buggregator Binary for macOS (Apple Silicon)

Source: https://github.com/buggregator/docs/blob/master/docs/cookbook/manual-install.md

Use curl to download the standalone Go binary for macOS on Apple Silicon and make it executable.

```bash
# macOS (Apple Silicon)
curl -L -o buggregator https://github.com/buggregator/server/releases/latest/download/buggregator-darwin-arm64
chmod +x buggregator
```

--------------------------------

### Download Buggregator Binary for Linux (amd64)

Source: https://github.com/buggregator/docs/blob/master/docs/cookbook/manual-install.md

Use curl to download the standalone Go binary for Linux amd64 architecture and make it executable.

```bash
# Linux (amd64)
curl -L -o buggregator https://github.com/buggregator/server/releases/latest/download/buggregator-linux-amd64
chmod +x buggregator
```

--------------------------------

### Configure Ray for PHP (Any Framework)

Source: https://github.com/buggregator/docs/blob/master/docs/config/ray.md

Create a `ray.php` configuration file in your project root for non-framework specific PHP applications. This file defines Ray's connection details and behavior.

```php
<?php

return [
    'enable' => true,
    'host' => 'ray@127.0.0.1',
    'port' => 8000,
    'remote_path' => null,
    'local_path' => null,
    'always_send_raw_values' => false,
];
```

--------------------------------

### Build and Development Commands for Buggregator Server

Source: https://github.com/buggregator/docs/blob/master/docs/contributing/server.md

Provides essential commands for building, compiling, and testing the Buggregator server. Includes full build, quick compilation checks, running all tests, and executing specific tests.

```bash
# Full build (downloads frontend, builds PHP parser for VarDumper, compiles binary)
make build
```

```bash
# Quick Go compilation check
go build ./...
```

```bash
# Run all tests
go test ./...
```

```bash
# Run a single test
go test ./internal/server/http/ -run TestAPI_Version
```

```bash
# Cross-compile
make build-cross GOOS=darwin GOARCH=arm64
```

--------------------------------

### Build and Run Buggregator Directly

Source: https://github.com/buggregator/docs/blob/master/docs/cookbook/docker-install.md

Build and run the Buggregator Go binary directly on your machine, bypassing Docker. Requires Go 1.26+ and Make.

```bash
make build
make run
```

--------------------------------

### Disable Modules in buggregator.yaml

Source: https://github.com/buggregator/docs/blob/master/docs/config/server.md

Example of disabling specific Buggregator modules by setting their values to 'false' in the configuration file.

```yaml
modules:
  sentry: true
  ray: true
  var-dump: false    # Disable VarDumper
  inspector: false   # Disable Inspector
  monolog: true
  smtp: true
  sms: false         # Disable SMS
  http-dump: true
  profiler: true
```

--------------------------------

### GitHub SSO Configuration (Environment Variables)

Source: https://github.com/buggregator/docs/blob/master/docs/config/sso.md

Set up GitHub as an SSO provider using environment variables. Note that GitHub does not support OIDC discovery, so AUTH_PROVIDER_URL is not required.

```dotenv
AUTH_ENABLED=true
AUTH_PROVIDER=github
AUTH_CLIENT_ID=xxx
AUTH_CLIENT_SECRET=xxx
AUTH_CALLBACK_URL=http://<server_address>/auth/sso/callback
AUTH_JWT_SECRET=your-secret-key
```

--------------------------------

### Disable Modules via Environment Variable

Source: https://github.com/buggregator/docs/blob/master/docs/config/server.md

Example of disabling Buggregator modules by specifying enabled events in an environment variable.

```bash
CLIENT_SUPPORTED_EVENTS=sentry,ray,monolog,smtp,http-dump,profiler
```

--------------------------------

### PHP Inspector SDK Initialization

Source: https://github.com/buggregator/docs/blob/master/docs/config/inspector.md

Initialize the Inspector PHP SDK with a configuration object. Set the URL and ingestion key for connecting to Buggregator.

```php
use Inspector\Inspector;
use Inspector\Configuration;

$configuration = new Configuration('YOUR_INGESTION_KEY');
$configuration->setUrl('http://inspector@127.0.0.1:8000');
$inspector = new Inspector($configuration);
```

--------------------------------

### Docker Run with Configuration File

Source: https://github.com/buggregator/docs/blob/master/docs/config/webhooks.md

Run the Buggregator server using `docker run`, exposing the necessary port and mounting the `buggregator.yaml` file for webhook configuration.

```bash
docker run --pull always \
  -p 127.0.0.1:8000:8000 \
  -v ./buggregator.yaml:/buggregator.yaml \
  ghcr.io/buggregator/server:latest
```

--------------------------------

### Enable MCP Server via Environment Variable

Source: https://github.com/buggregator/docs/blob/master/docs/config/mcp.md

Alternatively, enable the MCP server by setting the MCP_ENABLED environment variable to true.

```bash
MCP_ENABLED=true
```

--------------------------------

### Full Documentation URL for AI Assistants

Source: https://github.com/buggregator/docs/blob/master/docs/llm.md

Use this URL to provide the complete Buggregator documentation to an AI assistant in a single file. This is recommended for most assistants to ensure they have full context.

```text
https://docs.buggregator.dev/llms-full.txt
```

--------------------------------

### PHP Symfony HttpClient Setup

Source: https://github.com/buggregator/docs/blob/master/docs/config/http-proxy.md

Configure Symfony's HttpClient to use Buggregator's proxy and disable peer/host verification for requests.

```php
use Symfony\Component\HttpClient\HttpClient;

$client = HttpClient::create([
    'proxy' => 'http://127.0.0.1:8080',
    'verify_peer' => false,
    'verify_host' => false,
]);

$response = $client->request('GET', 'https://api.example.com/users');
```

--------------------------------

### Download and Extract Trap Binary (Linux)

Source: https://github.com/buggregator/docs/blob/master/docs/trap/getting-started.md

Download the Trap binary for Linux, extract it, and make it executable. This is useful for running Trap without project dependencies.

```bash
curl -L -o trap.tar.gz https://github.com/buggregator/trap/releases/latest/download/trap-1.13.13-linux-amd64.tar.gz
tar -xzf trap.tar.gz
rm trap.tar.gz
chmod +x trap
./trap
```

--------------------------------

### Basic Webhook Configuration

Source: https://github.com/buggregator/docs/blob/master/docs/config/webhooks.md

Configure a webhook to fire on any event type and send notifications to a specified URL with optional headers and SSL verification settings.

```yaml
webhooks:
  - event: "*"                          # Fire on any event type
    url: https://slack.example.com/webhook
    headers:
      Authorization: "Bearer token123"
    verify_ssl: false
    retry: true

  - event: sentry                       # Fire only on Sentry events
    url: https://pagerduty.example.com/alert

  - event: smtp                         # Fire only on SMTP events
    url: https://my-app.example.com/email-hook
```

--------------------------------

### Measure Performance with tr()

Source: https://github.com/buggregator/docs/blob/master/docs/trap/usage.md

Use tr() to mark the start and end points for performance measurement. It reports elapsed time and memory usage between calls.

```php
// Mark the starting point
tr();

// Execute the code to measure
$result = heavyComputation();

// Mark the endpoint and see elapsed time and memory usage
tr();
```

--------------------------------

### Configure Buggregator in Docker Compose

Source: https://github.com/buggregator/docs/blob/master/docs/getting-started.md

Integrate Buggregator into your Docker Compose setup by adding its service definition. This allows it to run alongside your other application services.

```yaml
services:
  buggregator:
    image: ghcr.io/buggregator/server:latest
    ports:
      - 127.0.0.1:8000:8000
      - 127.0.0.1:1025:1025
      - 127.0.0.1:9912:9912
      - 127.0.0.1:9913:9913
```

--------------------------------

### Clone the Documentation Repository

Source: https://github.com/buggregator/docs/blob/master/docs/contributing/docs.md

Clone the Buggregator documentation repository to your local machine to begin contributing.

```bash
git clone git@github.com:buggregator/docs.git
```

--------------------------------

### PHP Guzzle HTTP Client Setup

Source: https://github.com/buggregator/docs/blob/master/docs/config/http-proxy.md

Configure Guzzle HTTP client to use Buggregator's proxy and disable SSL verification for requests.

```php
use GuzzleHttp\Client;

$client = new Client([
    'proxy' => 'http://127.0.0.1:8080',
    'verify' => false,
]);

$response = $client->get('https://api.example.com/users');
```

--------------------------------

### Install Symfony Buggregator Profiler Bundle

Source: https://github.com/buggregator/docs/blob/master/docs/config/xhprof.md

Add the Buggregator profiler bundle for Symfony as a development dependency using Composer. Note: bundle is in early development.

```bash
composer require --dev velpl/buggregator-profiler-bundle:^0.2
```

--------------------------------

### GitLab SSO Configuration (Environment Variables)

Source: https://github.com/buggregator/docs/blob/master/docs/config/sso.md

Set up GitLab as an SSO provider using environment variables. Configure the application in GitLab with the necessary scopes and redirect URI.

```dotenv
AUTH_ENABLED=true
AUTH_PROVIDER=gitlab
AUTH_PROVIDER_URL=https://gitlab.com
AUTH_CLIENT_ID=xxx
AUTH_CLIENT_SECRET=xxx
AUTH_CALLBACK_URL=http://<server_address>/auth/sso/callback
AUTH_JWT_SECRET=your-secret-key
```

--------------------------------

### Run Buggregator with Local Frontend

Source: https://github.com/buggregator/docs/blob/master/docs/cookbook/docker-install.md

Run the Buggregator server, pointing it to a locally developed frontend build. Replace '/path/to/frontend/dist' with the actual path.

```bash
FRONTEND_DIR=/path/to/frontend/dist ./buggregator
```

--------------------------------

### Auth0 SSO Configuration (Environment Variables)

Source: https://github.com/buggregator/docs/blob/master/docs/config/sso.md

Set up Auth0 as an SSO provider using environment variables. Ensure the callback URL is correctly registered in your Auth0 application settings.

```dotenv
AUTH_ENABLED=true
AUTH_PROVIDER=auth0
AUTH_PROVIDER_URL=https://<domain>.auth0.com
AUTH_CLIENT_ID=xxx
AUTH_CLIENT_SECRET=xxx
AUTH_CALLBACK_URL=http://<server_address>/auth/sso/callback
AUTH_SCOPES=openid,email,profile
AUTH_JWT_SECRET=your-secret-key
```

--------------------------------

### Enable Metrics via Configuration File

Source: https://github.com/buggregator/docs/blob/master/docs/config/metrics.md

Configure metrics to be enabled by setting 'metrics.enabled' to true in the buggregator.yaml configuration file.

```yaml
metrics:
  enabled: true
```

--------------------------------

### PHP Laravel HTTP Client Setup

Source: https://github.com/buggregator/docs/blob/master/docs/config/http-proxy.md

Configure Laravel's HTTP client to use Buggregator's proxy and disable SSL verification for requests.

```php
use Illuminate\Support\Facades\Http;

$response = Http::withOptions([
    'proxy' => 'http://127.0.0.1:8080',
    'verify' => false,
])->get('https://api.example.com/users');
```

--------------------------------

### Configure Cursor with Local MCP Server

Source: https://github.com/buggregator/docs/blob/master/docs/config/mcp.md

Configure Cursor to connect to a local MCP server using the command './buggregator mcp'.

```text
Command: ./buggregator mcp
```

--------------------------------

### Docker Compose Configuration for MCP HTTP

Source: https://github.com/buggregator/docs/blob/master/docs/config/mcp.md

Example Docker Compose configuration to run Buggregator with MCP enabled over HTTP. Ensure the MCP HTTP port is exposed.

```yaml
services:
  buggregator:
    image: ghcr.io/buggregator/server:latest
    ports:
      - 127.0.0.1:8000:8000
      - 127.0.0.1:8001:8001    # MCP HTTP port
    environment:
      MCP_ENABLED: "true"
      MCP_TRANSPORT: http
      MCP_ADDR: ":8001"
```

--------------------------------

### Twilio SMS Format via cURL

Source: https://github.com/buggregator/docs/blob/master/docs/config/sms.md

Send an SMS using the Twilio format via an HTTP POST request to Buggregator. This example demonstrates the required JSON payload structure.

```bash
# Twilio format
curl -X POST http://127.0.0.1:8000/sms/twilio \
  -H "Content-Type: application/json" \
  -d '{"MessageSid":"SM123","From":"+1234","To":"+5678","Body":"Hello!"}'
```

--------------------------------

### Run Buggregator Server with Preview Depth Limit

Source: https://github.com/buggregator/docs/blob/master/docs/config/var-dumper.md

Run the Buggregator server using Docker, setting the VAR_DUMPER_PREVIEW_MAX_DEPTH environment variable to limit the depth of nested variables displayed in the event list for performance.

```bash
docker run --pull always \
  -p 127.0.0.1:8000:8000 \
  -p 127.0.0.1:9912:9912 \
  -e VAR_DUMPER_PREVIEW_MAX_DEPTH=3 \
  ghcr.io/buggregator/server:latest
```

--------------------------------

### Configure Application Environment Variables for Buggregator

Source: https://github.com/buggregator/docs/blob/master/docs/getting-started.md

Update your application's .env file to direct debugging data to Buggregator. This example shows configurations for Sentry, Ray, VarDumper, Monolog, and SMTP.

```dotenv
# Sentry — only the host changed. Your Sentry SDK keeps working exactly the same.
SENTRY_LARAVEL_DSN=http://sentry@buggregator:8000/1

# Ray
RAY_HOST=ray@buggregator
RAY_PORT=8000

# VarDumper
VAR_DUMPER_FORMAT=server
VAR_DUMPER_SERVER=buggregator:9912

# Monolog
LOG_CHANNEL=socket
LOG_SOCKET_URL=buggregator:9913

# SMTP — email capture
MAIL_HOST=buggregator
MAIL_PORT=1025
```

--------------------------------

### Laravel HTTP SMS Sending

Source: https://github.com/buggregator/docs/blob/master/docs/config/sms.md

Example of sending SMS directly via HTTP in a Laravel application using an HTTP-based SMS package. This overrides the default API base URL to point to Buggregator.

```php
// Example: sending directly via HTTP
Http::post('http://127.0.0.1:8000/sms/twilio', [
    'MessageSid' => Str::uuid(),
    'From' => '+1234567890',
    'To' => $user->phone,
    'Body' => "Your code is {$code}",
]);
```

--------------------------------

### Getting Values Back with trap()->return()

Source: https://github.com/buggregator/docs/blob/master/docs/trap/usage.md

Use trap()->return() to dump a value and immediately return it, allowing debugging within expressions without disrupting code flow. You can also return specific named values.

```php
// Dump a value and return it immediately
$result = trap($data)->return();

// Chain operations without breaking the flow
$response = $service->process(trap($request)->return());

// Return a specific named value
$name = trap(first: $firstName, last: $lastName)->return('last');
```

--------------------------------

### JavaScript Sentry SDK Initialization

Source: https://github.com/buggregator/docs/blob/master/docs/config/sentry.md

Initialize the Sentry JavaScript SDK with the Buggregator DSN to capture frontend exceptions.

```javascript
Sentry.init({
  dsn: "http://sentry@127.0.0.1:8000/1",
});
```

--------------------------------

### Run Buggregator with Metrics Enabled (Default Endpoint)

Source: https://github.com/buggregator/docs/blob/master/docs/config/metrics.md

Run the Buggregator Docker container with metrics enabled. Metrics will be served on the main HTTP server at the /metrics endpoint.

```bash
docker run --pull always \
  -p 127.0.0.1:8000:8000 \
  -e METRICS_ENABLED=true \
  ghcr.io/buggregator/server:latest
```

--------------------------------

### Basic trap() Function Usage

Source: https://github.com/buggregator/docs/blob/master/docs/trap/getting-started.md

Demonstrates basic and named variable dumps using the trap() function in PHP.

```php
// Basic variable dump
trap($user);

// Named variable dumps
trap(id: $userId, email: $userEmail);
```

--------------------------------

### Publish Ray Configuration (Laravel)

Source: https://github.com/buggregator/docs/blob/master/docs/config/ray.md

Publish the Ray configuration file for Laravel projects. This command generates a `config/ray.php` file.

```bash
php artisan ray:publish-config
```

--------------------------------

### Configure Cursor with Remote MCP Server (HTTP)

Source: https://github.com/buggregator/docs/blob/master/docs/config/mcp.md

Configure Cursor to connect to a remote MCP server using its HTTP URL.

```text
http://localhost:8001/mcp
```

--------------------------------

### Run Buggregator with Docker and Environment Variables

Source: https://github.com/buggregator/docs/blob/master/docs/getting-started.md

Use this command to run the latest stable release of Buggregator. It maps port 8000, sets the database DSN, enables metrics, and mounts a local data directory.

```bash
docker run --pull always \
  -p 127.0.0.1:8000:8000 \
  -e DATABASE_DSN=data.db \
  -e METRICS_ENABLED=true \
  -v ./data:/data \
  ghcr.io/buggregator/server:latest
```

--------------------------------

### Generic OIDC SSO Environment Variables

Source: https://github.com/buggregator/docs/blob/master/docs/config/sso.md

Configure these environment variables to enable and set up SSO with a generic OIDC provider. Ensure the callback URL matches your provider's configuration.

```dotenv
AUTH_ENABLED=true
AUTH_PROVIDER=oidc
AUTH_PROVIDER_URL=https://your-oidc-provider.com
AUTH_CLIENT_ID=xxx
AUTH_CLIENT_SECRET=xxx
AUTH_CALLBACK_URL=http://<server_address>/auth/sso/callback
AUTH_JWT_SECRET=your-secret-key
```

--------------------------------

### Enable MCP Server

Source: https://github.com/buggregator/docs/blob/master/docs/config/mcp.md

Enable the MCP server by setting 'enabled' to true in your buggregator.yaml configuration file.

```yaml
mcp:
  enabled: true
```

--------------------------------

### Configure Projects in buggregator.yaml

Source: https://github.com/buggregator/docs/blob/master/docs/config/projects.md

Define projects with unique keys and names in the `buggregator.yaml` file. This allows for data organization and separation.

```yaml
projects:
  - key: my-app
    name: My Application
  - key: staging
    name: Staging Environment
  - key: mobile
    name: Mobile App
```

--------------------------------

### Go HTTP Client with Proxy and Insecure Skip Verify

Source: https://github.com/buggregator/docs/blob/master/docs/config/http-proxy.md

Configure Go's http.Client to use a proxy and disable SSL certificate verification for HTTPS requests.

```go
import (
    "crypto/tls"
    "net/http"
    "net/url"
)

proxyURL, _ := url.Parse("http://127.0.0.1:8080")

client := &http.Client{
    Transport: &http.Transport{
        Proxy:           http.ProxyURL(proxyURL),
        TLSClientConfig: &tls.Config{InsecureSkipVerify: true},
    },
}

resp, err := client.Get("https://api.example.com/users")
```

--------------------------------

### trap() Function with Return and Depth

Source: https://github.com/buggregator/docs/blob/master/docs/trap/getting-started.md

Shows how to dump a value and continue using it with ->return(), and how to set the dump depth for nested objects.

```php
// Dump and continue using the value
$response = trap($api->getResponse())->return();

// Set dump depth for nested objects
trap($complexObject)->depth(3);
```

--------------------------------

### Set File-Based Database via Environment Variable

Source: https://github.com/buggregator/docs/blob/master/docs/config/database.md

Alternatively, set the database data source name (DSN) using the DATABASE_DSN environment variable for file-based persistence.

```bash
DATABASE_DSN=data.db
```

--------------------------------

### Enable Metrics via Environment Variable

Source: https://github.com/buggregator/docs/blob/master/docs/config/metrics.md

Set the METRICS_ENABLED environment variable to true to enable metrics collection.

```bash
METRICS_ENABLED=true
```

--------------------------------

### SQLite In-Memory Database Configuration

Source: https://github.com/buggregator/docs/blob/master/docs/config/database.md

Use this configuration for the fastest option when data persistence across restarts is not required. This is the default setting.

```yaml
database:
  dsn: ":memory:"
```

--------------------------------

### Ingress Configuration with TLS

Source: https://github.com/buggregator/docs/blob/master/docs/config/helm-chart.md

YAML configuration for enabling Ingress with TLS termination for Buggregator. Assumes cert-manager is used for certificate management.

```yaml
ingress:
  enabled: true
  className: nginx
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod
  hosts:
    - host: buggregator.example.com
      paths:
        - path: /
          pathType: Prefix
  tls:
    - secretName: buggregator-tls
      hosts:
        - buggregator.example.com
```

--------------------------------

### Google SSO Configuration (Environment Variables)

Source: https://github.com/buggregator/docs/blob/master/docs/config/sso.md

Configure Google as an SSO provider using environment variables. Register your callback URL in the Google Cloud Console's OAuth 2.0 Client ID settings.

```dotenv
AUTH_ENABLED=true
AUTH_PROVIDER=google
AUTH_PROVIDER_URL=https://accounts.google.com
AUTH_CLIENT_ID=xxx.apps.googleusercontent.com
AUTH_CLIENT_SECRET=xxx
AUTH_CALLBACK_URL=http://<server_address>/auth/sso/callback
AUTH_JWT_SECRET=your-secret-key
```

--------------------------------

### Run Buggregator Standalone Binary on Other Platforms

Source: https://github.com/buggregator/docs/blob/master/docs/getting-started.md

Download and execute the Buggregator binary for different operating systems and architectures. Ensure the binary is executable after download.

```bash
# Linux (arm64)
curl -sL https://github.com/buggregator/server/releases/latest/download/buggregator-linux-arm64 -o buggregator \
  && chmod +x buggregator

# macOS (Apple Silicon)
curl -sL https://github.com/buggregator/server/releases/latest/download/buggregator-darwin-arm64 -o buggregator \
  && chmod +x buggregator

# macOS (Intel)
curl -sL https://github.com/buggregator/server/releases/latest/download/buggregator-darwin-amd64 -o buggregator \
  && chmod +x buggregator
```

--------------------------------

### SQLite File-Based Database Configuration

Source: https://github.com/buggregator/docs/blob/master/docs/config/database.md

Configure a file path to persist database data across server restarts. The database file will be created next to the binary or at the specified path.

```yaml
database:
  dsn: data.db
```

--------------------------------

### Stack Trace Inspection with trap()

Source: https://github.com/buggregator/docs/blob/master/docs/trap/usage.md

Add the current stack trace to your dump using trap()->stackTrace() to visualize the execution path leading to the dump.

```php
// Add stack trace to your dump to see the execution flow
trap()->stackTrace();

// Dump a variable along with the stack trace
trap($result)->stackTrace();
```

--------------------------------

### Syntax Highlighting with Buggregator Trap

Source: https://github.com/buggregator/docs/blob/master/docs/config/var-dumper.md

Use the trap() helper from Buggregator Trap to dump text strings with syntax highlighting. Specify the language in the context() method.

```php
$code = <<<PHP
<?php

declare(strict_types=1);

echo 'Hello, World!';
PHP;

trap($code)->context(language: 'php');
```

--------------------------------

### Docker Run Command for Persistent Database

Source: https://github.com/buggregator/docs/blob/master/docs/config/database.md

When running in Docker, mount a volume to the specified path to ensure the database file persists across container restarts.

```bash
docker run --pull always \
  -p 127.0.0.1:8000:8000 \
  -e DATABASE_DSN=/data/buggregator.db \
  -v buggregator-data:/data \
  ghcr.io/buggregator/server:latest
```