GeezerVison

Welcome to d8a.tech! This guide will help you get up and running with d8a, an open-source clickstream analytics platform that's fully compatible with GA4 tracking protocols.

Cloud option available

You can start with our free cloud option. Visit the signup page to create an account. After setting up your account, you can proceed directly to step 4.

Docker + ClickHouse
Local binary + CSV files

Prerequisites:

Basic Unix knowledge (creating files, directories, etc.)
Unix shell (Linux, macOS, WSL, etc.)
Docker installed with the docker compose command

Prerequisites: Prerequisites:

Basic Unix knowledge (creating files, directories, etc.)
Unix shell (Linux, macOS, WSL, etc.)
curl and tar installed locally

Step 1: Create a configuration file

First, create a config file (you can learn more about the configuration options in the configuration reference):

Docker + ClickHouse
Local binary + CSV files

cat > config.yaml <<EOF
sessions:
  timeout: 10s # Adjust this after the testing phase to a production value

warehouse:
  driver: clickhouse
  clickhouse:
    host: clickhouse
    port: "9000"
    database: d8a
    username: default
    password: "verySecuredD8aDatabase"

protocol: ga4 # Set to 'd8a' when using the d8a web tracker and the /d/c endpoint
EOF

cat > config.yaml <<EOF
storage:
  bolt_directory: ./state/bolt
  queue_directory: ./state/queue
  spool_enabled: true
  spool_directory: ./state/spool

currency:
  destination_directory: ./state/currency

sessions:
  timeout: 10s # Adjust this after the testing phase to a production value

warehouse:
  driver: files
  files:
    format: csv
    storage: filesystem
    max_segment_age: 1m
    filesystem:
      path: ./csv-out

protocol: ga4 # Set to 'd8a' when using the d8a web tracker and the /d/c endpoint
EOF

note

If you'd like to use a different storage, please check the warehouses article.

Step 2: Prepare the runtime

Docker + ClickHouse
Local binary + CSV files

cat > docker-compose.yml <<EOF
services:
  clickhouse:
    image: clickhouse/clickhouse-server:latest
    container_name: clickhouse
    restart: unless-stopped
    ports:
      - "8123:8123"  # HTTP interface
      - "9000:9000"  # Native protocol
    volumes:
      - clickhouse-data:/var/lib/clickhouse
    environment:
      - CLICKHOUSE_DB=d8a
      - CLICKHOUSE_USER=default
      - CLICKHOUSE_PASSWORD=verySecuredD8aDatabase
    networks:
      - d8a-network

  d8a:
    image: ghcr.io/d8a-tech/d8a:latest
    container_name: d8a
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - ./config.yaml:/config.yaml:ro
      - d8a-data:/storage
    command: server --config /config.yaml
    networks:
      - d8a-network
    depends_on:
      - clickhouse

networks:
  d8a-network:
    driver: bridge

volumes:
  d8a-data:
  clickhouse-data:
EOF

# Resolve latest release version
LATEST_URL=$(curl -fsSL -o /dev/null -w '%{url_effective}' https://github.com/d8a-tech/d8a/releases/latest)
VERSION=${LATEST_URL##*/}

# Detect local platform
OS=$(uname -s | tr '[:upper:]' '[:lower:]')
ARCH=$(uname -m)

case "$ARCH" in
  x86_64) ARCH=amd64 ;;
  aarch64|arm64) ARCH=arm64 ;;
  *) echo "Unsupported architecture: $ARCH"; exit 1 ;;
esac

case "$OS" in
  linux|darwin) ;;
  *) echo "Unsupported operating system: $OS"; exit 1 ;;
esac

# Prepare local directories
mkdir -p ./state/bolt ./state/queue ./state/spool ./csv-out ./tmp

# Download and unpack d8a
curl -L "https://github.com/d8a-tech/d8a/releases/download/${VERSION}/d8a_${VERSION#v}_${OS}_${ARCH}.tar.gz" -o ./tmp/d8a.tar.gz
tar -xzf ./tmp/d8a.tar.gz -C ./tmp
chmod +x ./tmp/d8a

Step 3: Start the application

Finally, start d8a:

Docker + ClickHouse
Local binary + CSV files

docker compose up -d
docker compose logs -f

Your d8a instance should be available at http://localhost:8080. You may now send a test tracking request to your d8a instance:

curl "http://localhost:8080/g/collect?v=2&tid=14&dl=https%3A%2F%2Ffoo.bar&en=page_view&cid=ag9" -X POST

Wait about 10 seconds and then check your clickhouse for saved session.

./tmp/d8a server --config config.yaml

Your d8a instance should be available at http://localhost:8080. You may now send a test tracking request to your d8a instance:

curl "http://localhost:8080/g/collect?v=2&tid=14&dl=https%3A%2F%2Ffoo.bar&en=page_view&cid=ag9" -X POST

Wait about two minutes and then check ./csv-out for generated CSV files.

Your d8a server setup is now complete. If you'd like to hook up a domain and use SSL, you need a reverse proxy like Nginx. You can find resources for setting up reverse proxies in the Nginx documentation or Apache HTTP Server documentation.

Step 4: Set up tracking

After d8a is up and running, the next step is to send tracking traffic to your d8a endpoint. This allows you to capture analytics data using your own infrastructure while maintaining compatibility with GA4 tracking protocols.

We recommend starting with Intercepting GA4 events. If that approach does not fit your setup, you can choose another integration option from the Sources section in the sidebar.

Next steps

After completing all the steps:

Verify that events are being received by your d8a instance in the warehouse of your choice
For BigQuery, you can copy the official Data Studio dashboard
For the local CSV option, review the generated files in ./csv-out
For the files warehouse driver, review the files warehouse driver guide for upload destination options (S3/MinIO, GCS, or local filesystem)
Review the database schema to understand the data structure

GeezerVison

Step 1: Create a configuration file​

Step 2: Prepare the runtime​

Step 3: Start the application​

Step 4: Set up tracking​

Next steps​

Step 1: Create a configuration file

Step 2: Prepare the runtime

Step 3: Start the application

Step 4: Set up tracking

Next steps