Local

This guide will help you quickly set up Qpoint locally using Docker to start capturing and analyzing your service connections within minutes.

Before getting started, we recommend checking the system requirements for details on Qtap compatibility. If you'd like to automatically verify your environment's compatibility, use the following:

curl -sSL https://github.com/qpoint-io/preflight/releases/latest/download/preflight.sh | bash

Prerequisites

• A Linux host with kernel 5.10+ (check with uname -r)

• Docker installed

• Permissions to run privileged containers

Step 1: Create a Simple Qpoint Configuration File

# Create a directory for your configuration
mkdir -p ~/qpoint-demo/config

# Create the configuration file
cat > ~/qpoint-demo/config/qpoint.yaml << 'EOF'
version: 2

services:
  event_stores:
    - id: console_stdout
      type: stdout
  
  object_stores:
    - id: console_stdout
      type: stdout

stacks:
  default_stack:
    plugins:
      - type: debug
        config:
          mode: summary
      - type: detect_errors
        config:
          rules:
            - name: "All Errors"
              trigger_status_codes:
                - '4xx'
                - '5xx'
              report_as_issue: true
              record_req_headers: true
              record_req_body: true
              record_res_headers: true
              record_res_body: true

tap:
  direction: egress
  ignore_loopback: false
  audit_include_dns: true
  http:
    stack: default_stack
EOF

Step 2: Run the Qpoint Tap Agent

Now, deploy the Qtap agent:

docker run -d \
  --name qpoint-tap \
  --user 0:0 \
  --privileged \
  --cap-add CAP_BPF \
  --cap-add CAP_SYS_ADMIN \
  --pid=host \
  --network=host \
  -v /sys:/sys \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v ~/qpoint-demo/config:/app/config \
  -e TINI_SUBREAPER=1 \
  --ulimit=memlock=-1 \
  us-docker.pkg.dev/qpoint-edge/public/qpoint:v0 \
  tap \
  --log-level=info \
  --log-encoding=console \
  --config=/app/config/qpoint.yaml

Step 3: Generate Some Test Traffic

Let's create some test traffic to see Qpoint in action:

# Create a test container and send HTTP requests
docker run --rm --name test-client curlimages/curl \
  sh -c "curl -v https://httpbin.org/get && \
         curl -v https://httpbin.org/status/404 && \
         curl -v https://httpbin.org/status/500"

Step 4: View the Captured Traffic

Check the Qtap logs to see the traffic being captured:

docker logs qpoint-tap

You should see log entries showing:

• Connection details (source, destination, protocol)

• HTTP request and response metadata

• Full request and response payloads in the console

• Error information for the 404 and 500 responses

Example output snippet:

===================================================================
curl → GET https://httpbin.org/status/500 503 Service Unavailable
===================================================================

------------------ META ------------------
PID: 194603
Exe: /usr/bin/curl
Container ID: 6f4fccfae3f7
Direction: egress-external
Bytes Sent: 46
Bytes Received: 232

------------------ REQUEST ------------------
GET httpbin.org http2
Accept: */*
Qpoint-Request-Id: cvct1q87p3qj89ieqtlg
:authority: httpbin.org
:method: GET
:path: /status/500
:scheme: https
User-Agent: curl/8.12.1

------------------ RESPONSE ------------------
503 Service Unavailable
:status: 503
Server: awselb/2.0
Date: Tue, 18 Mar 2025 20:00:41 GMT
Content-Type: text/html
Content-Length: 162

Step 5: Test Specific Use Cases

Now that Qpoint is running, you can try various use cases to see more capabilities:

Capture API Authentication Issues

# Test missing or invalid API key
docker run --rm --name test-auth curlimages/curl \
  -v https://httpbin.org/bearer -H "Authorization: Bearer invalid-token"

Monitor Third-Party API Health

# Create a loop to periodically check an API
docker run --rm --name test-health curlimages/curl \
  sh -c "for i in {1..5}; do curl -s https://httpbin.org/status/200,200,200,500 > /dev/null; sleep 2; done"

Track Slow Responses

# Test a delayed response
docker run --rm --name test-delay curlimages/curl \
  https://httpbin.org/delay/2