Skip to main content

Getting started

Welcome to Divine Data (d8a)! 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.

Prerequisites:

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

Step 1: Create a configuration file​

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

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
note

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

Step 2: Prepare the runtime​

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

Step 3: Start the application​

Finally, start d8a:

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.

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 Looker 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